The Network Tokenization API provides critical payment credentials and security data (cryptograms) for Pagos customers to use when allowing cardholders to transact. As such, we have gone beyond the simple API key approach to authentication and instead leveraged 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 Pagos Network Tokenization.

​
Authentication Credentials

When you first onboard with Pagos Network Tokenization, you’ll obtain the following credentials:
  • A public ClientKey
  • A private SecretKey
With every request you submit to the Network Tokenization API, you must submit your public ClientKey, along with a message signature that you generate using your public ClientKey and your private Secret Key combined with the request message itself (e.g. the date and the JSON payload). 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. Check out our provisioning a network token code example to see how the signature appears in a request to the Network Tokenization API.

​
Authentication Signature HTTP Headers

All calls to the Network Tokenization API must include an HMAC signature and at least these four headers:
HeaderFormatExampleDescription
X-DateUTC timestamp in ISO 8601 format022-07-28T16:05:32.00Z (with optional microseconds and Z)The date and time of the request
X-Client-Key32 character string538A4B83FEC409ECE24CE373A883A432The public ClientKey you obtained during onboarding
AuthorizationStringV1-HMAC-SHA256, Signature: Qj23jk3…(base64 encoded)What your code will generate when making the request
X-Merchant-IDString”9bb8592c-cb99-48f7-907e-f97de930fc5c”Identifies the merchant making the request

​
Authentication Signature Algorithm

The requester code will combine the following data elements to form a string, and then use a HMAC library to compute the sha256 digest in base64 format:
  • ClientKey
  • Date
  • Request Payload

​
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. Pagos uses this merchant ID to pull the applicable network-specific TRIDs to send to the card networks for network tokenization. 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.