Real-Time Account Updater Encryption
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:
Click your profile icon at the bottom of the main navigation.
Under Developers, click API Keys.
Click the Action API tab.
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.
Copy your new key pairs and store them somewhere secure. You can only view these values one time.
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 Type | KeyAsBase64 | Key Id (KID) |
---|---|---|
RequestEncryptionKey | YWJjZGVmMTIzNDU2Nzg5YWJjZGVmMTIzNDU2Nzg5MQo= | merchant-1-uuid-pagos-bound |
ResponseDecryptionKey | QWJjRGVmMTIwNDU2Nzg5QWJjRGVmLTEyNDU2NzgwMAo= | 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:
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:
Response Decryption Example
When receiving a response, decrypt the accountEncrypted
section with your ResponseDecryptionKey.
You receive the following example response:
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:
Resulting in the full decrypted response message: