Field-level Encryption

⚠️

Card Present Gateway

If you want to access information about our in-store offering, you may check the API specifications here: In-store Transactions Overview

Cards Connect uses field-level encryption (FLE) to secure sensitive fields within the API request payloads (such as within the authorization request). This ensures that data like card and billing details are protected if intercepted during transit.
For example, the cardDetails and billingDetails JSON objects in the authorization request must be encrypted.

Encryption Overview

The encryption process follows the JSON Web Encryption (JWE) standard. Instead of sending the naked JSON objects, you will send a JWE token containing the encrypted data. For example, the cardDetails object is encrypted and sent in the cardDetailsEncrypted field.

The entire process can be broken down into three steps.

How to Encrypt Data

Step 1: Retrieve and Manage the Public Key

You must first fetch the Cards Connect public key, which is used to encrypt the data.

• Endpoint: The current public key is always available at the /keys/current/public API endpoint.
• Key Rotation: A new key is generated frequently (currently on a weekly basis). The key response includes an expiry element which denotes the date and time the key will be retired.
• Caching: You could cache the public key and reuse it for encryption until its expiry. Once the key has expired, you must fetch the new key from the endpoint to ensure successful transactions.
• Grace Period: To prevent failures during key rotation, Cards Connect provides a grace period. Decryption using a retired key is supported after it is no longer the "current" key. This allows any in-flight transactions to be processed successfully.

Step 2: Generate the JWE Token

Using a standard JSON Web Token (JWT) library, generate a JWE token by encrypting the sensitive JSON objects (cardDetails or billingDetails).
Use the public key retrieved in Step 1 with the following JWE algorithm parameters:

• Key Exchange Algorithm (alg): ECDH-ES+A256KW
• Content Encryption Algorithm (enc): A256GCM

Step 3: Submit the Encrypted Request

In your authorization request body, replace the original JSON object with the generated JWE token. The token should be placed in the corresponding ...Encrypted field (e.g., place the encrypted cardDetails object into the cardDetailsEncrypted field).