In the JSON payload you send to Real-Time Loon for updates, you must encrypt sensitive account details as a JWE token. To do so, you’ll use a RequestEncryptionKey to encrypt account details in an accountEncrypted section of your request to Real-Time Loon. Note that this must happen before calculating the authentication header.

The response Pagos returns will similarly be encrypted as a JWE token; you’ll decrypt the response using your ResponseDecryptionKey.

Encryption Algorithm

Use the algorithm A256GCMKW to encrypt your payload. This is a key-wrapped, symmetric encryption, supported by most common jose-jwt libraries. Your request JWE header should include your KeyId, otherwise known as a kid.

Encryption Keys

When onboarding with Real-Time Loon, reach out to Pagos during your implementation to request your encryption keys. You’ll be issued two encryption keys—RequestEncryptionKey and ResponseDecryptionKey—and the accompanying Key Id (KID) with the following details:

• Key size: 256 bit
• Algorithm: A256GCMKW
• Encryption: A256GCM

Your keys will follow the format of these examples:

Request Encryption Example

You want to send the following example payload for updates:

{
  "network": "visa",
  "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500",
  "account": {
      "accountNumber": "4025000000001002",
      "expiryYear": "2024",
      "expiryMonth": "09",
      "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
  },
  "subMerchantId": null
}

To do so, you start by encrypting the account object with your RequestEncryptionKey. Use the JWE token produced from the encryption process as the value for the accountEncrypted key in the payload you will send to Pagos.

Your HTTP client will then send the following encrypted payload to Pagos for updates:

{
  "network": "visa",
  "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500",
  "accountEncrypted": "eyJhbGciOiJBMjU-some-jwe-token...",
  "subMerchantId": null
}

Response Decryption Example

When receiving a response from Real-Time Loon, decrypt the accountEncrypted section with your ResponseDecryptionKey.

You receive the following example response from Real-Time Loon:

{
  "code": 200,
  "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500",
  "accountEncrypted": "eyJhbGciOiJBMjU-some-jwe-token..."
}

You will then decrypt the JWE token in the value of the accountEncrypted key. Your response will now be decrypted into the following account object:

  "account": {
    "accountNumber": "4025000000001002",
    "expiryYear": "2024",
    "expiryMonth": "09",
    "newAccountNumber": "4025000000001102",
    "newExpiryYear": null,
    "newExpiryMonth": null,
    "responseCode": "LAE",
    "errorCode": null,
    "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
  }

Resulting in the full decrypted response message:

{
  "code": 200,
  "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500",
  "account": {
    "accountNumber": "4025000000001002",
    "expiryYear": "2024",
    "expiryMonth": "09",
    "newAccountNumber": "4025000000001102",
    "newExpiryYear": null,
    "newExpiryMonth": null,
    "responseCode": "LAE",
    "errorCode": null,
    "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
  }
}