All calls to Loon must include the following API headers:

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 .

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 Loon, click Developers in the main navigation of your Loon Service Panel. Click Create API Key to generate the following API 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 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 ) );

Merchant Identification

To better support Pagos users with merchant-to-platform hierarchies, Loon includes a 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.

Any webhook that echos back to your business will also include this unique merchant identifier.