Card Issuing & Management
Secure Card Data
This page explains the secure-data flow used to deliver sensitive card information to the cardholder’s device using encrypted payloads. This flow is used when your system needs to deliver actual secure card data, such as PAN, CVV, or PIN, through a protected end-to-end process.
Overview
Secure card data flows are used when the cardholder needs to view sensitive card information through the client experience. Because this information can include PAN, CVV, or PIN, it must be handled as sensitive data throughout the full delivery and display flow.
Payblr returns secure card data through encrypted payloads. Your system is responsible for delivering the payload through a protected cardholder experience and ensuring sensitive values are not exposed outside the intended flow.
Recommended flow
Use the following flow when delivering secure card data to the cardholder device.
Generate a session key
Create a local AES-256 session key in the client app or device and keep it private.
Encrypt the session key
Encrypt the AES session key with Payblr’s RSA-4096 wrap public key using RSA OAEP padding.
Request secure card data
Send the secure-data request to Payblr with the encrypted session key.
Decrypt locally
Decrypt the returned encrypted card data using the local session key on the device.
Secure Card Data Sequence Diagram
Recommended secure-data delivery sequence
Pre-requisites
Device
Client App / Device
Backend
Client Backend
Platform
Payblr
1. Generate AES-256 session key
The client app or device generates a local AES-256 session key for encrypting secure card data.
2. Keep private session key locally
The session key stays private to the device and is never exposed outside the secure card data flow.
3. Encrypt session key
The client app or device encrypts the AES session key with Payblr’s RSA-4096 wrap public key using RSA OAEP padding.
4. Base64-encode encrypted session key
The encrypted session key is encoded for transport in the secure-data request.
5. Send encrypted session key
The client app or device sends the encrypted session key to the client backend for the secure-data call.
6. Request secure card data
Sensitive dataEndpoint
Get Card DataMethod
POST /program-manager/thr/cards/{publicToken}/encryptedThe client backend sends the secure-data request to Payblr with the encrypted session key.
7. Decrypt session key
Payblr decrypts the session key using its private RSA key before encrypting the card data payload.
8. Encrypt card data
Sensitive dataEndpoint
Get Card DataPayblr uses the session key to encrypt the card data and return the payload.
9. Return encrypted card data
The client backend forwards the encrypted secure card data to the client app or device.
10. Decrypt returned data
The client app or device decrypts the secure card data using the local AES session key.
API sequence
The following sequence summarizes the API activity involved in secure card data delivery.
| Order | API activity | Purpose | Output / next action |
|---|---|---|---|
| 1 | Get Card Data | Request encrypted secure card data for display to the cardholder. | Deliver the encrypted payload through the protected cardholder experience. |
| 2 | Display securely | Show the requested secure card information only within the intended cardholder flow. | Clear or hide sensitive information when the display flow ends. |
Request pattern
POST /program-manager/thr/cards/{publicToken}/encrypted
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
{
"key": "[BASE64_ENCODED_ENCRYPTED_KEY]",
"paddingMode": "PKCS2_2",
"encryptionKeyLength": "Rsa4096",
"hashingAlgorithm": "Sha256"
}Request fields
The following table describes fields that can be included in the body of the request when getting encrypted data.
| Field | Description | Min Length | Max Length | Type | Mandatory |
|---|---|---|---|---|---|
key | The base64 encoded, encrypted key. | 0 | 2147483648 | string | Yes |
paddingMode | The padding mode used to encrypt the AES key that is generated. This tells us how to decrypt the AES key. This can only be PKCS2_2. | 0 | 7 | string | No |
encryptionKeyLength | The length of the public RSA wrapping key. This can only be Rsa4096. | 0 | 7 | string | No |
hashingAlgorithm | The MGF hash function used when importing the key. This can only be Sha256. | 0 | 6 | string | No |
Response fields
| Field | Description | How your system uses it |
|---|---|---|
iv | Initialization vector returned with the encrypted response. | Use it with the original AES session key to decrypt the encrypted payload. |
encryptedPayload | Encrypted card data returned by Payblr. | Decrypt it on the client side using the original AES session key and returned iv. |
signatureOfPayloadAndIv | Signature used to validate the encrypted payload and IV. | Verify the response signature using the applicable Payblr Signing Public Key before trusting the response. |
Creating an AES key
Unique per request
Generate a new AES-256 session key for every secure-data request.
Minimum strength
The AES key must be no smaller than 256 bits.
Client-side control
Keep the original AES session key on the cardholder device or secure client application.
Example AES key generation
Example Python — Generate AES key
import os, json, base64
from cryptography.hazmat.primitives import hashes, serialization, padding as sym_padding
from cryptography.hazmat.primitives.asymmetric import padding as asym_padding
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.exceptions import InvalidSignature
def get_card_data(public_token, wrap_pub_pem, sign_pub_pem, send_request):
# 1. Fresh AES-256 session key
aes_key = os.urandom(32)Example Node.js — Generate AES key
const crypto = require('crypto');
async function getCardData(publicToken, wrapPubPem, signPubPem, sendRequest) {
const aesKey = crypto.randomBytes(32);
}Security handling requirements
This secure-data flow protects sensitive card data in transit, but it does not by itself authenticate the device or verify the identity of the cardholder.
- Apply device trust checks before allowing secure-data access.
- Authenticate the cardholder before initiating the secure-data flow.
- Authorize the requested secure-data action before sending the request.
- When operating outside PCI DSS scope, key generation, encryption, and decryption should happen on the cardholder device or secure client application.
- Only encrypted data should be sent to backend systems. Backend services should never receive or process clear sensitive card data in this model.
Implementation notes
Before implementing secure card data, confirm the encryption, device delivery, display, and data handling expectations for the client implementation.
- Treat secure card data as highly sensitive and display it only in protected cardholder flows.
- Do not log PAN, CVV, PIN, decrypted values, encrypted payload contents, or sensitive response data.
- Do not store secure card data in browser storage, screenshots, analytics tools, or client-side logs.
- Use the API Explorer to confirm the exact request method, URL, required headers, and payload fields.
- Limit the visibility of secure card data in the user interface and clear it when the session or display window ends.
Do not log sensitive values
Logs must not include PAN, CVV, PIN, decrypted values, or encrypted payload contents. Keep troubleshooting data limited to non-sensitive identifiers.
Keep display controlled
Display secure card data only to the authenticated cardholder and only for the intended flow or session window.
Next steps
After implementing secure card data, continue with card renewal and replacement documentation as needed for your cardholder lifecycle.