Go to Blog

Loon API Overview

About 30% of the issued payment cards globally are re-issued every year due to account closures, cards reported lost or stolen, expiration date changes, product upgrades, and fraud. Each time a customer replaces their card, you’re left with outdated stored card information in your vault. This can lead to checkout friction, declined transactions, and ultimately, customer churn.

Loon is an account lifecycle management service for card-on-file (COF) account information. Through a single API integration, you can securely update your customers’ payment card account information in a timely and efficient manner. At this time, Loon provides account updater support for Visa, Amex, Mastercard, and Discover.

This guide outlines the following Loon processes, from registration to receiving your first update and beyond:

  1. Request access to Loon.
  2. Register your business with the card brands.
  3. Authenticate with Loon.
  4. Set up webhooks to receive updates.
  5. Register encryption keys to send data securely.
  6. Prepare your data to be sent to Loon.
  7. Submit update inquiries for your cards on file
  8. Check the status of a specific update request
  9. Call Loon for your updated card details
  10. (Coming soon) Optionally send updates via Secure File Transfer Protocol (SFTP)

📘

Loon Testing

Check out our Loon Testing guide to learn more about testing in the Loon Sandbox.

Request Access

Contact us if you’re interested in 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, Mastercard, Amex, and Discover individually. 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

To ensure only authorized entities can access our services, we authenticate the identity of each client that submits requests to Loon services. Learn more in our Loon Authentication guide.

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.

Set Up Webhooks

Webhooks are a system of automated notifications that push information to your designated destination when important events occur. They’re essential for receiving notifications such as account updates or errors that occur in your Loon updater job.

To create a webhook:

  1. Click Developers in the main navigation.
  2. Click the Webhooks tab.
  3. Click Add Webhook.
  4. Create a Name for the webhook and input your webhook endpoint URL. This webhook will be marked as active by default; click the Active checkbox to deactivate it if preferred.
  5. Click Save.

You can navigate to the Webhooks page at any time to review and edit existing webhooks, or add new webhooks as needed.

Webhook Types

You will receive the following types of webhook notifications from Loon when a job status changes:

  • Job Created - The job was successful. This notification includes a associated job_id
{  
  "type": "wh_job_created",  
  "data": {  
    "job_id": 98765,  
    "timestamp": "2023-11-16T20:15:45.678Z"  
  }  
}
  • Job Complete - The job was successful
{
  "type": "wh_job_completed",
  "data": {
    "job_id": 98765,
    "timestamp": "2023-11-16T23:15:45.678Z"
  }
}
  • Job Failed - The job wasn't successful. Learn more about this webhook in our Loon Error Handling guide.
  • Job Status Changed - The job's status has changed (e.g. InProgress)
{
  "type": "wh_job_status_changed",
  "data": {
    "id": 12345,
    "status": "InProgress",
    "timestamp": "2023-11-16T21:00:30.123Z"
  }
}
  • Network Unprocessable - This notification identifies which card brand was inaccessible at the time the job was run
{
  "type": "wh_network_unprocessable",
  "data": {
    "job_id": 54321,
    "network": "SampleNetwork",
    "cards_amount": 10,
    "timestamp": "2023-11-16T19:30:15.789Z"
  }
}
  • Network Processed - This notification identifies which card brand was successfully processed 
{
  "type": "wh_network_processed",
  "data": {
    "network": "visa",
    "job_id": 12345,
    "timestamp": "2023-11-16T12:34:56.789Z"
  }
}

Register Encryption Keys

Regardless of how you send a file of primary account numbers (PANs) to Loon for updates, you must first encrypt that file. Loon will similarly encrypt any file we transfer back to you. For Loon to send you an encrypted file with your updates, you’ll need to first register your encryption keys with Loon. To do so:

  1. Click Developers in the main navigation.
  2. Click the PGP Keys tab.
  3. Click Add PGP key.
  4. Add a Label and your public key.
  5. Click Save.

You can navigate to the PGP Keys page at any time to review and manage existing PGP keys, or add new keys as needed.

📘

Note

Once you're registered with Loon, Pagos will send our public key to you directly for use with any file(s) you intend to transfer to Loon.

Prepare Your Data

After you encrypt your file of PANs, fetch and prepare your data to be sent to Loon securely. To do so:

  1. Fetch the necessary PAN data from your system that you want to send to Loon for updates.
  2. Save that data in a .csv with the columns as outlined in this example. Keep in mind, metadata is optional. Each card brand validates the sub_merchant_id field differently, so keep the following details in mind when preparing the .csv:
    1. For Visa, American Express, and Discover, the field is optional; it can contain any string value 1-12 characters in length or be null
    2. For Mastercard, the field can either be null or a valid 15 character sub_merchant_id issued by Mastercard
  3. Encrypt the .csv file using PGP encryption keys established in the Encryption Keys tab.

Submit Cards for Updates

After you've prepared your card data to be transferred, you have the option to send your secure file to Loon in one of two different ways: via the API or by Secure File Transfer Protocol (SFTP).

If you are sending your job file via the API, post the job file to the /inquiries/jobs API endpoint. After doing so, you’ll receive a job ID in response.

If you’re sending the file via SFTP, upload your job to the designated SFTP endpoint and receive a webhook notification containing the job Id as a reference. More information on this process is coming soon.

Check the Status of an Inquiry

After your inquiry has been submitted, you can poll the status of your job at any time by calling the /inquiries/jobs/{JobId} endpoint and specifying the respective job id. Possible status responses include:

  • Pending - Your job was successfully received
  • Processing - Your job is processing
  • Processed - Your job is complete and your updates are available
  • Error - There was an issue receiving and processing your job. Learn more in our Loon Error Handling guide.

Receive Updated Card Details

After you send a list of PANs to Loon for updates, you'll receive updated card details in waves over the next few days from the card brands, with the responses from each arriving asynchronously.

When the card brands have processed and returned your updates, you’ll receive a webhook notification. Retrieve an encrypted .csv file with your updates by calling the inquiries/jobs/{JobId}/download API.

Network Processed Webhooks

Pagos receives updated PANs from each of the different card brands at different times. Instead of making you wait until all card updates are ready, we’ll push them to you in waves as soon as we process them. Whenever a card brand’s PANs are ready, you’ll receive a network processed webhook notification. This webhook notification alerts you that updates from one card brand—a portion of your overall job—are available to you, and even identifies the card brand that provided the update.

Network processed updates don’t necessarily require any action from you. If you want to retrieve the partial job update after receiving this notification, you can do so. Otherwise, Loon will continue to add all of your updates to the same .csv file until all updates are processed and the job is completed; at that point, you’ll receive a job completed webhook notification and you can retrieve all your updates at once.

(Coming Soon) Send for Updates Via SFTP

With Loon, you'll soon have the ability to send bulk sets of primary account numbers to be updated via SFTP instead of a bulk API call. This feature is optional and coming soon! Check back for more details.

Client Sample

Please refer to the Loon JS example in github for a detailed client sample.