Real-Time Account Updater API Headers
All calls to Real-Time Account Updater must include the following API headers:
| Header | Format | Example | Description |
|---|---|---|---|
| X-Date | UTC timestamp in ISO 8601 format | 2022-07-28T16:05:32.00Z with optional microseconds and Z | The date and time of the request |
| X-Client-Key | 32 character string | 538A4B83FEC409ECE24CE373A883A432 “data” | The public ClientKey you obtained during onboarding |
| Authorization | String | V1-HMAC-SHA256, Signature: Qj23jk3…(base64 encoded) | What your code will generate when making the request |
| X-Merchant-ID | String | ”9bb8592c-cb99-48f7-907e-f97de930fc5c” | Identifies the merchant making the request |
The first three headers are used for authentication, and the X-Merchant-ID clarifies which merchant sent the request. This merchant identification is especially important for platform providers; learn more below .
Real-Time Authentication
When you make a call to Real-Time Account Updater, you’re requesting and receiving critical payment credentials and secure data for your customers. As such, we have gone beyond the simple API key approach to authentication and instead leverage a common HTTP REST-API pattern (AWS, Docusign, etc.) based on a keyed-HMAC (Hash Message Authentication Code) for authentication.
This guide outlines how a developer authenticates and proves their identity to access the Real-Time Account Updater service.
Authentication Credentials
When you first onboard with Real-Time Account Updater, open the Pagos Service Panel to generate an API Key pair:
If you have already created Action API keys (e.g. for Network Tokenization), you don’t need to create a new API Key pair.
Click your profile icon at the bottom of the main navigation.
Under Developers, click API Keys.
Click the Action API tab.
Under the Action API Keys header, click Create API Keys to add a new key pair to your account. A side panel will open with the new Client and Private key values.
Copy your new API key pair and store it somewhere secure. You can only view the Private Key value one time.
Click I’ve Copied My Keys to confirm and exit the side panel.
With every request you submit to Real-Time Account Updater, you must submit your public Client Key, along with a message signature that you generate using your public Client Key and your private Private Key combined with the request message itself. These details will be combined inside the HTTP headers as part of every request, as shown below.
Once Pagos receives a request, we’ll also calculate a signature; if they match, we’ll proceed with the request. Otherwise, an error will be returned and we’ll drop the request as not authorized.
Authentication Signature HTTP Headers
All calls must include an HMAC signature and at least these three headers:
| Header | Format | Description | Example |
|---|---|---|---|
X-date | UTC timestamp in ISO 8601 format | The date and time of the request | 2023-10-20T01:01:01.00Z (With optional microseconds and Z) |
X-client-key | 32 character string | Your Client Key | 538A4B83FEC409ECE24CE373A883A432 |
Authorization | String | The Signature value will be generated using the Private Key at run time, after the account object is encrypted | V1-HMAC-SHA256, Signature: Qj23jk3…(base64 encoded) |
Authentication Signature Algorithm
The requester code will combine the following data elements to form a string, and then use an HMAC library to compute the sha256 digest in base64 format:
- Client Key
- Date
- Request Body
The signature will be in the format of the following example:
Ensure the the requestBody contains messages using the accountEncrypted key, and the value is the encrypted account object as described in the Real-Time Account Updater Encryption guide. Don’t send account details in plain text using the account key.
Merchant Identification
To better our Pagos users with merchant-to-platform hierarchies, we include an X-Merchant-ID attribute in the header that sits underneath the API User. The relationship between API User and merchant is 1..n; an API User can have n merchants but a merchant will be associated with only one API User. This merchant ID will be used in the Pagos system to pull the applicable network specific keys, MIDs, and TRIDs that Pagos sends to the networks for account updates.
We’ll assign this unique merchant ID to you at the time of onboarding. If your business doesn’t operate as a platform, you’ll always use the same ID in the header of each call.