In the JSON payload you send to Real-Time Account Updater 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 Account Updater. 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

Real-Time Account Updater requires request and response encryption keys, along with a Key ID (KID) for each. To generate them:

1

Click your profile icon at the bottom of the main navigation.

2

Under Developers, click API Keys.

3

Click the Action API tab.

4

Under Real-Time Account Updater Encryption Keys, click Create Encryption Keys. A side panel will open containing the new Request and Response key pairs values.

5

Copy your new key pairs and store them somewhere secure. You can only view these values one time.

6

Click I’ve Copied My Keys to confirm and exit out of the side panel.

Your keys will follow the format of these examples:

Key TypeKeyAsBase64Key Id (KID)
RequestEncryptionKeyYWJjZGVmMTIzNDU2Nzg5YWJjZGVmMTIzNDU2Nzg5MQo=merchant-1-uuid-pagos-bound
ResponseDecryptionKeyQWJjRGVmMTIwNDU2Nzg5QWJjRGVmLTEyNDU2NzgwMAo=merchant-1-uuid-merchant-bound

Each accompanying Key Id (KID) will have the following details:

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

​
Request Encryption Example

You want to send the following example payload for updates:

{
    "network": "visa",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "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": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "subMerchantId": null,
    "accountEncrypted": "eyJ...-Q"
}

​
Response Decryption Example

When receiving a response, decrypt the accountEncrypted section with your ResponseDecryptionKey.

You receive the following example response:

{
    "accountEncrypted": "eyJ...qg",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09"
}

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:

{
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "newAccountNumber": "4166676667666746",
        "newExpiryYear": null,
        "newExpiryMonth": null,
        "responseCode": "LAE",
        "errorCode": null,
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    }
}

Resulting in the full decrypted response message:

{
  "code": 200,
  "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
  "account": {
       "accountNumber": "4111111111111111",
       "expiryYear": "2023",
       "expiryMonth": "12",
       "newAccountNumber": "4166676667666746",
       "newExpiryYear": null,
       "newExpiryMonth": null,
       "responseCode": "LAE",
       "errorCode": null,
       "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
  }
}