Skip to content

Retrieving a Card

A method for retrieving a card token by a completed transaction.

URL

Method: GET

  • Production: https://api.pay.kvell.group/v1/customers/{customer_key}/orders/{transaction}
  • Stage: https://api.pay.stage.kvell.group/v1/customers/{customer_key}/orders/{transaction}

Request parameters

Name Data type Required Description
customer_key string Yes Customer identifier in the merchant's system
transaction string Yes Unique transaction number on the merchant's side

Request headers

Name Data type Required Description
X-Api-Key string Yes Unique shop identifier
X-Signature string Yes Signature

The X-Signature signature is generated by concatenating X-Api-Key, customer_key, and secret_key. sha256 is computed from the resulting string:

sha256({x-api-key}{transaction}{customer_key}{secret_key})

where secret_key is the secret key found in the merchant's shop settings.

Response

Response parameters

Name
 Data type Description
customer_id integer Customer identifier in the system
token string Linked card token
pan_mask string Masked card number
holder string Cardholder name
expire string Card expiration date in YYYY-MM format
created_at string Creation date
pan_hash_encrypted string Encrypted card hash sha256(pan), encrypted with the shop's public key, in base64 format

Response example

{
  "customer_id": 25,
  "token": "4VNSbS7nF410G8WLEhUUUnflH2UKvWlHxIzN3Jr9JJs",
  "pan_mask": "411111******1111",
  "holder": "IVAN IVANOV",
  "expire": "2028-12",
  "created_at": "2023-11-30T07:52:29.720321Z",
  "pan_hash_encrypted": "EPNS42BPO6yazHvd6BKd...ObPg6EKv7mYKUy7zc8s="
}

{
  "errors": [
    {
      "message": "string",
      "code": 0
    }
  ]
}

Code examples

from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization, hashes
import base64

# Read the private key from a PEM file
with open("private_key.pem", "rb") as key_file:
    private_key = serialization.load_pem_private_key(
        key_file.read(),
        password=None
    )

# Example of an encrypted SHA256(PAN) (in base64)
encrypted_base64 = "base64_string_of_pan_hash_encrypted"
encrypted_bytes = base64.b64decode(encrypted_base64)

# Decryption using RSA-OAEP + SHA256
decrypted = private_key.decrypt(
    encrypted_bytes,
    padding.OAEP(
        mgf=padding.MGF1(algorithm=hashes.SHA256()),
        algorithm=hashes.SHA256(),
        label=None
    )
)

print("Decrypted SHA256(PAN):", decrypted.decode())

const forge = require('node-forge');
const fs = require('fs');

// Read the private key from a PEM file
const privateKeyPem = fs.readFileSync('privatekey.pem', 'utf8');
const privateKey = forge.pki.privateKeyFromPem(privateKeyPem);

// Example of an encrypted SHA256(PAN) (in base64)
const encryptedBase64 = 'base64_string_of_pan_hash_encrypted';
const encryptedBytes = forge.util.decode64(encryptedBase64);

// Decryption using RSA-OAEP + SHA256
const decryptedBytes = privateKey.decrypt(encryptedBytes, 'RSA-OAEP', {
  md: forge.md.sha256.create(),
  mgf1: {
    md: forge.md.sha256.create()
  }
});

console.log("Decrypted SHA256(PAN):", decryptedBytes);