When you make a call to Real-Time Loon, 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 Loon service.

Authentication Credentials

When you first log into the Real-Time Loon Service Panel, click Developers, then click API to locate the following API credentials:

• Client Key (public)
• Private Key

With every request you submit to Real-Time Loon, 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 to Loon must include an HMAC signature and at least these three headers:

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:

signature = Base64 ( HmacSHA256 ( clientKey + date + requestBody\*\* ) );

🚧

Note

Ensure the the requestBody contains messages using the accountEncrypted key, and the value is the encrypted account object as described in the Real-Time Loon Encryption guide. Don’t send account details in plain text using the account key.