Real-Time Loon API Overview

Real-Time Loon is a real-time account updater service for card-on-file (COF) account information. With Real-Time Loon, you can securely update your customers’ payment card account information at the time of a transaction and avoid declines caused by account lifecycle events (e.g. expirations, reissuances, etc.). A Real-Time Loon request is for a single card per request. At this time, Real-Time Loon provides account updater support for Visa and Mastercard only.

This guide outlines the following Real-Time Loon processes, from registration to receiving your first update:

  1. Request access to Loon.
  2. Register your business with the card brands.
  3. Authenticate and Encrypt with Loon.
  4. Submit a Card Inquiry in real-time upon a transaction decline or a vault update.
  5. Check response of the inquiry, if new data is available update vault or retry transaction.

Request Access

Contact us if you’re interested in Real-Time Loon. Once onboarded, you'll have access to our Loon Service Panel.

Register With Card Brands

Before you can start requesting and receiving updated card details from the card brands, Pagos must first register your business with Visa and Mastercard. Pagos will work with you directly to collect the necessary business details and complete this registration process. This process is mandatory and required by each card brand.

You can check the status of your enrollment on the Card Brand page in your Loon Service Panel.

Authenticating and Encrypting

To ensure only authorized entities can access our services, we authenticate the identity of each client that submits requests to Real-Time Loon services. Similarly, we require you to encrypt any customer account details before sending requests to Real-Time Loon. Learn more in our authentication and encryption guides.

To locate your API keys in the Loon Service Panel:

  1. Log into your Loon account.
  2. Click Developers in the main navigation.
  3. Click Create API Key.
  4. Save the Client Key and Private Key in your secure place for future reference.

🚧

Important

This is the only time you can view this Private Key.

You can navigate to the Developers page at any time to review, add, or deactivate API keys as needed.

Submit a Card Inquiry

You can submit card inquiries to Real-Time Loon on POST: /inquiry

📘

Note

There is only one account per request

Request JSON Fields

Inquiry Request

The inquiry request includes the following request JSON fields:

Data Field

Variable Type

Description

Example

requestId (Required)

string

UUID

5f954e17-27c2-46d5-b0ed-f28149267500

network (Required)

string

The card brand

This field can only have one of the following values: visa and mastercard

accountEncrypted (Required)

blob

Contains the account (URL-safe base64 encoded). See object defined in account request table.

  • *Format**: JSON Web Encrypted string using the RequestEncryptionKey.
  • *Validation**: The accountNumber in this list must be unique.

subMerchantId (Nullable)

string

For Visa, American Express, and Discover, a sub-merchant ID between 1 to 12 characters
For Mastercard, a 15 character sub_merchant_id issued by Mastercard

Account Request

The account request includes the following request JSON fields:

Data FieldVariable TypeDescriptionExample
accountNumber (Required)stringValue of length between 13 to 19 characters1111111111111111
expiryYear (Required)stringValue based on YYYY format2024
expiryMonth (Required)stringValue based on MM format09
metadata (Nullable)stringValue of length between 1 to 50 characters51032475-bc83-46d8-8768-15e129f3c6e0

Example Request

// The account object in plain-text (before encryption)
{
    "network": "visa",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    },
    "subMerchantId": null
}

// The full request after encryption including headers
{
    "X-Date": "2024-12-24T04:47:52.421Z",
    "X-Client-Key": "C732E1FD95D919F3CBAD56C0382E0D0E",
    "Authorization": "V1-HMAC-SHA256, Signature: uDf66s9aDVIEjbMNYeo+6pcZVlBVfeb1/3ieXUPv5qc=",
    "X-Merchant-Id": "47cb8551-9977-4ea9-bf4d-c12082af233b",
    "Content-Type": "application/json"
}
// The request object (using JWE Token)
{
    "network": "visa",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "subMerchantId": null,
    "accountEncrypted": "eyJ...-Q"
}

Check the Inquiry Response

After you submit a successful inquiry to Real-Time Loon, you’ll receive an encrypted response. You can decrypt the response using your ResponseDecryptionKey. See our Real-Time Loon Encryption guide for a full example.

Response JSON Fields

Inquiry Response

The inquiry Response includes the following request JSON fields:

Data Field

Variable Type

Description

Example

code (Required)

numeric

HTTP response code

200

requestId (Required)

string

UUID

5f954e17-27c2-46d5-b0ed-f28149267500

accountEncrypted (Required)

blob

Contains the account (URL-safe base64 encoded). See object defined in account response table.

  • *Format**: JSON Web Encrypted string using the RequestEncryptionKey.
  • *Validation**: The accountNumber in this list must be unique.

Account Response

The account response includes the following request JSON fields:

Data Field

Variable Type

Description

Example

accountNumber (Required)

string

Value of length between 13 to 19 characters

1111111111111111

expiryYear (Required)

string

Value based on YYYY format

2024

expiryMonth (Required)

string

Value based on MM format

09

newAccountNumber (Nullable)

string

Value of length between 13 to 19 characters

2222222222222222

newExpiryYear (Nullable)

string

Value based on YYYY format

2023

newExpiryMonth (Nullable)

string

Value based on MM format

10

responseCode (Required)

string

One of the codes from the Update Codes table

LCA

errorCode (Nullable)

string

One of the codes from the Error Codes table.

LE01

metadata (Nullable)

string

Value of length between 1 to 50 characters

51032475-bc83-46d8-8768-15e129f3c6e0

Example Response

// The encrypted response object
{
    "accountEncrypted": "eyJ...qg",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09"
}

// The response object in plain-text (after decryption)
{
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "newAccountNumber": "4166676667666746",
        "newExpiryYear": null,
        "newExpiryMonth": null,
        "responseCode": "LAE",
        "errorCode": null,
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    }
}