Loon Authentication

Loon provides critical payment credentials and security data (PAN data and expiration dates) for Pagos customers to keep their cards on file up to date. 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 Loon service.

Authentication Credentials

When you first onboard with Pagos Loon, you’ll obtain the following credentials:

  • A public ClientKey
  • A private SecretKey

With every request you submit to Loon, 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.

Authentication Signature HTTP Headers

All calls to Loon must include an HMAC signature and at least these three headers:

X-DateUTC timestamp in ISO 8601 format2022-07-28T16:05:32.00Z

with optional microseconds and Z
The date and time of the request
X-Client-Key32 character string538A4B83FEC409ECE24CE373A883A432

The public ClientKey you obtained during onboarding
AuthorizationStringV1-HMAC-SHA256, Signature: Qj23jk3...(base64 encoded)What your code will generate when making the request

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:

  • ClientKey
  • Date
  • Request Payload
signature = Base64 ( HmacSHA256 ( clientKey + date + body ) );