Secure Card Data

Payblr supports a secure-data flow for retrieving and handling sensitive card information using an encryption approach. This flow is available whether your organization is PCI DSS certified or not, but it must be implemented correctly to keep sensitive data protected end-to-end.

How it works

Payblr supports secure-data operations using two RSA keys:

Signature RSA key
Used only to verify the response signature. It is not used for encryption.

Payblr RSA public key
Used to encrypt the AES session key that protects the secure data exchange.

Secure-data requests use the following encryption model:

1. The client application or device generates a new AES-256 session key for the request.

2. That session key must be unique per request and kept securely on the client side.

3. The client encrypts the AES session key using the Payblr RSA public key.

4. The encrypted AES key is Base64-encoded and sent in the request.

5. Payblr returns the requested data in encrypted form.

6. The client uses the original AES session key to verify and decrypt the response.

How to implement

1. Generate a new AES-256 session key on the cardholder device or secure client application.

2. Encrypt the AES session key using the Payblr RSA public key.

3. Base64-encode the encrypted AES key and include it in the request body as the required key field.

4. Send a POST request to /api/v1/cards/{publicToken}/encrypted, including the target card’s publicToken in the path.

5. Add optional cryptographic parameters only when needed:

   • paddingMode

   • encryptionKeyLength

   • hashingAlgorithm

6. Receive the encrypted response, which includes:

   • iv

   • encryptedPayload

   • signatureOfPayloadAndIv

7. Verify the response signature by validating the concatenated encrypted payload + IV with the appropriate signature verification key.

8. Decrypt encryptedPayload using the original AES session key and the returned iv.

Request Fields

Important security considerations

This secure-data flow protects sensitive data in transit, but it does not by itself authenticate the device or verify the identity of the device holder. For that reason, Payblr strongly recommends that clients implement their own policy-based controls, such as device trust checks, user authentication, and other authorization safeguards before allowing secure-data access.

PCI DSS responsibility

If your organization is not PCI DSS certified, all key generation, encryption, and decryption must happen on the device.

Only encrypted data should ever be sent to backend systems. In other words, backend services should never receive or process clear sensitive card data in this model.

Important notes

• Do not use the signature RSA key for encryption. It is only intended for verification.

• Use a new session key for every request. Reusing keys weakens the security model.

• Keep the session key only where it is needed to decrypt the response.

• Ensure only the encrypted session key is transmitted as part of the request body.

• Ensure backend services only handle encrypted payloads when operating outside PCI DSS scope.

Summary

In Payblr’s secure-data model, the client device generates a one-time AES-256 session key, encrypts that key with the Payblr RSA public key, sends the encrypted key with the request, and then uses the session key to decrypt the secure response. This design helps reduce exposure of sensitive card data, especially when implemented so that only encrypted data reaches backend systems.