Real-Time Loon Encryption
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:
Key Type | KeyAsBase64 | Key Id (KID) |
---|---|---|
RequestEncryptionKey | YWJjZGVmMTIzNDU2Nzg5YWJjZGVmMTIzNDU2Nzg5MQo= | merchant-1-uuid-pagos-bound |
ResponseDecryptionKey | QWJjRGVmMTIwNDU2Nzg5QWJjRGVmLTEyNDU2NzgwMAo= | merchant-1-uuid-merchant-bound |
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"
}
}
Updated 5 months ago