# Batch Account Updater API Headers Source: https://docs.pagos.ai/account-updater/batch-api-headers All calls to Batch Account Updater must include the following API headers: | Header | Format | Example | Description | | :- | :- | :- | :- | | Authorization | String | Bearer \ | The API key you created during onboarding | | X-Merchant-ID | String | "9bb8592c-cb99-48f7-907e-f97de930fc5c" | Identifies the merchant making the request | The first header is used for [authentication](#authentication), and the **X-Merchant-ID** clarifies which merchant sent the request. This merchant identification is especially important for platform providers; [learn more below](#merchant-identification) . ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Merchant Identification To better support Pagos users with merchant-to-platform hierarchies, Batch Account Updater 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. Pagos uses this merchant ID to pull the applicable network-specific MIDs to send 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](/account-updater/batch-webhooks) that echos back to your business will also include this unique merchant identifier. # Batch Account Updater API Overview Source: https://docs.pagos.ai/account-updater/batch-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. Batch Account Updater 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, Pagos provides batch account updater support for Visa, Mastercard, Discover, Amex Direct, and Amex OptBlue. This guide outlines the following Batch Account Updater processes, from registration to receiving your first update and beyond. Click on each step to navigate to the associated header in this guide: 1. [Request access](#request-access) to Batch Account Updater. 2. [Register your business](#register-with-card-brands) with the card brands. 3. [Authenticate](#authentication) with Batch Account Updater. 4. [Set up webhooks](#set-up-webhooks) to receive updates. 5. [Register encryption keys](#register-encryption-keys) to send data securely. 6. [Prepare your data](#prepare-your-data) to be sent. 7. [Submit update inquiries](#submit-cards-for-updates) via the API. 8. [Check the status](#check-the-status-of-an-inquiry) of a specific update request. 9. [Call Batch Account Updater](#receive-updated-card-details) for your updated card details. Review our [Testing](/account-updater/batch-testing) guide for full instructions on how to test the Batch Account Updater API in the sandbox. ## Request Access [Contact us](https://pagos.ai/contact/sales) if you’re interested in Batch Account Updater. Once onboarded, you'll have access to the [**Account Updater**](/card-network-apis/account-updater) page in your Pagos 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 **Networks** tab in the [Account Updater](/card-network-apis/account-updater#networks) page. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## 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 updater job. See our [Batch Account Updater Webhooks](/account-updater/batch-webhooks) guide for details on setting up and validating webhooks. ## Register Encryption Keys Before you submit a file of primary account numbers (PANs) to Batch Account Updater for updates, you must first encrypt that file. We will similarly encrypt any file we transfer back to you. For Batch Account Updater to send you an encrypted file with your updates, you’ll need to first register your PGP encryption keys. Encryption keys are different for Test and Live Mode. If you've already created encryption keys in [Test Mode](/getting-started/managing-your-pagos-account#test-mode), you must complete these steps to create keys in Live Mode; check the environment toggle in the top-right corner of the Pagos Service Panel to confirm which mode you're in. To register your encryption keys: Click your **settings** icon in the top-right corner. Under **Developers**, click **API Keys**. Click the **Action API** tab. Under **Batch Account Updater PGP Encryption Key**, click **Create PGP Key**. A side panel will open requesting a **Key Name** and your **Encryption Key** (i.e. your public PGP key) Fill in each value. Ensure you enter the full PGP key including the `**-----BEGIN PGP PUBLIC KEY BLOCK-----**` header and `**-----END PGP PUBLIC KEY BLOCK-----**` footer. Click **Create** to store your public key and exit out of the side panel. You can navigate to this page at any time to review and manage existing PGP keys, or add new keys as needed. ### PGP Key Pairs Batch Account Updater requires two different PGP Key pairs, and each pair is comprised of a public and private key: * **Pagos' PGP Key Pair**: Download Pagos' public keys for [Live](/account-updater/pagos-public-pgp-key-live) and [Test](/account-updater/pagos-public-pgp-key-test) Mode, then use the appropriate public key to encrypt request files before sending them to Pagos. We use **our own private key** to decrypt the file. * **Your PGP Key Pair**: When you [register your encryption keys](#register-encryption-keys), you upload **your public key** to the Pagos Service Panel; we'll then use it to encrypt the response file before making it available for download. You'll use **your private key** to decrypt that response file. ## Prepare Your Data To fetch and prepare your data to be sent to Pagos securely: 1. Fetch the necessary PAN data from your system that you want to send for updates. 2. Save that data in a .csv file with the columns as outlined [in the request file format](#request-file-format). 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](#register-encryption-keys) established in the **Action API** tab. ## Submit Cards for Updates After you've prepared your card data to be transferred, you have the option to send your secure file via the Batch Account Updater API. To do so, post the job file to the [/inquiries/jobs](/account-updater/endpoint/inquiries) API endpoint. If the request was successful, you'll receive an HTTP 200 OK status response along with a job ID; if the request fails, you'll receive the corresponding [generic API error code](/account-updater/batch-error-handling#generic-api-errors). ## 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}](/account-updater/endpoint/status) 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 [error handling](/account-updater/batch-error-handling#status-errors) guide. ## Receive Updated Card Details After you send a list of PANs to Pagos 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 [in the response file format](#response-file-format) with your updates by calling the [inquiries/jobs/\{JobId}/download](/account-updater/endpoint/download) API. Encrypted .csv response files will be available for download for 90 days from the time the response file is created. The system will automatically purge after this time. ### 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, we'll 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. ## Account Updater Batch File Format ### Request File Format The request file should be a .csv file with the following header row: `network,account_number,expiry_year,expiry_month,sub_merchant_id,metadata` Beneath the header row, you'll add at least one row of data with the following values: | Data Field | Format | | :- | :- | | `network` (Required) | `visa`, `mastercard`, `discover`, or `american express` | | `account_number` (Required) | 13-19 digits | | `expiry_year` (Required) | YYYY | | `expiry_month` (Required) | MM | | `sub_merchant_id` (Optional) | Visa, Discover, or American Express: A sub-merchant ID between 1 and 12 characters.
Mastercard: A 15 character sub\_merchant\_id issued by Mastercard | | `metadata` (Optional) | Max 50 characters | ### Response File Format The response file is an encrypted .csv file with the following header row: `account_number,expiry_month,expiry_year,new_account_number,new_expiry_month,new_expiry_year,response_code,error_code,network,sub_merchant_id,metadata` Each row contains the following values: | Data Field | Format | | :- | :- | | `account_number` | Value from the request file, same format | | `expiry_month` | Value from the request file, same format | | `expiry_year` | Value from the request file, same format | | `new_account_number` | 13-19 digits | | `new_expiry_month` | MM | | `new_expiry_year` | YYYY | | `response_code` | [Response codes](/account-updater/batch-update-codes#response-codes) | | `error_code` | [Error codes](/account-updater/batch-update-codes#error-codes) | | `network` | Value from the request file, same format | | `sub_merchant_id` | Value from the request file, same format | | `metadata` | Value from the request file, same format | # Batch Account Updater API Error Handling Source: https://docs.pagos.ai/account-updater/batch-error-handling ## Generic API Errors If your request to [submit cards for updates](/account-updater/endpoint/inquiries), [check the status of an inquiry](/account-updater/endpoint/status), or [download updated card details](/account-updater/endpoint/download) fails, you’ll receive a generic API error in the format of the following example: | HTTP Status Code | Code | Message | Details | Endpoint | | :- | :- | :- | :- | :- | | 413 | file\_too\_big | The request file size exceeds the maximum limit (50 MB). | null | inquiry | | 403 | unauthorized | Merchant is not authorized to use the resource. | null | inquiry, status, and download | | 500 | internal\_error | An internal error has occurred. | null | inquiry, status, and download | | 400 | job\_not\_ready | This job is not ready yet. | null | status and download | | 404 | job\_not\_found | A job was not found. | null | status and download | | 400 | validation\_error | Some of the request values failed to validate. | \{"jobId": "Job Id should be numeric"} | status and download | ```json theme={null} { "error": { "code": "validation_error", "message": "Some of the request values failed to validate.", "details": { "JobId": "Job Id should be numeric" } } } ``` What endpoint you call determines the types of HTTP status codes you can potentially receive, should your API request fail. This table outlines the types of generic errors you can receive and what information you can expect to find in the error messaging. ## Status Errors If your [call to request the status of an inquiry](/account-updater/batch-api-overview#check-the-status-of-an-inquiry) successfully reaches the API but the job fails, you’ll receive a `status` response of `error`. The associated error message will appear in the format of the following example: ```json theme={null} { "status": "error", "error": { "code": "validation_failed", "message": "The file failed to validate. See Details for details.", "details": [ { "detail": "file_validation_month_invalid", "additional_info": "Row = 1, Reason = Invalid length of a expiry_month", "metadata": "[value from the job file for the row]" } ] }, "networks": [ { "network": "visa", "status": "pending" }, { "network": "discover", "status": "error" } ] } ``` The `code` property value (and the associated `message`) can be one of the following: | code | message | | :- | :- | | `validation_failed` | `The file failed to validate. See Details for details.` | | `invalid_format` | `The file was in an incorrect format.` | | `internal_import_error` | `Internal error while processing the file.` | If the `code` property value is either `invalid_format` or `validation_failed`, then the `detail` property value—which is enclosed within the `details` array—can be any of the following: * `file_format_error` - There is an error in the file's formatting; review the `additional_info` property for more details on the formatting error * `file_decryption_failed` - Your file is not encrypted with Pagos' public PGP key, or is corrupted; validate that you have registered the appropriate PGP key and are encrypting with the appropriate key * `file_validation_network_invalid` - Your file contains an invalid value in the **network** field; the only possible values in this field are `visa`, `mastercard`, `discover`, `american express`, and `amex_optblue` * `file_validation_month_invalid` - Your file contains an invalid value in the **expiry\_month** field; this value must be in the format of MM * `file_validation_year_invalid` - Your file contains an invalid value in the **expiry\_year** field; this value must be in the format of YYYY * `file_validation_account_number_invalid` - Your file contains an invalid value in the **account\_number** field; this value must be 15-16 digits * `file_validation_sub_merchant_invalid` - Your file contains an invalid value in the optional **sub\_merchant\_id** field; this value must be alphanumeric * `file_validation_metadata_too_big` - Your file contains a **metadata** value that exceeds the length maximum of 50 characters * `file_validation_network_not_available` - You're not registered for account updater services from one or more card brands; reach out to your Pagos Account Manager The value of `additional_info` property will be a type string (e.g. `Row = 1, Reason = Invalid length of a expiry_year, Value = 202`) and the `metadata` property will contain the value of the metadata for the row in the submitted job file that produced the error. ## Webhook Error Notifications You’ll receive a **Job Failed** [webhook notification](/account-updater/batch-webhooks#job-failed) from Pagos whenever a job fails. The notification will appears in the format of the following example: ```json theme={null} { "type": "wh_job_failed", "data": { "merchantId": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "job_id": 54321, "reason": "validation_failed", "error_details": [ { "detail": "file_validation_year_invalid", "additional_info": "Row = 911, Reason = Invalid length of a expiry_year, Value = 202", "metadata": "[value from the job file for the row]" } ], "timestamp": "2023-11-16T22:30:45.678Z" } } ``` This notification will always include one of the following values in the `reason` field: * `validation_failed` * `invalid_format` * `internal_import_error` The JSON array `error_details` can have one or more items with the following string values in the `detail` property and details in `additional_info`: * `file_format_error` * `file_decryption_failed` * `file_validation_network_invalid` * `file_validation_month_invalid` * `file_validation_year_invalid` * `file_validation_account_number_invalid` * `file_validation_sub_merchant_invalid` * `file_validation_metadata_too_big` * `file_validation_network_not_available` The `metadata` property contains the value of the metadata for the row in the submitted job file that produced the error # Batch Account Updater Testing Source: https://docs.pagos.ai/account-updater/batch-testing Ensure your Batch Account Updater integration works correctly by simulating Account Updater responses in our test environment. ## Step 1: Create a Pagos Account or Sign In If you’re interested in Batch Account Updater, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Key In Test Mode, generate an API key for the Batch Account Updater API. These API keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test Batch Account Updater Follow the instructions in our Batch Account Updater API Overview guide to perform the following actions in Test Mode using our [test values](#test-values): 1. [Authenticate](/account-updater/batch-api-headers#authentication) to confirm your access to the Batch Account Updater service 2. [Set up webhooks](/account-updater/batch-webhooks) to receive notifications when important events occur 3. [Register encryption keys](/account-updater/batch-api-overview#register-encryption-keys) 4. [Prepare your data](/account-updater/batch-api-overview#prepare-your-data) to be transferred securely to Pagos 5. [Submit Card Update Inquiries](/account-updater/batch-api-overview#submit-cards-for-updates) via the API 6. [Check the status of your inquiry jobs](/account-updater/batch-api-overview#check-the-status-of-an-inquiry) 7. [Receive updated card details](/account-updater/batch-api-overview#receive-updated-card-details) For a detailed client sample, check out our [JS example in github](https://github.com/pagos-ai/loon-js-example). **Keep in Mind:** * **Test Mode is a stateless system** that responds with simulated responses and processes in a synchronous manner * When you submit test values, you'll receive the expected response and corresponding webhook immediately ## Test Values You can use the following test values and responses in Test Mode for both Batch and Real-Time Account Updater. ### Visa | Visa Test Card Details | Response Code | Error Code | Response Code Description | Updated Card Details (If Applicable) | | :- | :- | :- | :- | :- | | | LAE | | Change in account number or change in account number and expiration date | | | | LAE | | Change in account number or change in account number and expiration date | | | | LCA | | Closed account | | | | LED | | Change in expiration date | | | | LCC | | Contact cardholder | | | | LNB | | Non-participating BIN | | | | LNM | | Participating BIN - No match | | | | LNC | | No change in account details | | | | LCO | | Card holder opt-out | | | | | LE02 | Account number invalid | | | | | LE03 | Account number format invalid | | | | | LE04 | Expiration date invalid | | | | | LE05 | Merchant not registered | | ### Mastercard | Mastercard Test Card Details | Response Code | Error Code | Response Code Description | Mastercard Updated Card Details (If Applicable) | | :- | :- | :- | :- | :- | | | LAE | | Change in account number or change in account number and expiration date | | | | LAE | | Change in account number or change in account number and expiration date | | | | LCA | | Closed account | | | | LED | | Change in expiration date | | | | LNB | | Non-participating BIN | | | | LNM | | Participating BIN - No match | | | | LNC | | No change in account details | | | | LNC | | No change in account details | | | | | LE03 | Account number format invalid | | | | | LE04 | Expiration date invalid | | | | | LE05 | Merchant not registered | | | | | LE06 | Sub-merchant not registered | | ### Discover | Discover Test Card Details | Response Code | Error Code | Response Code Description | Discover Updated Card Details (If Applicable) | | :- | :- | :- | :- | - | | | LAE | | Change in account number or change in account number and expiration date | | | | LAE | | Change in account number or change in account number and expiration date | | | | LCA | | Closed account | | | | LED | | Change in expiration date | | | | LCC | | Contact cardholder | | | | LBC | | Brand conversion | | | | LCP | | Corrected previous update | | | | | LE01 | Undefined error | | | | | LE02 | Account number invalid | | | | | LE04 | Expiration date invalid | | ### American Express | Amex Test Card Details | Response Code | Error Code | Response Code Description | Amex Updated Card Details (If Applicable) | | :- | :- | :- | :- | - | | | LAE | | Change in account number or change in account number and expiration date | | | | LAE | | Change in account number or change in account number and expiration date | | | | LCA | | Closed account | | | | LED | | Change in expiration date | | | | LCC | | Contact cardholder for updated Account Information | | | | | LE02 | Account number invalid | | | | | LE03 | Account number format invalid | | | | | LE04 | Expiration date invalid | | | | | LE05 | Merchant not registered | | # Batch Account Updater Update Codes Source: https://docs.pagos.ai/account-updater/batch-update-codes Pagos' Account Updater tools standardize the response codes from each card brand's account updater service. The following tables break down how we map card brand response codes into the **Account Updater Update Codes** and **Error Codes**. These codes are the same for both Batch and Real-Time Account Updater. ## Response Codes | Account Updater Code | Short Code | Description | Recommended Action | | :- | :- | :- | :- | | LNR | NO RESPONSE | No updates are available for the account, or if the file contains multiple card brands, one of the brands hasn't responded yet | If the file is over seven days old and contains all LNRs, resubmit the file. Otherwise, resubmit the card the next time you use it to check for normal updates. | | LAE | ACCOUNT NUMBER OR ACCOUNT NUMBER AND EXPIRATION DATE CHANGE | The account number, or account number and expiration date are updated. | Update your systems with the new values. | | LCA | CLOSED ACCOUNT ADVICE | The issuer closed the cardholder’s account. | Update your systems that the account is no longer valid and don't attempt to use it for subsequent transactions. | | LED | EXPIRATION DATE CHANGE | The issuer updated the expiration date. | Update your systems with the new values. | | LCC | CONTACT CARDHOLDER ADVICE | Additional information required on the account. | The merchant should contact the cardholder for additional information on the account | | LNB | NON PARTICIPATING BIN | The issuer of the card does not participate in the account updater program for the given BIN. | No action at this time. You can resubmit the account number in the future, as the issuer may participate in the account updater program at a later time. | | LNM | PARTICIPATING BIN NO MATCH | The issuer of the card participates in the account updater program for the given BIN, but there is no information provided by the issuer regarding the specific card account number requested. | No action at this time. You can resubmit the account number in the future. | | LNC | NO CHANGE | The account number and expiration date are unchanged. | No action required. | | LCO | CARD HOLDER OPT-OUT | The cardholder opted out of the account updater service. | Update your systems so you don't attempt to resubmit this card in the future. | | LBC | BRAND CONVERSION | (Discover-only) The card brand has been changed but the issuer remains the same. Generally, the account number and expiration date stay the same, but could change. | If the account number or expiration date changed, update your systems with the new values. | | LCP | CORRECTED PREVIOUS UPDATE | The issuer corrected a previous update | Update your systems with the new values | ## Error Codes | Account Updater Code | Short Code | Description | Recommended Action | | :- | :- | :- | :- | | LE01 | UNDEFINED ERROR | Undefined error from the card brand. | Contact your Pagos Account Manager. | | LE02 | ACCOUNT NUMBER INVALID | The account number is not a valid PAN or is not a valid card for the given card brand. | Review and update the data. | | LE03 | ACCOUNT NUMBER FORMAT INVALID | The account number isn't in the proper format. | Review and update the data. | | LE04 | EXPIRATION DATE INVALID | The expiration date isn't in the proper format. | Review and update the data. | | LE05 | MERCHANT NOT REGISTERED | The merchant isn't registered with the card brand(s) for the account updater service. | Contact your Pagos Account Manager. | | LE06 | SUB-MERCHANT NOT REGISTERED | The sub-merchant isn't registered with the card brand(s) for the account updater service. | Contact your Pagos Account Manager. | # Batch Account Updater Webhooks Source: https://docs.pagos.ai/account-updater/batch-webhooks Webhooks are a system of automated notifications that push information to your designated destination when important events occur. To create a webhook, click **Account Updater** under **Card Brand APIs** in the main navigation of your Pagos Service Panel, and click the [**Webhooks**](/card-network-apis/account-updater#webhooks) tab. You can return to this tab any time to review and edit existing webhooks, or add new webhooks as needed. * If a single webhook has five consecutive failures, we will set the webhook status to *inactive*. This only happens if the failures are consecutive (not intermittent) * If a webhook fails or is set to *inactive*, navigate to the **Webhooks** tab to edit and re-enable the webhook ## Webhook Types You will receive the following types of webhook notifications from Pagos when a job status changes: ### Job Created This notification alerts you that the job was successful; the webhook includes an associated `job_id`. ```json theme={null} { "type": "wh_job_created", "data": { "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "job_id": 98765, "timestamp": "2025-01-25T23:37:21.6882095Z" } } ``` ### Job Complete This notification alerts you that the job was successful. ```json theme={null} { "type": "wh_job_completed", "data": { "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "job_id": 98765, "timestamp": "2025-01-25T23:37:21.6882095Z" } } ``` ### Job Failed This notification alerts you that the job was not successful. This webhook includes a `metadata` property in the `data.error_details []` array that contains the value of the metadata for the row in the submitted job file that produced the error. ```json theme={null} { "type": "wh_job_failed", "data": { "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "job_id": 54321, "reason": "validation_failed", "error_details": [ { "detail": "file_validation_year_invalid", "additional_info": "Row = 911, Reason = Invalid length of a expiry_year" "metadata": "[value from the job file for the row]" } ], "timestamp": "2025-01-25T23:37:21.6882095Z" } } ``` Learn more about this webhook in our [error handling](/account-updater/batch-error-handling#webhook-error-notifications) guide. ### Network Unprocessable This notification identifies when a network MID has not been configured for the calling merchant. Contact your Pagos Account Manager for assistance. ```json theme={null} { "type": "wh_network_unprocessable", "data": { "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "job_id": 54321, "network": "SampleNetwork", "cards_amount": 10, "timestamp": "2025-01-25T23:37:21.6882095Z" } } ``` ### Network Processed This notification identifies which card brand was successfully processed. ```json theme={null} { "type": "wh_network_processed", "data": { "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c", "network": "visa", "job_id": 12345, "timestamp": "2025-01-25T23:37:21.6882095Z" } } ``` ## Validating webhooks When you first set up a webhook, you'll create a **SecretKey** for it. Save each SecretKey somewhere secure for use in validating webhooks from Pagos moving forward. We will not display your secret again; if you ever lose it, create a new one by editing the webhook in the [Account Updater](/card-network-apis/account-updater#webhooks) page of your Pagos Service Panel. The header of each webhook you receive includes a `x-pagos-signature` property containing an HMAC-SHA256 generated hash signature. We recommend always validating this signature to ensure your server only processes webhook deliveries sent by Pagos and to verify the delivery hasn't been tampered with. This will help you avoid using server resources to process deliveries, or updating your source-of-truth systems based on messages that do not originate from Pagos, thereby helping to prevent man-in-the-middle attacks. The `x-pagos-signature` contains the webhook signature in the following format: ```bash theme={null} x-pagos-signature: t={timestamp in unix time},{signature-version}={signature} ``` Pagos generates the webhook signature hash as a concatenation of the timestamp value in `t=` from the `x-pagos-signature`, a period (“.”), the contents of the `body:` of the webhook payload, and the stored customer secret. This signature will be sent in the `{signature-version}=` property of the `x-pagos-signature`. The `{signature-version}` will be initially set as “V1”, representing SHA256. If additional hashing algorithms are offered, then an additional `{signature-version}` will be created representing these additional hashing algorithms. To validate the webhook signature a customer should generate a webhook signature using the above process of concatenation of the timestamp value in `t=` from the `x-pagos-signature` plus a period “.” plus the contents of the `body:` of the webhook payload and the stored customer secret. Then compare your signature with the signature value in `{signature-version}={signature}`. If they match, you're safe to process the webhook. If they don’t match, then the webhook should be dropped. **Example Webhook Message** ```json theme={null} { x-pagos-signature: t=1731326247,v1=K1dEDpPNgRiehBEZzyx1/mZYKjE0jrK3qkvklPqAG+g= body: { "type":"wh_job_created", "data":{ "job_id":23255, "timestamp":"2024-11-11T11:57:22.6315227Z", "merchant_id":"ae89c6af-dde7-4460-8a6f-bd64ec0826a6" } } } ``` **Python Code for Generating and Comparing Signatures** ```python theme={null} import hmac import hashlib import base64 signature = 'K1dEDpPNgRiehBEZzyx1/mZYKjE0jrK3qkvklPqAG+g=' time_stamp = '1731326247' message_body = '{"type":"wh_job_created","data":{"job_id":23255,"timestamp":"2024-11-11T11:57:22.6315227Z","merchant_id":"ae89c6af-dde7-4460-8a6f-bd64ec0826a6"}}' message = time_stamp + '.' + message_body secret_key = "RAJZ5nBM,)Ub]eUw7cXwD%]hN<8HrEd>r" # Create an HMAC object using SHA-256 hmac_object = hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha256) # Get the HMAC signature as a hexadecimal string base64_string = base64.b64encode(hmac_object.digest()).decode("utf-8") result = base64_string == signature print(f"The signatures match: {result}") ``` Webhook verification is highly recommended, but isn't required. We also advise (but don't require) you to allow-list the [Pagos IP address](/getting-started/pagos-domains-and-ip-addresses#account-updater-and-network-tokenization-ip-addresses) that sends webhooks to your system as an additional security measure. # Download Updated Card Details Source: https://docs.pagos.ai/account-updater/endpoint/download GET /loon/inquiries/jobs/{jobId}/download # Submit Cards for Updates Source: https://docs.pagos.ai/account-updater/endpoint/inquiries POST /loon/inquiries/jobs # Real-Time Account Updater Inquiry Source: https://docs.pagos.ai/account-updater/endpoint/rtau-inquiry POST /loon/rtau/inquiry When sending legacy encrypted payloads, use accountEncrypted in request and response # Check Status of an Inquiry Source: https://docs.pagos.ai/account-updater/endpoint/status GET /loon/inquiries/jobs/{jobId} # Pagos Account Updater Tools Source: https://docs.pagos.ai/account-updater/pagos-account-updater-tools Pagos provides two options for account updater: Request updated card details in batches to keep your vault up to date. Update card details in real time during checkout to boost approval rates. # Pagos Public PGP Key (Live) Source: https://docs.pagos.ai/account-updater/pagos-public-pgp-key-live Pagos' public PGP key for Live Mode If you're using Batch Account Updater in [**Live Mode**](/getting-started/managing-your-pagos-account#test-mode), use the following public PGP key to encrypt your request files before sending them to Pagos: ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQGNBGRn420BDAClnHBdrsgk9SyB9zw/sRTfE88yO690wBdofENXpuGsEvQgd2wd 0R2T092LfK5dTdDnGaeB8QcvgJXWwTDflwInH1OYeIgaLQa/hsuSjf/DkOlMCmMq ifgBICVFLoZo676ojlNgALUxMSHvZCCtO8zqnamxd5r2e+N5b9aZOl2E/LaLvmz8 iyzvU/fQxJyGjnCJNs7pos9L3wNg8u+LKho9t8pE4HZiV+wfchdfjcsW6yv6o2Pg VuoIdQ3QuN+NtY4muP9tZ15o3NwX2pHReAsdNSbDRFU/i4zLTPUyntAz5twJ5Mfr n8pe+6ckrtimenOGZp0eV1Fa8ceJovcgTuQST6+z0166/GiIK9bOjgU2jzQFHqpA CtV3GoiB9vffaSv8OzdYAy2oTUo91Z91fH8lo65eVIyqABisaxV68jzMU9kWPMHD IKp+Pq179iyOzcMPD1AviRpW3h8XAgb3AruMBTbJWAPw9eEko1R5vTpWmokCReb3 886sBV75IFMjrSkAEQEAAbQfUGFnb3MgTG9vbiBQcm9kIDxsb29uQHBhZ29zLmFp PokBzgQTAQoAOBYhBOAjDMjOgDAEW8s2ioMkOlLlUxW5BQJkZ+NtAhsDBQsJCAcC BhUKCQgLAgQWAgMBAh4BAheAAAoJEIMkOlLlUxW5X/YL/RXcHVpk1B3Tm660L8xR uWneckK9/7IT9wWBUEzlgFDBluL8Ve5BwAh7KBEFxLgWYHdsfp+vi/Wx5V7bnD90 ZcaPDcGj1Bt+YHhbnvTE50ARgdUgW+YMUwcr/fVpHUd1yhjNRzaWKDifn6zZgI7h HUBNlsKEB0Gsj7VTlzQ6qQ7DkZNchWj+dDuajfzU9Yzwi6IbRi/YCRk+1KSwwuvA fmS7wdOMa308WWd+1YZhXCoBa1xbJzJFcwtPlhOuLSmrSydKqBrGPtUJ0bJR4yyM kEJAWqVmpThRgmT6r6KV+iWBlALM+BbBtrYF0cfN0Z9JPBVW7+8DiYNnDY6i7zE4 kSBsIJ1IfJKr5qO8cKajiO5UZ1FBo2oxxpbrewbLQ1uPppsE8kM6yjiR+GEl4lEq Y9iujYSTOQqEsJ8NxzltdeyxsBgfckUV9vnoYLT4KVLFTVmVHzohW057elaWUCcS CQEqlByESFatUvco9+1mAXaZESTK31HhemrVyaBLrVbIo7kBjQRkZ+NtAQwApT+q ZdRcx9r9b4VFwLh26On3g2hdPLK0lsQzxVyZvJPAHWgCqpmmoFjcCAijcOMuJvSj EYnZsXbBDSw1/mjNpk0pfUpXo1achWDxevWzTnuhkcsNtj5SnBEWiQRyABi67kqf TlhpleyMr56gQ0lH+rvnEElaajtaVFws8lJO6pg2KUha+8m7SjC/5cskcKMhTitB 7Ep5vFKQkbXFH4vp/rTb3Js9FVfmd9grwgMDw5nGiW3dzfHJYcEX5Xq197OLiJyh jPCGf+PBMjScrE+vmGH8GOTTb5JY/F7BqEE2tbDA8JFe5FHzunb8PsEizab+RQ05 T/CODkoFKtDeEvJPExEZxyAEKgLTgr3hZa4bRCX6jhoiGpgjvIc6OrU/wJhVDMtm xGqLmObtIqVEv7Hbyd9IRNq1HK7r9yHOd9huIWjUWyKsaVm2xC7O13f91y83Atk4 HAQ53jWgVVf5jHIA5bR6eKh5KBk6lobm5vMFOLr7E35+lNZ3wTQSytZNDeobABEB AAGJAbYEGAEKACAWIQTgIwzIzoAwBFvLNoqDJDpS5VMVuQUCZGfjbQIbDAAKCRCD JDpS5VMVuc+1C/9+e+XgfxtA9u36+iHhsLEAfitDeBGE5t7yb0Ei83Sod0fDNs48 PkIeqfsPXpKiMUH+bZEVKv6RVKTEPlmSmaYfy455vZPpJA4Hr8jkdQbeMiTUG+xA z9ncdoNTgll6xVi5hBC9UZx2pPEPfuC3dveraVw0MyE1w8qriZTAeZTI9a83Q4Lc y6gnxXiWBFZGjDLTGxxeDb+V58XNU4JRl83MHwsP5HVLr6QtjfGztwiTa6JODGt0 LiM49n7c30bD24OjwVfEIdKaFLy8dVyDc7TJsFFqA/YmxZiDXmV9RvuUklHBqYei FntdgN44+MgDP6MQqMHuUV6sLM3BdGlYM3AqWbXeS0GScFpD6kHslcAR3+0epxFh kF+zMmtAbp+HATzS4Ero95Uq0WlTdMGdUdpRjQI4iOGXYUR4Vi+40fiLKLK/+cxw mIHKNg69FXuwPySfQ6YkmWWZkLDzvEVXyqhP1gyAHLIu8eFTj5jTmLH0QFzeArGW jzHETXG2YTamYPM= =iYy2 -----END PGP PUBLIC KEY BLOCK----- ``` # Pagos Public PGP Key (Test) Source: https://docs.pagos.ai/account-updater/pagos-public-pgp-key-test Pagos' public PGP key for Test Mode If you're [testing Batch Account Updater](/account-updater/batch-testing) in [**Test Mode**](/getting-started/managing-your-pagos-account#test-mode), use the following public PGP key to encrypt your request files before sending them to Pagos: ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQGNBGgZUSIBDADJ93wBjFZolAkwPdrjXG7y4vUpEdPM/eMu2qvi8LNbZ18GqvuL L3YLNX0CGl7+aTY7xD5oQlKvUEBZQVT1FoVUWIDyL7rRiqTdtlo+V4qd0/1qJ6Yo 6BqcUpofLri2RM5fFrMT8eYnPePHYEQVoEzuQziBie9EQYJvYUdOWUIj5PxNKNR+ WXW+Y6L8d1ywH5uxroaKa/PQscOwHz8JwKx5EH1Bk+fNGENOc8pssSvrStfHd6TN fNloeRxG1uttwcEm9lCO/mdkR++spD+I9RHynAXKphlJ+JYicrWKKQM+QSpWw5iV 9+OVbnpYi91KYKSnLtiTodnT3keoPzInrslQdePgSiQAoxkFy+6Vzu7oKJQh8Owf jYmXt43cW9xwNRvp4U5qgPWs0zsx/CztJKnULCuuHuVemoobQoyOpCiBCwN9HSuI 4qqGQOI/Q6Lo3ZYBCw9i2DDmUjek/lzq1dCPnNeEdnOsuKd2iRsBPjFf/HfaWycX pgwY3+BQHafCn7sAEQEAAbQqUGFnb3MgTG9vbiBTYW5kYm94IDxsb29uK3NhbmRi b3hAcGFnb3MuYWk+iQHRBBMBCAA7FiEEtUhZC41hoEJltTyJArkZeDKr5oAFAmgZ USICGwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQArkZeDKr5oDXUQwA qE7Tu3hPo9HaRzP9r3KKDCW+fP5EurVEqsP+rCJID0hvv65/+9FAqBuORLtDKeRq 1xYoPK8wX6VUu2kRmYOCvqy8jrBkY16C15AJPWIjZWXk3ayAnNL5q2MvFSxGL4+O LSRY5j5ydZE1NiXlmJmtITtDt1JV4yo1fM7zg/+YeJQm5V5DC5FLkrJxeY0hI8Le xRR3azj9pB8/+tk1NoS5ycRIJMjMbkSQulSA6eLXGnB0Bn5PAlVqjhhuzvRmmbW3 WAmP8E/SdQ7X8S8fiOeN1gj9VKzwW5+rH1CXQNpvWbmqQiY2+1VhumVLM9rRK591 kqp/Yl89+4gUeghcPzzLcGPOZ49wdkvyXDuwNlp0zl4iLG8DJt2kcx6gT0z7FyIL 6sdz6sXC++8jfOKU0/VEoBphVylb0+DeCHjMhBLXVIFU+IrzT53MEVx/pEHruPhO TTULTJZbmAC2h/KY9jpJuPWo7f0hnYpqPTI21IbWQPeY7DwHLcLyXTsN8pozKQW4 uQGNBGgZUSIBDADSuBsKQ9nAxrqcwkOG4r6Rl506OnVEn+NroPFWex+3ZWPHKthN ht8xBm9LgnRdzu2Yu0v+X1sUc6nhM6LSWqg5zazNOeGcRY4Y+O7SGj0tNhBpmqvx Z8UIrYlODLWLjC/tWS1+/BYt2vkpdloZJ7uNGEwi5rruw5HWX60KCEKI+1L9jUe0 mPhbepHy8gGdBijxwL/vMSkwCbYIilShfuUw3yPwzwhW7fVA7/w6lcpRgp6dXhCZ YOKQ6ImWEl4cSiKH24r/bcdfTnQSUtJsaMlqd3l4WybO5tmphqKIQNPlUx3O19MM 3lz0yCBHRF6/1yHlxT4S1P7SiFCuQX0sB6xNbmZwbkqjy85o54ygijTWtIW4R8Ip Z+IreHBChr/g0s4+38hoDSHe7lKctQRwbXRxU3cudb9Jl/+CbVVRqLhviNZ7UVGx L0XQ4oRHaC6VTZFYakci6l/j1J0cZdLKJ5jaUjNF/6hXQU1cBNuxfMbUuL6IDOPh CePqQIX2QMWV9pcAEQEAAYkBtgQYAQgAIBYhBLVIWQuNYaBCZbU8iQK5GXgyq+aA BQJoGVEiAhsMAAoJEAK5GXgyq+aAEsQMAKRXK+1B3OJfOYZmIYlKyPqDoxHLACFB r36OhB3M2nqak+zljZElWQQ15JWrdF5Wh3ntMEsNmUJJQ52UDRIhysdg5Gne3k5w Gc8IrgG1JRHXas6lF0S1ibJt9UnC4+7nmlYT4zG/p6NZ0Z9JmvG1hVZzcxF8Ow4i cgliCrQB7Zmn+gzlfswyZtwGMueslrLWmMiItG+mFtbPfMDuxgnOtVGavZLVywDQ CChzFX8v0nku+CKlKwn6EKOz0HtZoO9mHTSRFBLZWfdkkV2jCXIfFf14QloAyLm/ rkqq68p4z0J2Pjfx3bnAZkQGGNts331rdph6C6N8sUzwzE3nO6aLSr3SIBNvrIlC 6RI+uf/4ZbzSvAV1HU3j8uiMR3pgRntcORA+RCFCCwxVfXSxVvON8iJmxD5sAHPr 95OhvYiwwDI9tcH7k7ociqXI4G+FJFs4tJy5X3x8fRXyxKtw+I/WYMOaEjo8y5/v aRjJBFN9AdlfB+aJ230TBPNziPi4cBpDTw== =2e0s -----END PGP PUBLIC KEY BLOCK----- ``` # Real-Time Account Updater API Headers Source: https://docs.pagos.ai/account-updater/real-time-api-headers All calls to Real-Time Account Updater must include the following API headers: | Header | Format | Example | Description | | :- | :- | :- | :- | | Authorization | String | Bearer \ | The API key you created during onboarding | | X-Merchant-ID | String | "9bb8592c-cb99-48f7-907e-f97de930fc5c" | Identifies the merchant making the request | The first header is used for [authentication](#authentication), and the **X-Merchant-ID** clarifies which merchant sent the request. This merchant identification is especially important for platform providers; [learn more below](#merchant-identification) . ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Merchant Identification To better support Pagos users with merchant-to-platform hierarchies, Real-Time Account Updater includes an `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. Pagos uses this merchant ID to pull the applicable network-specific MIDs to send 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. # Real-Time Account Updater API Overview Source: https://docs.pagos.ai/account-updater/real-time-api-overview With Real-Time Account Updater, you can securely update your customers’ account information at the time of a transaction and avoid (or recover) declines caused by account lifecycle events (e.g. expirations, reissuances, etc.). A Real-Time Account Updater request is for a single card per request. At this time, Real-Time Account Updater provides account updater support for Visa and Mastercard only. This guide outlines the following Real-Time Account Updater processes, from registration to receiving your first update: 1. [Request access](#request-access). 2. [Register your business](#register-with-card-brands) with the card brands. 3. [Authenticate](#authenticating). 4. [Submit a Card Inquiry](#submit-a-card-inquiry) in real-time upon a transaction decline or a vault update. 5. [Check response](#check-the-inquiry-response) of the inquiry, if new data is available update vault or retry transaction. Review our [Testing](/account-updater/real-time-testing) guide for full instructions on how to test the Real-Time Account Updater API in the sandbox. ## Request Access [Contact us](https://pagos.ai/contact/sales) if you’re interested in Real-Time Account Updater. Once onboarded, you'll have access to the [**Account Updater**](/card-network-apis/account-updater) page in your Pagos 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 **Networks** tab of the **Account Updater** page. ## Authenticating The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Submit a Card Inquiry You can submit card inquiries on POST: [/inquiry](/account-updater/endpoint/rtau-inquiry) There is only one `account` per request ### Request JSON Fields #### Inquiry Request The **inquiry request** includes the following 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` or `mastercard` | | `account` (Required) | account object | Contains the `account` object listed below. | | | `subMerchantId` (Nullable) | string | For **Visa**, a sub-merchant ID between 1 to 12 characters. For **Mastercard**, a 15 character *sub\_merchant\_id* issued by Mastercard | | ### Account Object The **account object** includes the following 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` | | `metadata` (Nullable) | string | Value of length between 1 to 50 characters | `51032475-bc83-46d8-8768-15e129f3c6e0` | ### Example Request ```json theme={null} { "network": "mastercard", "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500", "account": { "accountNumber": "5105105105105100", "expiryMonth": "12", "expiryYear": "2023", "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0" } } ``` ### Response JSON Fields #### Inquiry Response The **inquiry Response** includes the following JSON fields: | Data Field | Variable Type | Description | Example | | :- | :- | :- | - | | `code` (Required) | numeric | HTTP response code | `200` | | `requestId` (Required) | string | UUID | `5f954e17-27c2-46d5-b0ed-f28149267500` | | `account` (Required) | account object | Contains the json account | | ### Account Object The **account object** includes the following JSON fields: | Data Field | Variable Type | Description | Example | | :- | :- | :- | - | | `accountNumber` (Required) | string | Value (13-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 (13-19 characters) | `2222222222222222` | | `newExpiryYear` (Nullable) | string | Value based on YYYY format | `2023` | | `newExpiryMonth` (Nullable) | string | Value based on MM format | `10` | | `responseCode` (Required) | string | A code from the [Response Codes](/account-updater/batch-update-codes#response-codes) table | `LCA` | | `errorCode` (Nullable) | string | A code from the [Error Codes](/account-updater/batch-update-codes#error-codes) table | `LE01` | | `metadata` (Nullable) | string | Value (1-50 characters) | `51032475-bc83-46d8-8768-15e129f3c6e0` | ### Example Response ```json theme={null} { "account": { "accountNumber": "5105105105105100", "expiryYear": "2023", "expiryMonth": "12", "newAccountNumber": "5233580618829955", "newExpiryYear": "2026", "newExpiryMonth": "12", "responseCode": "LAE", "errorCode": null, "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0" }, "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500" } ``` # Real-Time Account Updater Error Handling Source: https://docs.pagos.ai/account-updater/real-time-error-handling You will make all Real-Time Account Updater requests to a single endpoint: [/inquiry](/account-updater/endpoint/inquiries). If your request fails for authentication or network errors, you’ll receive an error in the format of the following example: ```json theme={null} { "code": 403, "requestId": "8b764b09-5e2d-4562-8a74-6d04fbf574cd", "errorDetails": { "reason": "unauthorized", "message": "Merchant is not authorized to use the resource." } } ``` ## API Error Details | HTTP Response Code | `errorDetails` reason | `errorDetails` message | Recommended Action | | :- | :- | :- | :- | | 401 | `AuthenticationFailed` | `The account updater service could not authenticate the request.` | Re-submit your request with correct credentials. Contact your Pagos Account Manager if the problem persists. | | 403 | `unauthorized` | `Merchant is not authorized to use the resource.` | Re-submit your request with correct `x-merchant-id` in the header. Contact your Pagos Account Manager if the problem persists. | | 429 | `concurrentLimitExceeded` | `You exceeded the maximum allowed concurrent API calls.` | Keep concurrent API calls within the allowed concurrent API request limits. | | 500 | `SystemError` | `A system error occurred.` | Contact your Pagos Account Manager. | | 503 | `NetworkError` | `The network cannot process the request.` | Re-submit your request later. Contact your Pagos Account Manager if the problem persists. | ## Validation Errors If your request fails due to a validation error (HTTP code 400), the response will include a `code` element that explains the source of the validation error. The response will be in the format of the following example: ```json theme={null} { error: { code: 'account_validation_month_invalid', message: "accountsEncrypted property validation's failed.", details: {} } } ``` ### Validation Error Details | HTTP Response Code | `error` code | Recommended Action | | :- | :- | :- | | 400 | `validation_error` | Re-submit your request following guidance in the `details` object. | | 400 | `account_validation_account_number_invalid` | Re-submit your request with a valid PAN. | | 400 | `account_validation_month_invalid` | Re-submit your request with a valid PAN expiry month. | | 400 | `account_validation_year_invalid` | Re-submit your request with a valid PAN expiry year. | Pagos is currently working on normalizing the error message response body formats between API Error and Validation Error to aid in integraiton. # Real-Time Account Updater Testing Source: https://docs.pagos.ai/account-updater/real-time-testing Ensure your Real-Time Account Updater integration works correctly by simulating Account Updater responses in Test Mode. You can use the following test values and responses in Test Mode for both Batch and Real-Time Account Updater. ## Step 1: Create a Pagos Account or Sign In If you’re interested in Real-Time Account Updater, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Key In Test Mode, generate an API key for the Real-Time Account Updater API. These API keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test Real-Time Account Updater You're ready to begin testing the full capabilities of Real-Time Account Updater! Follow the instructions in our Real-Time Account Updater Overview Overview guide to perform the following actions in Test Mode using our [test values](#test-values): 1. [Authenticate](/account-updater/real-time-api-overview#authenticating) to confirm your access 2. [Submit a card inquiry](/account-updater/real-time-api-overview#submit-a-card-inquiry) using our test values. 3. [Check response](/account-updater/real-time-api-overview#check-the-inquiry-response) of the inquiry. **Keep in Mind:** * **Test Mode is a stateless system** that responds with simulated responses and processes in a synchronous manner * When you submit test values, you'll receive the expected response and corresponding webhook immediately ## Test Values ### Visa | Visa Test Card Details | Response Code | Error Code | Response Code Description | Updated Card Details (If Applicable) | | :- | :- | :- | :- | :- | |
  • **PAN:** 4111111111111111
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LAE | | Change in account number or change in account number and expiration date |
  • **PAN:** 4166676667666746
| |
  • **PAN:** 4012888888881881
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LAE | | Change in account number or change in account number and expiration date |
  • **PAN:** 4212345678910006
  • **Exp. Month:** 12
  • **Exp. Year:** 2026
| |
  • **PAN:** 4330251207506660
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LCA | | Closed account | | |
  • **PAN:** 4539097887163333
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LED | | Change in expiration date |
  • **Exp. Month:** 12
  • **Exp. Year:** 2026
| |
  • **PAN:** 4929980395567582
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LCC | | Contact cardholder | | |
  • **PAN:** 4929544240318920
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LNB | | Non-participating BIN | | |
  • **PAN:** 4916725297925395
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LNM | | Participating BIN - No match | | |
  • **PAN:** 4711358892785746
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LNC | | No change in account details | | |
  • **PAN:** 4035501000000008
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| LCO | | Card holder opt-out | | |
  • **PAN:** 4035501428146300
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| | LE02 | Account number invalid | | |
  • **PAN:** 4917610000000000
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| | LE03 | Account number format invalid | | |
  • **PAN:** 4111111145551142
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| | LE04 | Expiration date invalid | | |
  • **PAN:** 4111112014267661
  • **Exp. Month:** 12
  • **Exp. Year:** 2023
| | LE05 | Merchant not registered | | ### Mastercard | Mastercard Test Card Details | Response Code | Error Code | Response Code Description | Mastercard Updated Card Details (If Applicable) | | :- | :- | :- | :- | :- | |
  • **PAN**: 5555555555554444
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LAE | | Change in account number or change in account number and expiration date |
  • **PAN**: 5454545454545454
| |
  • **PAN**: 5105105105105100
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LAE | | Change in account number or change in account number and expiration date |
  • **PAN**: 5233580618829955
  • **Exp. Month**: 12
  • **Exp. Year**: 2026
| |
  • **PAN**: 5461310156953048
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LCA | | Closed account | | |
  • **PAN**: 5325191087030619
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LED | | Change in expiration date |
  • **Exp. Month**: 12
  • **Exp. Year**: 2026
| |
  • **PAN**: 5580422612666704
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LNB | | Non-participating BIN | | |
  • **PAN**: 5157204564548129
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LNM | | Participating BIN - No match | | |
  • **PAN**: 5336475987107024
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LNC | | No change in account details | | |
  • **PAN**: 5412000000001009
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| LNC | | No change in account details | | |
  • **PAN**: 5555341244441115
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| | LE03 | Account number format invalid | | |
  • **PAN**: 5577000055770004
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| | LE04 | Expiration date invalid | | |
  • **PAN**: 5555444433331111
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| | LE05 | Merchant not registered | | |
  • **PAN**: 5100060000000002
  • **Exp. Month**: 12
  • **Exp. Year**: 2023
| | LE06 | Sub-merchant not registered | | # Real-Time Account Updater Update Codes Source: https://docs.pagos.ai/account-updater/real-time-update-codes Pagos' Account Updater tools standardize the response codes from each card brand's account updater service. The following tables break down how we map card brand response codes into the **Account Updater Update Codes** and **Error Codes**. These codes are the same for both Batch and Real-Time Account Updater. ## Response Codes | Account Updater Code | Short Code | Description | Recommended Action | | :- | :- | :- | :- | | LNR | NO RESPONSE | No updates are available for the account, or if the file contains multiple card brands, one of the brands hasn't responded yet | If the file is over seven days old and contains all LNRs, resubmit the file. Otherwise, resubmit the card the next time you use it to check for normal updates. | | LAE | ACCOUNT NUMBER OR ACCOUNT NUMBER AND EXPIRATION DATE CHANGE | The account number, or account number and expiration date are updated. | Update your systems with the new values. | | LCA | CLOSED ACCOUNT ADVICE | The issuer closed the cardholder’s account. | Update your systems that the account is no longer valid and don't attempt to use it for subsequent transactions. | | LED | EXPIRATION DATE CHANGE | The issuer updated the expiration date. | Update your systems with the new values. | | LCC | CONTACT CARDHOLDER ADVICE | Additional information required on the account. | The merchant should contact the cardholder for additional information on the account | | LNB | NON PARTICIPATING BIN | The issuer of the card does not participate in the account updater program for the given BIN. | No action at this time. You can resubmit the account number in the future, as the issuer may participate in the account updater program at a later time. | | LNM | PARTICIPATING BIN NO MATCH | The issuer of the card participates in the account updater program for the given BIN, but there is no information provided by the issuer regarding the specific card account number requested. | No action at this time. You can resubmit the account number in the future. | | LNC | NO CHANGE | The account number and expiration date are unchanged. | No action required. | | LCO | CARD HOLDER OPT-OUT | The cardholder opted out of the account updater service. | Update your systems so you don't attempt to resubmit this card in the future. | | LBC | BRAND CONVERSION | (Discover-only) The card brand has been changed but the issuer remains the same. Generally, the account number and expiration date stay the same, but could change. | If the account number or expiration date changed, update your systems with the new values. | | LCP | CORRECTED PREVIOUS UPDATE | The issuer corrected a previous update | Update your systems with the new values | ## Error Codes | Account Updater Code | Short Code | Description | Recommended Action | | :- | :- | :- | :- | | LE01 | UNDEFINED ERROR | Undefined error from the card brand. | Contact your Pagos Account Manager. | | LE02 | ACCOUNT NUMBER INVALID | The account number is not a valid PAN or is not a valid card for the given card brand. | Review and update the data. | | LE03 | ACCOUNT NUMBER FORMAT INVALID | The account number isn't in the proper format. | Review and update the data. | | LE04 | EXPIRATION DATE INVALID | The expiration date isn't in the proper format. | Review and update the data. | | LE05 | MERCHANT NOT REGISTERED | The merchant isn't registered with the card brand(s) for the account updater service. | Contact your Pagos Account Manager. | | LE06 | SUB-MERCHANT NOT REGISTERED | The sub-merchant isn't registered with the card brand(s) for the account updater service. | Contact your Pagos Account Manager. | # Pagos API Authentication Source: https://docs.pagos.ai/authentication/authentication-overview **Legacy API Key Migration** As of **September 1, 2026**, you can no longer authenticate requests with product-specific legacy API keys. See the [September 2026 API Migration](/authentication/september-2026-api-migration) guide for more details and migration instructions. You integrate with all Pagos services via RESTful APIs, secured and authenticated by a unified API key. This guide outlines how to request your API key and authenticate against the APIs: * [Generate an API key](#generate-an-api-key) * [Authenticate with the APIs](#authentication) ## Generate an API Key Follow these steps to create keys for all Pagos APIs. API keys generated anywhere else in the Pagos Service Panel are legacy keys that stopped working on [September 1, 2026](/authentication/september-2026-api-migration). To generate an API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. You'll provide this API key with all API requests. Pagos uses this value alone to authenticate requests to our servers; you don't need to provide a password. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. To access the API, you must authenticate via Bearer Authentication (e.g. for a cross-origin request). When you make any API request, pass an `Authorization` header in the following format: ```bash theme={null} Authorization: Bearer ``` **Keep in mind:** * All API requests must be made over HTTPS; calls made over plain HTTP will fail * API requests without authentication will fail # September 2026 API Migration Source: https://docs.pagos.ai/authentication/september-2026-api-migration How to migrate your Pagos integration in preparation for changes coming on September 1, 2026. We're making several changes to the Pagos APIs on **September 1, 2026** that will require you to take action. Each change is independent of one another and you can address them in any order. **You must complete all required actions before September 1, 2026**. **All API users** must replace all legacy product keys with a new unified key and switch to `Authorization: Bearer` **BIN Data API users** must send all requests to `bin.pagos.ai` **BIN Data API users who allowlist IPs** must update their allowlist to the new addresses **BIN Data Batch users** must move to the new domain and allowlist the new download hostname **Important Notes:** * These changes are independent of one another and must be addressed independently * Migrating to the new domain **doesn't** migrate your API key, and creating a unified API key **doesn't** move you to the new domain * Check each section below against your integration ## Migration Checklist If you're impacted by all impending integration changes, complete this entire checklist before September 1, 2026: Create a key on the main **API Keys** tab in the Pagos Service Panel—not under a product-specific tab. [Details below](#unified-api-keys). Remove any legacy headers (`x-api-key`, `x-client-key`, `x-date`) and [replace them](#switching-your-authentication-header) with `Authorization: Bearer `. [Replace](#new-api-domains) `parrot.prod.pagosapi.com` with `bin.pagos.ai` in production and `parrot.sandbox.pagosapi.com` with `bin.sandbox.pagos.ai` in sandbox. [Add](#new-static-ip-addresses) `13.248.157.210` and `166.117.218.160` to any firewall rules. Use the `url` value returned in the batch response as-is, rather than rebuilding it from a hardcoded domain. If you allowlist that download hostname anywhere, [add the new one](#your-network-controls) before September 1. Once production is stable on the unified key, revoke the old product-specific keys. ## Unified API Keys Pagos originally issued a separate API key for each product, each with its own authentication format. The **unified API key** replaces all of them: one key that works across the entire Pagos suite and authenticates with a standard `Authorization: Bearer` header. You must update your existing keys to the unified API key by September 1. If either of the following is true, you have legacy API keys that must be updated: * Your integration sends the API key in an `x-api-key` header (BIN Data APIs) * Your integration sends `x-client-key` and `x-date` headers with an HMAC signature (Account Updater and Network Tokenization) * You created the key under a **product-specific tab** in the developer settings of your Pagos account **This is the most common source of confusion.** In the **settings** dropdown menu, click **API Keys** under **Developers**. The first tab on this page is **API Keys**; this is where you can generate unified API keys. The other tabs (**Data Ingestion & Observability API**, **BIN Data API**, and **Action API**) still issue **legacy** keys, which will stop working on September 1, 2026. If you create a replacement key under a product tab, you haven't migrated. Always use the main **API Keys** tab. API Keys Unified vs Legacy | Legacy Tab | Products Covered | | :- | :- | | **BIN Data API** | [BIN Data API](/bin-data-APIs/bin-data-api-overview), [BIN Data Batch](/bin-data-APIs/batch-api-overview), [BIN Continuity API](/bin-data-APIs/bin-continuity-api-overview) | | **Action API** | [Real-Time Account Updater](/account-updater/real-time-api-overview), [Batch Account Updater](/account-updater/batch-api-overview), [Network Tokenization](/network-tokenization/overview) | | **Data Ingestion & Observability API** | [Data Ingestion API](/data-ingestion-api/data-ingestion-api-overview), [Enrichment API](/data-ingestion-api/enrichment-api-overview) | The **Action API** tab only appears if your organization signed up for Account Updater or Network Tokenization, so you may not see all three tabs. ### Creating a Unified Key Follow the instructions in the [Pagos API Authentication](/authentication/authentication-overview#generate-an-api-key) guide to generate your new unified API key. All unified keys begin with the prefix `ak_`. A single key covers every Pagos product your organization is entitled to, so most integrations replace several product keys with one. API keys are different for Test and Live Mode. Create one in each mode using the [environment toggle](/getting-started/managing-your-pagos-account#test-mode) in the top-right corner of the Service Panel. ### Switching Your Authentication Header | | Legacy | Unified | | :- | :- | :- | | **Header (BIN Data APIs)** | `x-api-key: ` | `Authorization: Bearer ` | | **Header (Account Updater & Network Tokenization)** | `x-client-key` + `x-date` + HMAC signature | `Authorization: Bearer ` | | **Header (Data Ingestion & Observability)** | `Authorization: ` | `Authorization: Bearer ` | ```bash Unified theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins?bin=55630400' \ --header 'Authorization: Bearer ' ``` ```bash Legacy theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins?bin=55630400' \ --header 'x-api-key: ' ``` Send only **one** authentication header with each request; if a request includes both `Authorization` and a legacy `x-api-key` header, Pagos will validate the `x-api-key` value and ignore the other. ### Account Updater and Network Tokenization If your integration uses [Account Updater](/account-updater/pagos-account-updater-tools) or [Network Tokenization](/network-tokenization/overview), the legacy authentication involved generating an HMAC signature and sending it with `x-client-key` and `x-date` headers. With the unified key, replace all three headers with a single `Authorization: Bearer ` header. You can remove the HMAC signature generation code entirely. **[Real-Time Account Updater (RTAU)](/account-updater/real-time-api-overview):** When using a unified API key, message encryption is no longer required. You can remove the Request Key and Response Key encryption steps from your integration if you choose. This is optional; we'll still accept encrypted payloads. **Batch Account Updater:** [PGP encryption](/account-updater/batch-api-overview#register-encryption-keys) of the batch request and response files is still required regardless of which key type you use. Only the authentication header changes. ## New API Domains The BIN Data APIs have moved to new domains: | Environment | Legacy domain | New domain | | :- | :- | :- | | Production | `parrot.prod.pagosapi.com` | `bin.pagos.ai` | | Sandbox | `parrot.sandbox.pagosapi.com` | `bin.sandbox.pagos.ai` | While both legacy and new domains work today, **the legacy domains will be retired on September 1, 2026.** Your API key type and endpoint are independent. While both legacy and unified API keys authenticate against *both* domains during this transition time, both the legacy API keys and legacy domains will be retired on September 1, 2026. See [Unified API Keys](#unified-api-keys) to update your API keys. ## New Static IP Addresses The new domains resolve to new static IP addresses. If you allowlist Pagos traffic in a firewall, add these: * `13.248.157.210` * `166.117.218.160` The legacy domains continue to resolve to their original addresses (`99.83.189.213` and `75.2.25.63`) until they're retired on September 1, 2026. Keep both sets allowlisted while you're mid-migration, and remove the legacy pair once you've fully cut over. ## Batch Download URLs Responses from the BIN Data Batch [`/batch/files`](/bin-data-APIs/endpoint/file-snapshot) endpoint contain a `url` field pointing at the file to download. Today, that URL still references the legacy domain even when you call the new one: ```json theme={null} { "url": "https://parrot.prod.pagosapi.com/batch/files/download?preSignedUrl=..." } ``` **This is expected.** On September 1, 2026, these URLs switch to the new domain: ```json theme={null} { "url": "https://bin.pagos.ai/batch/files/download?preSignedUrl=..." } ``` This switch happens on our side (server side), with no release required from you. That being said, check your code to ensure you use the returned `url` exactly as given, rather than extracting the path and appending it to a hardcoded domain. Integrations that follow the returned URL pick up the new domain automatically. ### Update Network Controls If you allowlist the download URLs you get back from the BIN Data Batch API, **downloads will start failing on September 1, 2026**. Following the URL dynamically isn't enough on its own, as the hostname inside it changes on that date. Any egress firewall rule, outbound proxy allowlist, or URL filter that permits `parrot.prod.pagosapi.com` for downloads must also permit `bin.pagos.ai` before September 1. This is easy to miss, because nothing in your own code changes and the failure appears without a deploy. Check for the download hostname in: * Outbound proxy or egress firewall rules * URL or domain allowlists on a corporate network * Any allowlist maintained by a data platform or ETL tool that fetches the file on your behalf Add `bin.pagos.ai` (production) and `bin.sandbox.pagos.ai` (sandbox) alongside your existing entry now and remove the legacy hostname after the cutover. If you allowlist by IP rather than hostname, add the [new IP addresses](#new-static-ip-addresses). Pass the `preSignedUrl` value through unchanged. It contains a temporary, expiring token, and its internal structure may change over time; don't decode, parse, or build logic around its contents. ## What Doesn't Change * **Request and response formats** - Apart from the batch `url` domain described above, no field is added, removed, or reformatted by this migration; switching to a unified key has no effect on response bodies * **Other headers** - Account Updater and Network Tokenization still require `X-Merchant-ID`, unchanged * **Batch AU file encryption** - Batch Account Updater still requires PGP encryption of request and response files * **Paths and query parameters** - Only the domain changes; `/bins`, `/batch/files`, and every other path stays the same * **Rate limits and entitlements** - Your unified key inherits the product access your organization already has ## Troubleshooting Usually a key sent in the wrong header. Pagos chooses how to validate your key based on the header you use, and doesn't fall back to the other: * `x-api-key` is always validated as a **legacy** key * `Authorization: Bearer` is always validated as a **unified** key A unified key sent as `x-api-key`, or a legacy key sent as `Authorization: Bearer`, fails even though the key itself is valid. Confirm the key type and header match. Also confirm the key matches the environment you're calling. [Test Mode](/getting-started/managing-your-pagos-account#test-mode) keys don't authenticate production requests. Your request reached a BIN Data API endpoint with no recognized authentication header. Confirm you're sending `Authorization: Bearer ` and that the header isn't being stripped by a proxy or gateway in front of your integration. Check which tab you created it under. Keys created on the **BIN Data API**, **Action API**, or **Data Ingestion & Observability API** tabs are legacy keys and won't authenticate with `Authorization: Bearer`. Create the key on the main **API Keys** tab instead. See the image in the [Unified API Keys](#unified-api-keys) section above for further clarification. Legacy keys only ever authenticate the single product they were issued for, so an integration calling several Pagos APIs may be holding one legacy key per product. A unified key covers every product your organization is entitled to. If a unified key is rejected by one product specifically, your organization may not have access to it; contact your Pagos Account Manager. Check your firewall rules. The new domains resolve to [different IP addresses](#new-static-ip-addresses) than the legacy ones. This is most likely caused by a network allowlist. From September 1, 2026, the `url` returned by [`/batch/files`](/bin-data-APIs/endpoint/file-snapshot) points at `bin.pagos.ai` instead of `parrot.prod.pagosapi.com`. If an egress firewall, outbound proxy, or URL filter only permits the legacy hostname, the download is blocked even though your integration is behaving correctly and nothing was deployed. Follow the steps under [Update Network Controls](#update-network-controls) to add `bin.pagos.ai` to the allowlist. Pagos displays a key's value only once, at creation. If you didn't store it, revoke that key and [generate a replacement](/authentication/authentication-overview#generate-an-api-key). ## Frequently Asked Questions If it's a legacy key, yes. Which domain you call and which key type you use are two separate things. A legacy key authenticates against the new domain today, but it stops working everywhere on September 1, 2026. Check whether your key is legacy using the [guidance above](#unified-api-keys). Legacy API keys stop authenticating requests, and the legacy domains stop serving traffic. Requests using either begin to fail. Batch download URLs also start returning the new domain from that date forward. No, that's the point of the change. One unified key authenticates every product your organization is entitled to. You **do** still need separate keys for Test Mode and Live Mode. Yes, until September 1, 2026. Both authenticate during the transition, so you can migrate one service or environment at a time. Send only one authentication header per request. Only the batch download `url` domain (starting September 1, 2026). Switching your key or your endpoint has no effect on response bodies. If you're seeing another difference, it isn't caused by this migration; contact [support@pagos.ai](mailto:support@pagos.ai) and we'll look into it. As many as you need. Separate keys per environment, service, or team make it easier to rotate or revoke one without disrupting everything else. Still have questions about migrating? Email [support@pagos.ai](mailto:support@pagos.ai). # Benchmarking Within Insights Source: https://docs.pagos.ai/benchmarking/benchmarking-within-insights **Beta Feature:** Pagos Benchmarking is currently in a closed Beta. Reach out to your Pagos Account Manager to request access. ## Overview Our benchmarking tool empowers your business to benchmark your payments performance trends against those of industry leaders and peers. You can use benchmarking to anonymously compare your historical payments data against relevant benchmarks to identify areas for improvement, recognize trends, and gain confidence in your processing capabilities. You can even confirm if any trends in your data are consistent across your industry or only affecting you! Pagos Benchmarking is powered by billions of transaction data points and custom card brand data feeds. Even more, the data is updated regularly and anonymized to provide you with the most up-to-date data comparisons possible without revealing the sources. Benchmarking is built within the [Pagos Insights platform](/insights/getting-started-with-insights) and available at an additional fee. ## BIN Benchmark The BIN Benchmark section of the Home page identifies the individual BINs that require your attention this week, including those for which your approval rate has fallen the furthest below the Pagos Benchmark. Learn more in the [Pagos Insights Home](/insights/home#bin-benchmark) guide. ## Benchmarking Metrics Benchmarking in Approval Rate Metrics Graph At this time, benchmarking capabilities are available in the **Approval Rate** tab of the [**Approvals**](/insights/metrics/approvals) Metrics page. To compare your approval rate data against your cohort, click the **Benchmark** toggle on the main graph. This adds the following to the approval rate graph: * **Benchmark Range** - The shaded area shows an estimated approval rate range (10th—90th percentile) for your cohort over time, reflecting approval rate trends and statistical variation across comparable businesses * **Median Line** - A line running through the estimated range, showing the median approval rate for your cohort **Chargebacks** will be the next Metrics page to include benchmarking capabilities. ### Filtering Benchmark Data Use the [bar lists](/insights/metrics#filtering-metrics-pages) below the main **Approval Rate** graph to filter your approval rate data. If you select filter parameters in the following bar lists, the filter will apply to both your data and the benchmark data: * Card Brand * Card Type * Stored Credential * Issuing Country If you use any other bar list to filter the data in your Approval page, the chosen filter parameter will be applied to *only your approval rate data* and not the benchmark range. This allows you to compare any segment of your own data to the cohort’s overall benchmark range. If your cohort doesn’t contain enough data to generate a benchmarking range for the chosen filter parameter, the main graph will display an **Unavailable** message. ### Important Notes on Benchmark Range Data Keep the following information in mind when using benchmarks: * Benchmarking is only available if you’ve set the [**Date Range** filter](/insights/insights-data-filters#filter-options) to a daily, weekly, or monthly time interval. * Historical benchmark ranges are available as far back as three months from today's date, provided there is enough data in the cohort. * To ensure cohort data is complete and up-to-date, benchmark ranges are not available for the last 3 days. * We calculate approval rate benchmark ranges after removing [duplicate retry data](/payments-basics/transaction-retry-deduplication) from your cohort’s attempted transaction count. To ensure a more direct comparison with your own data, turn on deduplicate filter (click **Dataset**, then click the **Deduplicate** toggle). # Getting Started With Pagos Benchmarking Source: https://docs.pagos.ai/benchmarking/getting-started-with-benchmarking **Beta Feature:** Pagos Benchmarking is currently in a closed Beta. Reach out to your Pagos Account Manager to request access. One of the most difficult aspects of payments data analytics is identifying when a metric warrants concern. Up until now, businesses have had no way to determine if their payments performance is actually optimized in comparison to their peers and competitors. That's why we've built Pagos Benchmarking. This powerful tool empowers your business to benchmark your payments performance against industry leaders and peers. In other words, you can anonymously compare your historical and real-time payments data against industry benchmarks to identify areas for improvement, recognize trends, and gain confidence in your processing capabilities. You can even confirm if any fluctuations in your data—changes in the type of declines or a degrading approval rate, for example—is consistent across your industry or only affecting you. Pagos Benchmarking is powered by billions of transaction data points and card brand data feeds. Even more, the data is updated weekly and anonymized to provide you with the most up-to-date data comparisons possible without revealing the sources. Whenever you need it, Pagos' benchmark data is at your fingertips. # Request Access If you're interested in adding Benchmarking to your Pagos subscription or want to get started with our payments optimization tools, [contact us for a demo](https://pagos.ai/contact/sales)! # BIN Data Batch API Dictionary Source: https://docs.pagos.ai/bin-data-APIs/batch-api-dictionary This guide is a repository of information that you can access in the Pagos BIN Data Batch file and use to refine your payments strategy or get to know your customers better. There are two types of data fields for which you can receive responses: [Standard](#standard-data-fields) and [Enhanced](#enhanced-data-fields). **Empty Field Responses:** The data provided in an individual field response depends on what data appears in the files Pagos receives from the card brands. If a field response is empty, this means our network files don't include any data for that field. Any bool fields marked as "Visa only" will return a `true` or `false` value for Visa BINs; for all non-Visa BINs, they'll return an empty value in the Batch file. If you're using BIN Data API, see the [BIN Data API Dictionary](/bin-data-APIs/bin-data-api-dictionary). ## Standard Data Fields | Data Field | Description | Example Response | | :- | :- | :- | | `bin_min` | Minimum PAN value for the BIN range | "4225090000000000000" | | `bin_max` | Maximum PAN value for the BIN range | "4225099999999999999" | | `product_name` | The card product name according to the card brand | "World Elite Mastercard card" | | `card_brand` | The name of the card brand | "Mastercard" | | `country_alpha2` | 2 letter country code representing the issuing country; Alpha 2 code meets the ISO3166 standards | "US" | | `country_name` | Issuing country name | "United States" | | `country_numeric` | Numeric country code representing the issuing country; the numeric country code meets ISO 3166 standards | "840" | | `type` | Indicator of the card type | "Debit" | | `bank_name` | Issuing bank name | "Bank of America National Association" | | `product_code` | The card product code according to the card brand | "MWE" | | `card_segment_type` | Indicator of consumer BIN or commercial BIN | "consumer" | | `prepaid` | Indicator of a prepaid BIN | "true" | | `correlation_id` | A unique Pagos ID that maps a BIN range to a specific network file; used for troubleshooting | "eyJGaWxlSWQiOjE0NDUsIlZlcnNpb24iOjEwfQ" | | `card_number_length` | The length of the underlying PAN | "16" | | `flagged_for_delete_remaining_wks` | Countdown in weeks until this BIN range is removed from the file; [learn more](/bin-data-APIs/batch-api-overview#bin-ttl-time-to-live) | "4" | ## Enhanced Data Fields | Data Field | Description | Example Response | | :- | :- | :- | | `clean_bank_name` | Pagos-harmonized bank name that has been formatted to proper case, removes unnecessary punctuation and misspellings, and spells out uncommon banking acronyms | "American Federal Credit Union" | | `bank_url` | Issuing bank website | "[https://www.bankofamerica.com](https://www.bankofamerica.com)" | | `bank_phone` | Issuing bank phone number | "180004321000" | | `regulated` | Indicator of the presence of an interchange regulation on a BIN | "true" | | `regulated_name` | The name of the interchange regulation | "GOVERNMENT NON-EXEMPT INTERCHANGE FEE (WITH FRAUD)" | | `reloadable` | Indicator of reloadable or non-reloadable prepaid | "false" | | `pan_or_token` | Indicator if the BIN is a PAN or a Network Token. Note: Mastercard uses the same BIN ranges for both PANs and tokens, meaning all Mastercard BINs can be a PAN and will therefore always return pan in this field—even for those that are actually tokens. Refer to the issuer\_supports\_tokenization field to determine if the BIN supports tokens | "pan" | | `account_updater` | (Visa-only field) Account Updater enabled | "true" | | `alm` | (Visa-only field) Indicator of a BIN or Account Range participating in Account Level Management | "true" | | `domestic_only` | (Visa-only field) Domestic-only BIN or Account Ranges | "true" | | `gambling_blocked` | (Visa-only field) Indicator that this BIN is not permitted to be used for online gambling | "true" | | `level2` | (Visa and Mastercard-only field) Indicator of Level 2 interchange rate eligibility | "true" | | `level3` | (Visa and Mastercard-only field) Indicator of Level 3 interchange rate eligibility | "true" | | `issuer_currency` | The currency that was issued to this BIN to transact in | "usd" | | `combo_card` | Indicator for a card that has combined card type capabilities | "credit and prepaid" | | `bin_length` | 6 or 8 digit BIN | "6" | | `authentication` | If additional customer authentication is required, this json array will indicate the authentication\_name; this field is hardcoded based on issuer country law | "authentication\_name": "EU PSD2 - SCA" | | `cost` | Identifies associated costs by name and amount, embedded as JSON in the column | see [Costs Fields](#cost-fields) | | `card_brand_is_additional` | Set to false if the BIN range is associated with a primary card network and set to true if associated with a secondary network (e.g. Star, pulse, nyce); note that secondary network's typically provide less in their BIN data. | "false" | | `issuer_supports_tokenization` | Set to true if the card brand data indicates the issuing bank supports network tokenization. Note: The field doesn't indicate if the associated card actually is a PAN or token, just what it supports | "true" | | `pagos_shared_bin` | **Deprecated.** This field has been replaced by `card_brand_is_additional`; for continuity, it remains in the batch file, but will always be set to `"false"` | "false" | | `billpay_enabled` | BIN has been enabled to make bill payments to service providers electronically, or over the internet | "false" | | `ecom_enabled` | BIN has been enabled to make ecommerce purchases, or purchases over the internet | "true" | | `virtual_card` | Set to true if the given BIN range supports virtual card creation. A null response indicates we do not know if there is support for virtual cards | “true” | | `funding_source` | Indicates the funding source for a payment card, which is different from the type. Note: This field only displays the funding source for Visa and Mastercard; all other brands will show null. | “deferred debit” | | `pagos_bin_length` | Indicates the length of the BIN as determined by Pagos using the bin\_min and bin\_max fields provided by the networks. | "8" | | `multi_account_access_indicator` | Indicates if a Visa card allows for Flexible Credentials functionality. (Note: This field is only available for Visa cards. All other brands will show null.) The possible values for this field are:
  • M - The card is multi-account managed, meaning the issuer manages which account is used and when
  • S - The card is multi-account self-serve, meaning the cardholder manages which account is used and when
  • N - The card is not a participant in multi-account functionality
| "M" | ### Costs Fields Depending on the cost data available for a BIN range, the JSON embedded in the cost column could include following fields: | Data Field | Description | Example Response | | :- | :- | :- | | **Interchange** | | see nested values | | `regulated` | | | | `regulated_name` | The name of the interchange regulation | "GOVERNMENT NON-EXEMPT INTERCHANGE FEE (WITH FRAUD)" | | **Domestic** | | see nested values | | `cap_region_shortname` | An abbreviated region name where the interchange cap applies | “Dom” | | `cap_advalorem_amount` | The interchange percentage assessed, shown in decimals for the capped interchange | “0.002” | | `cap_type_name` | The name of the regulated interchange cap | “US Durbin Regulation Debit Visa” | | `cap_fixed_amount` | If a fixed or regulated interchange amount applies, the amount will be shown here | “0.21” | | `cap_type_qualifier_currency` | The currency of the qualified fixed\_amount for the regulated or capped interchange | “usd” | | `cap_type_qualifier_text` | The description of the interchange cap or regulation | “US Durbin Regulation Debit Visa” | | `cap_type_qualifier_lower` | The minimum merchant processing volume amount limit for the interchange cap | "101mm" | | `cap_type_qualifier_upper` | The maximum merchant processing volume amount limit for the interchange cap | "500mm" | | **International** | | see nested values | | `cap_region_shortname` | An abbreviated region name where the interchange cap applies | "Inter" | | `cap_advalorem_amount` | The interchange percentage assessed, shown in decimals for the capped interchange | "0.0115" | | `cap_type_name` | The name of the regulated interchange cap | "EU MIF" | | `cap_fixed_amount` | If a fixed or regulated interchange amount applies the amount will be shown here | "0" | | `cap_type_qualifier_currency` | The currency of the qualified fixed\_amount for the regulated or capped interchange | "usd" | | `cap_type_qualifier_text` | The description of the interchange cap or regulation | "EU XB CNP MIF" | | `cap_type_qualifier_lower` | The minimum merchant processing volume amount limit for the interchange cap | "101mm" | | `cap_type_qualifier_upper` | The maximum merchant processing volume amount limit for the interchange cap | "500mm" | # BIN Data Batch API Overview Source: https://docs.pagos.ai/bin-data-APIs/batch-api-overview Subscribers to the Batch BIN File add-on can request a csv of updated BIN data via the BIN Data Batch API. This guide outlines the process of retrieving BIN bank and market details for your own local database using Pagos BIN Data Batch API. With the Batch BIN file, you can easily integrate BIN data into any bank or customer analysis you conduct. Batch is an in-house alternative to requesting directly from our database via the [BIN Data API](/bin-data-APIs/bin-data-api-overview). If you prefer a no-code method for downloading the Batch file, navigate to the **Batch** tab in the [BIN](/card-network-apis/bin#batch) section of your Pagos Service Panel. On **September 1, 2026**, legacy API keys and the legacy `parrot.prod.pagosapi.com` domain were retired, and batch download URLs switched to `bin.pagos.ai`. See the [September 2026 API Migration](/authentication/september-2026-api-migration) guide. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## How it works 1. Every Tuesday at 00:00 UTC, Pagos generates and publishes a new batch file with the most up-to-date BIN data from the card networks. 2. Pagos will pre-load the weekly database file for you. 3. You will call [/batch/files](/bin-data-APIs/endpoint/file-snapshot) to fetch URLs to the following weekly Batch files for download: a Basic file containing only [standard](/bin-data-APIs/batch-api-dictionary#standard-data-fields) BIN data, and an Enhanced file containing both standard and [enhanced](/bin-data-APIs/batch-api-dictionary#enhanced-data-fields) BIN data. 4. Follow the URLs to download the files. These file URLs are only valid for a short period of time and are unique to each call. Follow the `url` value exactly as returned, rather than rebuilding it from a hardcoded domain. **If you allowlist the download hostname, you must add `bin.pagos.ai`.** Following the returned URL dynamically isn't enough on its own—the hostname inside it changed on September 1, 2026, so an egress firewall or proxy that only permits `parrot.prod.pagosapi.com` will block downloads without any change on your side. Learn more in our [September 2026 API Migration](/authentication/september-2026-api-migration#update-network-controls) guide. ## File Changes When calling [/batch/files](/bin-data-APIs/endpoint/file-snapshot), the response will include a `changes` object, outlining the following changes to the Batch file since the previous week: * `bins_removed` - The number of BIN ranges (rows in the file) removed * `bins_updated` - The number of BIN ranges with updated information * `bins_added`- The number of new BIN ranges added The response will also include the percentage of BIN ranges that changed (removed, updated, or added) in the last week, broken out by [card brand](#brands-covered). ## Brands Covered At this time, the BIN Data API includes data for the following card brands. * Accel * Amex * ATM Card * Bancontact * Carte Bancaire * Cirrus * Culiance * Dankort * DinaCard * Diners Club * Discover * EBT * EFTPOS Australia * Elo * Hipercard * JCB * Korean Local * Maestro * Mastercard * MIR * NYCE * PayPal * Private Label * Prop * PULSE * RuPay * STAR * UATP * Unionpay * Visa ## BIN Data Batch Ranges When networks issue cards, they generate BINs in ranges. All BINs issued within a set range share flags indicating card currency, card type (e.g. prepaid, reloadable, etc.), local only, gambling enabled/not supported, etc. Because these flags are set at the range level—not the individual BIN level—Batch BIN Data similarly shares BIN details in ranges between a minimum and maximum value. Design your search logic to search for a BIN value within a given range. For example, if you want to review details for BIN `464565`, generate the 19-digit value for a card number, padded with zeros; search for all the rows where the card number `4645650000000000000` is between the `bin_min` and the `bin_max`. ### Super Ranges When adjacent BIN ranges share the exact same data, Pagos collapses them into a single row called a **super range**. The super range uses the `bin_min` value from the first adjacent range and the `bin_max` value from the last. By removing duplicate rows in the file, we can reduce the file size by roughly 5x. You don't need to change your search logic to accommodate super ranges. Because a super range spans the same `bin_min` to `bin_max` as the underlying ranges combined, any BIN value that falls within the span will match the super range row. ## BIN TTL (Time-To-Live) The Batch file includes a [`flagged_for_delete_remaining_wks`](/bin-data-APIs/batch-api-dictionary) column, providing continuity for BIN ranges now absent from the network source files. For each BIN range, the value in this column will be either: * **Null** - The BIN range is active and not flagged for deletion * A value **1-4** - The number of weeks until this BIN range is officially removed from the BIN Data Batch files The first week our network source files no longer contain a particular BIN range, we'll populate this field with a countdown starting with "4." Each subsequent week the BIN range remains absent, this value decreases by 1; by the fifth week, we remove the range entirely from the Batch file. If a network adds back a BIN range previously flagged for deletion, a "null" response replaces the countdown. This feature helps you: * Plan for upcoming BIN removals before they affect your systems * Maintain continuity when network files temporarily omit a BIN range due to errors * Distinguish between permanent BIN removals and temporary network file issues ### BIN TTL and Super Ranges When a BIN range within a [super range](#super-ranges) is removed from the network source file, Pagos both retains the original super range with the `flagged_for_delete_remaining_wks` countdown and creates new super ranges at the bifurcation points for the removed range. This gives you visibility into upcoming changes without losing the compact file structure. For example, before a card brand updates the source file, you see the following super range in the BIN Data Batch file: | bin\_min | bin\_max | | :- | :- | | 4010213200000000000 | 4010215599999999999 | Within this super range, the range **4010213900000000000 - 4010213999999999999** is removed from our network source files. The next Batch file accounts for this by retaining the original super range with the four week countdown and adding the new super ranges representing the remaining active portions of the original: | bin\_min | bin\_max | flagged\_for\_delete\_remaining\_wks | | :- | :- | :- | | 4010213200000000000 | 4010215599999999999 | 4 | | 4010213200000000000 | 4010213899999999999 | | | 4010214000000000000 | 4010215599999999999 | | The new super ranges have no countdown values, as they remain active. ## BIN Data Batch IP Addresses The following static IP addresses can be used to allowlist API traffic to BIN Data Batch: * `13.248.157.210` * `166.117.218.160` ## Testing You can explore a mock Pagos Batch BIN file in sandbox by enabling [Test Mode](/getting-started/managing-your-pagos-account#test-mode) and following the [testing](/bin-data-APIs/batch-api-testing) details. # BIN Data Batch API Testing Source: https://docs.pagos.ai/bin-data-APIs/batch-api-testing Ensure your integration with the BIN Data Batch API works correctly by making calls to our simulator in Test Mode. ## Step 1: Create a Pagos Account or Sign In If you’re interested in the BIN Data Batch API, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Key In Test Mode, generate an API Key for the BIN Data Batch API. These API Keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API keys: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test retreiving Batch BIN file using the BIN Data Batch API Make a call to the BIN Data Batch API in Test Mode. Note that the endpoint for Test Mode points to **sandbox**. ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/batch/files' \ --header 'Authorization:Bearer ' ``` This will return an array of download URLs for two mock BIN files: a Basic file containing only [standard](/bin-data-APIs/batch-api-dictionary#standard-data-fields) BIN data, and an Enhanced file containing both standard and [enhanced](/bin-data-APIs/batch-api-dictionary#enhanced-data-fields) BIN data. Follow the URLs to download the files. These URLs are only valid for a short period of time and are unique to each call. ```json theme={null} [ { "type": "enhanced", "name": "parrot-batch-enhanced-2025-07-02T13:11:42.9915907Z.gz", "url": "https://bin.sandbox.pagos.ai/batch/files/download?preSignedUrl=aHR0cHM6Ly9wYXJyb3QtdjMtc25hcHNob3RzLXNhbmRib3guczMuYW1hem9uYXdzLmNvbS9lbmhhbmNlZC8yNDM1LTIwMjUtMDctMDJUMTM6MTE6NDIuOTkxNTkwN1ouZ3o/QVdTQWNjZXNzS2V5SWQ9QVNJQTU0SkpBVjczWlFaTERBREkmRXhwaXJlcz0xNzU3NDcxNTE0JngtYW16LXNlY3VyaXR5LXRva2VuPUlRb0piM0pwWjJsdVgyVmpFSGNhQ1hWekxXVmhjM1F0TVNKSE1FVUNJUUN3U21rN2dNR1ozNHJndGJUYlolMkJ4Nzd1d1Z1dGtFMmIlMkZuRWwxeWxZcnNTd0lnR012ak53SkpxUkpvYkluc0N0QWgxJTJCWTMwUG4yZ1dZcEVFOEc1b3M3WGlJcW1nUUk0UCUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRkFSQUFHZ3c1TlRReE1EVTJNemc1TURNaURFQWpvODJGUUpkUkRGN1B0Q3J1QXg3MjR0SHJRR0tRT0FYVkdzVUtqQ2Ewc3FaZ2E3SEdQeXFQWnBwclJNJTJCUDIzdE0lMkJ0WlhDRVpGekJSS3RMUEkzeFBnaW1xdjlRd2JlRVk4OURwWXNPWnB0dnQlMkJhbVBiQ3ZGejRldW5DWiUyQmlvQlZmM2E3SXRVMFhkQ0ltd3NzUHFmbk05R1lZdmNaY2w0TEtkaDByWWJkN29hMmZTbThQWE50Um9UZUJoRWVoQzVVWnpoZ1NDaXNFemRTVnhEZWcxNzBuTzdtclQzTExsMUVLUnglMkJZdkxvRVU0YlU0bVFHcmRGZXRCcFJwaFUzaVZ4azlHSjljbkh2QSUyRnBxMmZLUTJWa2QwTURQZUhqZ0o0VTFBY2EzaHBDWXl2U0dpRDhuNkdEM1g4V3psT0R4RHpVN0pwU0M0S3RWR0RxZXozVWZXczVkWlRCaTNueVIwYXhPMWRjYUsyemZSMHFOMzdWZFM5VzE3Y2pJTk14dlZqeDFVdHRibmJUN3BwNVF5dWY5emRGQjdZazFPYnNuN3NicDhsWUxLUnlFS0gwVDBZZXNYVGQ0dUtvdkVPRmxZa1E0dyUyQjUlMkY1dHQyNiUyQnpxRnR0RlYxJTJCYUNLMW1qeTVZMjh4U0VUNlpsVG1COWVJJTJCRGdRUExjYWRQb01iZ21ESTJqRFZPY3JodEJGUmdXdGFza0g4amElMkJ5ZVZLN0ZUTkhoZTNjUUNRUUNvSmczaVlvTFJHNHdER2xYVG5tR3pQWG83aEI3NHJ5bTMyb2pFeVBoaGZmNWo1YmdGNFdpZkdHdU5MS3FtRjVJVEpIRjdDNiUyRnlHWVRjeURSQW1vWnM1cnd6dnBtYmslMkYlMkY3Z3NnaEFLQVJuUzJWUDJOYTJacDZmbG5NNWpNNlpoTUpYWmdzWUdPcVlCT0lGRllFYzlFTlhPaThuZ1lKWUx3TjdtTkdOMDFwTXlwNndmWFVqVjlhTDVWR2NkcXp2QVRrd3kwJTJGVFQwYnZ1OTNoSU5SUks5cVNSSE5qZWI2VVNDaXpDaHViS2YlMkZFUmdhOTZBY2ZNRHJVQTgwSUVONzNVQTNzU3RBRkFyMzdMOVpFZEVGZ3lOckxySDV0dTQyRTIzYTFab0RrVkpjTm9pZk4yelJ4bEtEaFJ1MW9ZdEtlYnpzdGpQckE5V0Z3U1RVSWtQT3FZMExRRjVmbkhEemJ2V1lIRlhlbmtFUSUzRCUzRCZTaWduYXR1cmU9UmllcjJXbyUyQmFTWFdYZHklMkZXQSUyRlNNTWNweWxVJTNE", "changes": { "bins_removed": 0, "bins_updated": 0, "bins_added": 0, "last_update_date": "2025-06-24T00:00:29.4982520Z", "sources": [ { "bins_total": 6, "source": "MASTERCARD", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "VISA", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "DISCOVER", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "AMEX", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "CULIANCE", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "NYCE", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "PINLESS", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "PAGOS_DATA", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } }, { "bins_total": 6, "source": "EFTPOS_AUSTRALIA", "changes": { "percentage": "0.00", "removed": 0, "updated": 0, "added": 0 } } ] } }, { "type": "basic", "name": "parrot-batch-basic-2025-07-02T13:12:41.1270632Z.gz", "url": "https://bin.sandbox.pagos.ai/batch/files/download?preSignedUrl=aHR0cHM6Ly9wYXJyb3QtdjMtc25hcHNob3RzLXNhbmRib3guczMuYW1hem9uYXdzLmNvbS9iYXNpYy8yNDM1LTIwMjUtMDctMDJUMTM6MTI6NDEuMTI3MDYzMlouZ3o/QVdTQWNjZXNzS2V5SWQ9QVNJQTU0SkpBVjczWlFaTERBREkmRXhwaXJlcz0xNzU3NDcxNTE0JngtYW16LXNlY3VyaXR5LXRva2VuPUlRb0piM0pwWjJsdVgyVmpFSGNhQ1hWekxXVmhjM1F0TVNKSE1FVUNJUUN3U21rN2dNR1ozNHJndGJUYlolMkJ4Nzd1d1Z1dGtFMmIlMkZuRWwxeWxZcnNTd0lnR012ak53SkpxUkpvYkluc0N0QWgxJTJCWTMwUG4yZ1dZcEVFOEc1b3M3WGlJcW1nUUk0UCUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRiUyRkFSQUFHZ3c1TlRReE1EVTJNemc1TURNaURFQWpvODJGUUpkUkRGN1B0Q3J1QXg3MjR0SHJRR0tRT0FYVkdzVUtqQ2Ewc3FaZ2E3SEdQeXFQWnBwclJNJTJCUDIzdE0lMkJ0WlhDRVpGekJSS3RMUEkzeFBnaW1xdjlRd2JlRVk4OURwWXNPWnB0dnQlMkJhbVBiQ3ZGejRldW5DWiUyQmlvQlZmM2E3SXRVMFhkQ0ltd3NzUHFmbk05R1lZdmNaY2w0TEtkaDByWWJkN29hMmZTbThQWE50Um9UZUJoRWVoQzVVWnpoZ1NDaXNFemRTVnhEZWcxNzBuTzdtclQzTExsMUVLUnglMkJZdkxvRVU0YlU0bVFHcmRGZXRCcFJwaFUzaVZ4azlHSjljbkh2QSUyRnBxMmZLUTJWa2QwTURQZUhqZ0o0VTFBY2EzaHBDWXl2U0dpRDhuNkdEM1g4V3psT0R4RHpVN0pwU0M0S3RWR0RxZXozVWZXczVkWlRCaTNueVIwYXhPMWRjYUsyemZSMHFOMzdWZFM5VzE3Y2pJTk14dlZqeDFVdHRibmJUN3BwNVF5dWY5emRGQjdZazFPYnNuN3NicDhsWUxLUnlFS0gwVDBZZXNYVGQ0dUtvdkVPRmxZa1E0dyUyQjUlMkY1dHQyNiUyQnpxRnR0RlYxJTJCYUNLMW1qeTVZMjh4U0VUNlpsVG1COWVJJTJCRGdRUExjYWRQb01iZ21ESTJqRFZPY3JodEJGUmdXdGFza0g4amElMkJ5ZVZLN0ZUTkhoZTNjUUNRUUNvSmczaVlvTFJHNHdER2xYVG5tR3pQWG83aEI3NHJ5bTMyb2pFeVBoaGZmNWo1YmdGNFdpZkdHdU5MS3FtRjVJVEpIRjdDNiUyRnlHWVRjeURSQW1vWnM1cnd6dnBtYmslMkYlMkY3Z3NnaEFLQVJuUzJWUDJOYTJacDZmbG5NNWpNNlpoTUpYWmdzWUdPcVlCT0lGRllFYzlFTlhPaThuZ1lKWUx3TjdtTkdOMDFwTXlwNndmWFVqVjlhTDVWR2NkcXp2QVRrd3kwJTJGVFQwYnZ1OTNoSU5SUks5cVNSSE5qZWI2VVNDaXpDaHViS2YlMkZFUmdhOTZBY2ZNRHJVQTgwSUVONzNVQTNzU3RBRkFyMzdMOVpFZEVGZ3lOckxySDV0dTQyRTIzYTFab0RrVkpjTm9pZk4yelJ4bEtEaFJ1MW9ZdEtlYnpzdGpQckE5V0Z3U1RVSWtQT3FZMExRRjVmbkhEemJ2V1lIRlhlbmtFUSUzRCUzRCZTaWduYXR1cmU9UW9MRiUyQlhQbktMMXhub2E1cVYyVHB0ek9LdFklM0Q=", "changes": { "bins_removed": 0, "bins_updated": 0, "bins_added": 0, "last_update_date": "2025-06-24T00:00:29.4982520Z", "sources": null } } ] ``` # BIN Benchmark API Dictionary Source: https://docs.pagos.ai/bin-data-APIs/bin-benchmark-api-dictionary This guide is a repository of information about the fields returned by the Pagos BIN Benchmark API. The response contains benchmark metrics for a given BIN range (when available), allowing you to compare your performance to that of the broader Pagos network. ## BIN Benchmark Object Fields | Data Field | Variable Type | Required | Description | Example | | :- | :- | :- | :- | :- | | `bin_benchmark` | object | No | Top-level benchmark object; [`null`](#missing-or-insufficient-data-response) if the BIN doesn't exist or there isn't enough network data to calculate a benchmark | see nested value | | `bin_matched` | integer | Yes | The BIN prefix actually used to calculate the benchmark. Can be shorter than the queried `bin` value if Pagos falls back to a shorter prefix with sufficient data; see [Partial Matches](/bin-data-APIs/bin-benchmark-api-overview#partial-matches) | `412345` | | `auth_rate` | object | Yes | Approval rate metrics for the matched BIN | see nested values | | `cardholder_initiated` | number | Yes | Network approval rate for customer-initiated transactions (CITs) on the matched BIN | `0.865` | | `merchant_initiated` | number | Yes | Network approval rate for merchant-initiated transactions (MITs) on the matched BIN | `0.838` | ## Example Response ```json theme={null} { "bin_benchmark": { "bin_matched": 412345, "auth_rate": { "cardholder_initiated": 0.865, "merchant_initiated": 0.838 } } } ``` ### Missing or Insufficient Data Response ```json theme={null} { "bin_benchmark": null } ``` # BIN Benchmark API Error Handling Source: https://docs.pagos.ai/bin-data-APIs/bin-benchmark-api-error-handling If the BIN Benchmark API fails, you'll receive an error response with an appropriate HTTP status code. A BIN that doesn't exist, or that doesn't have enough transaction volume to calculate a benchmark, is **not** an error. In both cases, the API returns a `200` response with `bin_benchmark` set to `null`; learn more about [missing or insufficient network BIN data](/bin-data-APIs/bin-benchmark-api-overview#missing-or-insufficient-data). There is no `BIN_NOT_FOUND` error for this endpoint. ## Error Responses | HTTP Response Code | Error Code | Description | | :- | :- | :- | | 400 | `INVALID_BIN_FORMAT` | BIN is malformed or incorrect length; BIN must contain only numeric digits, be between 6 and 10 characters in length, and can't include spaces or special characters | | 400 | `MISSING_PARAMETER` | Required `bin` query parameter not provided | | 401 | `MISSING_AUTHORIZATION` | Authorization header not present | | 401 | `INVALID_API_KEY` | API key is invalid or expired | | 403 | `INSUFFICIENT_PERMISSIONS` | Account isn't opted in to data sharing; the BIN Benchmark API is only available to businesses that have opted in to data sharing with Pagos. Contact your Pagos Account Manager to enable this feature. | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests made in time window; if you exceed the [rate limit](/bin-data-APIs/bin-benchmark-api-overview#bin-benchmark-api-limits) of 100 calls every 10 seconds, wait briefly before retrying or consider implementing exponential backoff in your integration. | | 500 | `INTERNAL_ERROR` | Unexpected server error | | 503 | `SERVICE_UNAVAILABLE` | Service temporarily unavailable | ## Error Response Format Error responses are returned in the following JSON format: ```json theme={null} { "message": "INVALID_BIN_FORMAT" } ``` # BIN Benchmark API Overview Source: https://docs.pagos.ai/bin-data-APIs/bin-benchmark-api-overview Query benchmarked metrics for a BIN, calculated from Pagos network transaction data The Pagos BIN Benchmark API returns benchmark metrics for a given BIN range, calculated from the billions of transaction data points Pagos has ingested from merchants who opt in to data sharing. You can use this API to see how your own performance for a BIN compares to the broader Pagos network. The BIN Benchmark API is only available to businesses that have opted in to data sharing with Pagos. Contact your Pagos Account Manager to enable this feature. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Look Up BIN Benchmark Data You can use cURL on the command line to submit BIN Benchmark API requests, but you can also use API query tools like Postman or integrate the API directly into your systems. Here's a cURL example for benchmark details on BIN `41234567`: ```bash theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins/benchmark?bin=41234567' \ --header 'Authorization: Bearer ' ``` This will return the available benchmark metrics for the BIN: ```json theme={null} { "bin_benchmark": { "bin_matched": 412345, "auth_rate": { "cardholder_initiated": 0.865, "merchant_initiated": 0.838 } } } ``` Note that `bin_matched` (`412345`) has fewer digits than the `bin` value submitted (`41234567`). See [Partial Matches](#partial-matches) below for why. If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq). For a full list of response fields, see the [BIN Benchmark API Dictionary](/bin-data-APIs/bin-benchmark-api-dictionary). ## Partial Matches If you submit a BIN longer than six digits, Pagos may not have enough transaction volume at that full length to calculate a reliable benchmark. In that case, we fall back to the closest shorter BIN-6 prefix that has sufficient data. `bin_matched` relays that shorter prefix rather than the full value you submitted. Use `bin_matched` to tell whether a response reflects your exact BIN or a broader fallback match. In the example above, querying the 8-digit BIN `41234567` returned benchmark data for the 6-digit prefix `412345`. ## Missing or Insufficient Data The `bin_benchmark` object is returned as `null` when Pagos can't provide a benchmark for the queried BIN, which happens in two cases: * **Missing BIN** - The BIN doesn't exist in the Pagos BIN Database * **Insufficient data** - The BIN exists, but Pagos doesn't have enough transaction volume for it to calculate a reliable benchmark In both cases, the API will not charge you for a failed benchmark lookup: ```json theme={null} { "bin_benchmark": null } ``` ## BIN Benchmark API Limits The following are the API limits for BIN Benchmark API calls: | BIN Benchmark API | API Endpoint | API Limit | | :- | :- | :- | | BIN Benchmark Lookup | `/bins/benchmark` | 100 calls every 10 seconds | ## BIN Benchmark API IP Addresses The following static IP addresses can be used to allowlist API traffic to the Pagos BIN Benchmark API: * `13.248.157.210` * `166.117.218.160` ## Testing You can explore the Pagos BIN Benchmark API in sandbox by enabling [Test Mode](/getting-started/managing-your-pagos-account#test-mode) and following the [testing](/bin-data-APIs/bin-benchmark-api-testing) details. # BIN Benchmark API Testing Source: https://docs.pagos.ai/bin-data-APIs/bin-benchmark-api-testing Ensure your integration with the BIN Benchmark API works correctly by making calls to our simulator in Test Mode. ## Step 1: Create a Pagos Account or Sign In If you're interested in the BIN Benchmark API, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Keys In Test Mode, generate an API Key for the BIN Benchmark API. These API Keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test Looking up BIN Benchmark Data Use our [test BINs](#test-bins) to test looking up BIN benchmark data in Test Mode. Note the endpoint for Test Mode points to **sandbox**, and—unlike other BIN Data API sandboxes—the BIN Benchmark API simulator only supports the exact BIN values listed below rather than entire BIN ranges. ### BIN-6 to BIN-6 Match Querying a 6-digit BIN returns benchmark data matched at the same length: ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/benchmark?bin=485427' \ --header 'Authorization: Bearer ' ``` This will return the mock benchmark details, with `bin_matched` equal to the 6-digit BIN you queried: ```json theme={null} { "bin_benchmark": { "bin_matched": 485427, "auth_rate": { "cardholder_initiated": 0.825, "merchant_initiated": 0.866 } } } ``` ### BIN-8 to BIN-6 Match (Partial Match) Querying an 8-digit BIN doesn't guarantee a match at that same length. In this example, Pagos doesn't have enough transaction volume at the full 8-digit length, so the response falls back to the closest 6-digit prefix with sufficient data; learn more about [partial matches](/bin-data-APIs/bin-benchmark-api-overview#partial-matches). ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/benchmark?bin=42380850' \ --header 'Authorization: Bearer ' ``` This will return the mock benchmark details, with `bin_matched` truncated to the 6-digit prefix `423808`: ```json theme={null} { "bin_benchmark": { "bin_matched": 423808, "auth_rate": { "cardholder_initiated": 0.744, "merchant_initiated": 0.801 } } } ``` ### BIN-8 to BIN-8 Match Some 8-digit BINs do have enough transaction volume for Pagos to calculate a reliable benchmark at the full length. In this example, the response matches at the same 8 digits queried: ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/benchmark?bin=54076555' \ --header 'Authorization: Bearer ' ``` This will return the mock benchmark details, with `bin_matched` equal to the 8-digit BIN you queried: ```json theme={null} { "bin_benchmark": { "bin_matched": 54076555, "auth_rate": { "cardholder_initiated": 0.885, "merchant_initiated": 0.893 } } } ``` ### No Match or Insufficient Data If the queried BIN doesn't exist in the Pagos BIN Database, or Pagos doesn't have enough transaction volume for it, `bin_benchmark` is returned as `null`; learn more about [missing or insufficient network BIN data](/bin-data-APIs/bin-benchmark-api-overview#missing-or-insufficient-data). ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/benchmark?bin=311338' \ --header 'Authorization: Bearer ' ``` This will return a `null` benchmark: ```json theme={null} {"bin_benchmark": null} ``` ## Test BINs Unlike the other BIN Data API sandboxes, the BIN Benchmark API simulator matches against the exact BIN values below rather than entire BIN ranges. Use these BIN values, as-is, for testing. | BIN | Network | Match Type | | :- | :- | :- | | `485427` | VISA | BIN-6 to BIN-6 match | | `42380850` | VISA | BIN-8 to BIN-6 match (partial match) | | `54076555` | MASTERCARD | BIN-8 to BIN-8 match | | `311338` | AMEX | No match / insufficient data | # BIN Continuity API Dictionary Source: https://docs.pagos.ai/bin-data-APIs/bin-continuity-api-dictionary This guide is a repository of information about the fields returned by the Pagos BIN Continuity API. The response includes lifecycle metadata in the `continuity` object and the last known card attributes in the nested `card` object. The `card` object contains the same fields as the [BIN Data API](/bin-data-APIs/bin-data-api-dictionary) enhanced response. This represents the current state of an active BIN, or the last known state of a BIN before it was deleted from the Pagos BIN Database. ## Continuity Object Fields | Field | Type | Required | Description | Example | | :- | :- | :- | :- | :- | | `bin` | string | Yes | The queried BIN value (6-10 digits) | `"41234567"` | | `bin_min` | string | Yes | Minimum PAN value for the BIN range | `"4123456700000000"` | | `bin_max` | string | Yes | Maximum PAN value for the BIN range | `"4123456799999999"` | | `status` | string | Yes | Current lifecycle status of the BIN; see [Status Values](/bin-data-APIs/bin-continuity-api-overview#bin-lifecycle-statuses) | `"active"` | | `first_seen_at` | string (ISO 8601) | Yes | Timestamp of the first BIN file in which this BIN range appeared | `"2019-03-15T00:00:00Z"` | | `last_seen_at` | string (ISO 8601) | Yes | Timestamp of the most recent BIN file in which this BIN range was present | `"2024-11-01T00:00:00Z"` | | `flagged_for_delete_at` | string (ISO 8601) | No | Timestamp when the BIN was marked for deletion; `null` if never flagged | `"2024-10-15T00:00:00Z"` | | `deleted_at` | string (ISO 8601) | No | Timestamp when the BIN was removed from the BIN file; `null` if still active | `"2024-11-01T00:00:00Z"` | | `days_active` | integer | Yes | Total number of days the BIN range was/has been present in BIN files | `2058` | | `file_appearances` | integer | Yes | Count of BIN file versions containing this BIN range | `68` | | `card` | object | Yes | Last known card attributes for this BIN range; see [Card Object](#card-object) | see below | ## Card Object The `card` object contains the last known attributes for the BIN range. This is the same structure as the [BIN Data API enhanced response](/bin-data-APIs/bin-data-api-dictionary#enhanced-data-fields). For deleted BINs, this represents the state of the BIN at the time it was last present in a network source file. ## Example Response ```json theme={null} { "continuity": { "bin": "41234567", "bin_min": "4123456700000000", "bin_max": "4123456799999999", "status": "deleted", "first_seen_at": "2019-03-15T00:00:00Z", "last_seen_at": "2024-10-01T00:00:00Z", "flagged_for_delete_at": "2024-10-15T00:00:00Z", "deleted_at": "2024-11-15T00:00:00Z", "days_active": 2028, "file_appearances": 65, "card": { "number": { "length": 16 }, "bin_length": 8, "pagos_bin_length": 8, "bin_min": "4123456700000000", "bin_max": "4123456799999999", "pan_or_token": "PAN", "virtual_card": false, "level2": true, "level3": true, "alm": true, "account_updater": true, "domestic_only": false, "gambling_blocked": false, "issuer_currency": "USD", "reloadable": false, "card_brand": "VISA", "card_segment_type": "CONSUMER", "combo_card": null, "type": "CREDIT", "funding_source": "CREDIT", "prepaid": false, "product": { "product_id": "A", "product_name": "Visa Traditional" }, "bank": { "name": "CHASE BANK USA, N.A.", "phone": "1-800-935-9935", "url": "www.chase.com", "clean_name": "Chase" }, "country": { "alpha2": "US", "numeric": "840", "name": "United States" }, "authentication": { "authentication_required": true, "authentication_name": "3DS" }, "cost": { "interchange": { "regulated": false, "regulated_name": null, "domestic": { "cap_region_shortname": "US", "cap_advalorem_amount": "1.65", "cap_type_name": "PERCENT_PLUS_FIXED", "cap_fixed_amount": "0.10", "cap_type_qualifier_currency": "USD", "cap_type_qualifier_text": null, "cap_type_qualifier_lower": null, "cap_type_qualifier_upper": null }, "inter": null, "intra": null, "notes": null } }, "networkfees": {}, "issuer_supports_tokenization": true, "multi_account_access_indicator": null, "shared_bin": false, "flagged_for_delete_remaining_wks": null } }, "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` # BIN Continuity API Error Handling Source: https://docs.pagos.ai/bin-data-APIs/bin-continuity-api-error-handling If the BIN Continuity API fails, you'll receive an error response with an appropriate HTTP status code. ## Error Responses | HTTP Response Code | Error Code | Description | | :- | :- | :- | | 400 | `INVALID_BIN_FORMAT` | BIN is malformed or incorrect length; [learn more](#invalid-bin-format-400) | | 400 | `MISSING_PARAMETER` | Required `bin` query parameter not provided | | 401 | `MISSING_AUTHORIZATION` | Authorization header not present | | 401 | `INVALID_API_KEY` | API key is invalid or expired | | 403 | `INSUFFICIENT_PERMISSIONS` | API key lacks access to this endpoint | | 404 | `BIN_NOT_FOUND` | No continuity record exists for the BIN; [learn more](#bin-not-found-404) | | 429 | `RATE_LIMIT_EXCEEDED` | [Too many requests](#rate-limit-exceeded-429) in time window | | 500 | `INTERNAL_ERROR` | Unexpected server error | | 503 | `SERVICE_UNAVAILABLE` | Service temporarily unavailable | ## Error Response Format Error responses are returned in the following JSON format: ```json theme={null} { "message": "[ERROR MESSAGE]" } ``` ## Common Error Scenarios ### BIN Not Found (404) Unlike the standard `/bins` endpoint which returns 404 for BINs not in the current file, the `/bins/continuity` endpoint only returns 404 if the BIN has **never** existed in any Pagos BIN file. If a BIN was previously active but has since been deleted, the continuity endpoint will return the historical data with the [status](/bin-data-APIs/bin-continuity-api-overview#bin-lifecycle-statuses) `"deleted"`. ### Invalid BIN Format (400) Ensure your BIN value: * Contains only numeric digits * Is between 6 and 10 characters in length * Does not include spaces or special characters ### Rate Limit Exceeded (429) If you exceed the [rate limit](/bin-data-APIs/bin-continuity-api-overview#bin-continuity-api-limits) of 100 calls every 10 seconds, wait briefly before retrying. Consider implementing exponential backoff in your integration. # BIN Continuity API Overview Source: https://docs.pagos.ai/bin-data-APIs/bin-continuity-api-overview Query the lifecycle history of BIN ranges, including deleted BINs The Pagos BIN Continuity API provides historical lifecycle data for BIN ranges, including when they were first seen in the network source files, last seen, and their current status. You can use this API to research the history of a specific BIN, including those we've removed from the standard BIN file. The BIN Continuity API returns data for all BIN ranges that have *ever* appeared in Pagos' BIN database files. Calls to the standard [BIN Data API](/bin-data-APIs/bin-data-api-overview) only return currently active BIN ranges. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Look Up BIN History You can use cURL on the command line to submit BIN Continuity API requests, but you can also use API query tools like Postman or integrate the API direclty into your systems. Here's a cURL example for continuity details on BIN `41234567`: ```bash theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins/continuity?bin=41234567' \ --header 'Authorization: Bearer ' ``` This will return the lifecycle history and last known card data for the BIN: ```json theme={null} { "continuity": { "bin": "41234567", "bin_min": "4123456700000000", "bin_max": "4123456799999999", "status": "active", "first_seen_at": "2019-03-15T00:00:00Z", "last_seen_at": "2024-11-01T00:00:00Z", "flagged_for_delete_at": null, "deleted_at": null, "days_active": 2058, "file_appearances": 68, "card": { "number": { "length": 16 }, "card_brand": "VISA", "type": "CREDIT", "prepaid": false, "product": { "product_id": "A", "product_name": "Visa Traditional" }, "bank": { "name": "CHASE BANK USA, N.A.", "clean_name": "Chase" }, "country": { "alpha2": "US", "numeric": "840", "name": "United States" } } }, "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq). ## BIN Lifecycle Statuses The `status` field in the response indicates where the BIN is in its lifecycle: | Status | Description | | :- | :- | | `active` | BIN is currently present in the BIN file and available via the standard `/bins` endpoint | | `flagged_for_delete` | BIN has been marked for deletion but is still present in the BIN file. See [BIN TTL](#bin-ttl-time-to-live) for details | | `deleted` | BIN has been removed from the BIN file and is no longer available via the standard `/bins` endpoint | ## BIN TTL (Time-To-Live) When a BIN range is no longer present in the card network source files, Pagos doesn't immediately remove that range from the Pagos BIN Database. Instead, we provide a grace period, tracked with the `flagged_for_delete_remaining_wks` field in the [BIN Data API](/bin-data-APIs/bin-data-api-overview#bin-ttl-time-to-live) and the [BIN Data Batch file](/bin-data-APIs/batch-api-overview#bin-ttl-time-to-live). The BIN Continuity API tracks this lifecycle with the `flagged_for_delete_at` and `deleted_at` timestamps. ## Use Cases The BIN Continuity API is particularly useful for: * **Investigating missing BINs** - When a BIN that previously returned data stops appearing in the standard `/bins` endpoint, use `/bins/continuity` to understand why and when it was removed * **Historical research** - Access the last known data for a BIN range even after it has been removed from the current BIN file * **Monitoring BIN lifecycle** - Track when BINs were first added to network files, how long they've been active, and their deletion timeline * **Fallback data** - Use the `card` object as a fallback when the BIN is no longer in the active file but historical data is still valuable for your use case ## BIN Continuity API Limits The following are the API limits for BIN Continuity API calls: | BIN Continuity API | API Endpoint | API Limit | | :- | :- | :- | | BIN Continuity Lookup | [/bins/continuity](/bin-data-APIs/endpoint/continuity) | 100 calls every 10 seconds | ## BIN Continuity API IP Addresses The following static IP addresses can be used to allowlist API traffic to the Pagos BIN Continuity API: * `13.248.157.210` * `166.117.218.160` ## Testing You can explore the Pagos BIN Continuity API in sandbox by enabling [Test Mode](/getting-started/managing-your-pagos-account#test-mode) and following the [testing](/bin-data-APIs/bin-continuity-api-testing) details. # BIN Continuity API Testing Source: https://docs.pagos.ai/bin-data-APIs/bin-continuity-api-testing Ensure your integration with the BIN Continuity API works correctly by making calls to our simulator in Test Mode. ## Step 1: Create a Pagos Account or Sign In If you're interested in the BIN Continuity API, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Keys In Test Mode, generate an API Key for the BIN Continuity API. These API Keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test Looking up BIN Continuity Use our [test BIN ranges](#test-ranges) to test looking up BIN continuity in Test Mode. Note that the endpoint for Test Mode points to **sandbox**. ### Active BIN Example ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/continuity?bin=485427' \ --header 'Authorization: Bearer ' ``` This will return the mock continuity details for an active BIN: ```json theme={null} { "continuity": { "bin": "485427", "bin_min": "4854270000000000000", "bin_max": "4854279999999999999", "status": "active", "first_seen_at": "2020-01-15T00:00:00Z", "last_seen_at": "2024-12-10T00:00:00Z", "flagged_for_delete_at": null, "deleted_at": null, "days_active": 1791, "file_appearances": 256, "card": { "number": { "length": 16 }, "bin_length": 6, "pagos_bin_length": 6, "bin_min": "4854270000000000000", "bin_max": "4854279999999999999", "pan_or_token": "pan", "card_brand": "VISA", "card_segment_type": "Business", "type": "Debit", "funding_source": "DEBIT", "prepaid": false, "product": { "product_id": "G", "product_name": "Visa Business" }, "bank": { "name": "SPACE COAST CREDIT UNION", "clean_name": "Space Coast Credit Union" }, "country": { "alpha2": "US", "numeric": "840", "name": "UNITED STATES OF AMERICA" } } }, "correlation_id": "test-1234-5678-90ab-cdef12345678" } ``` ### Deleted BIN Example To test the response for a deleted BIN, use one of the deleted test ranges: ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins/continuity?bin=65031117' \ --header 'Authorization: Bearer ' ``` This will return the mock continuity details for a deleted BIN: ```json theme={null} { "continuity": { "bin": "65031117", "bin_min": "6503111700000000000", "bin_max": "6503111799999999999", "status": "deleted", "first_seen_at": "2018-06-01T00:00:00Z", "last_seen_at": "2024-09-15T00:00:00Z", "flagged_for_delete_at": "2024-09-22T00:00:00Z", "deleted_at": "2024-10-20T00:00:00Z", "days_active": 2298, "file_appearances": 328, "card": { "number": { "length": 16 }, "card_brand": "DISCOVER", "type": "Credit", "prepaid": false, "bank": { "name": "DISCOVER BANK", "clean_name": "Discover Bank" }, "country": { "alpha2": "US", "numeric": "840", "name": "UNITED STATES OF AMERICA" } } }, "correlation_id": "test-abcd-efgh-ijkl-mnop12345678" } ``` ## Test Ranges Use any BIN, first 6 to 10 digits, that fall within the below min and max bin ranges for testing. The BIN Continuity API in sandbox uses the same test ranges as the [BIN Data API](/bin-data-APIs/bin-data-api-testing#test-ranges). ### Active BINs | BIN Range Min | BIN Range Max | Network | | :- | :- | :- | | `4854270000000000000` | `4854279999999999999` | VISA | | `4238085010000000000` | `4238085139999999999` | VISA | | `4419273340000000000` | `4419279999999999999` | VISA | | `5578061200000000000` | `5578061299999999999` | MASTERCARD | | `5407655500000000000` | `5407655599999999999` | MASTERCARD | | `3113380000000000000` | `3113389999999999999` | AMEX | | `6011392800000000000` | `6011392899999999999` | DISCOVER | ### Deleted BINs Use the following BIN ranges to test historical lookups: | BIN Range Min | BIN Range Max | Network | Status | | :- | :- | :- | :- | | `6503111700000000000` | `6503111799999999999` | DISCOVER | deleted | | `4300693100000000000` | `4300693109999999999` | VISA | deleted | ### Flagged for Delete BINs | BIN Range Min | BIN Range Max | Network | Status | Weeks Remaining | | :- | :- | :- | :- | :- | | `5323922500000000000` | `5323922599999999999` | MASTERCARD | flagged\_for\_delete | 3 | | `3344240000000000000` | `3344249999999999999` | AMEX | flagged\_for\_delete | 1 | # BIN Data API Dictionary Source: https://docs.pagos.ai/bin-data-APIs/bin-data-api-dictionary This guide is a repository of information that you can access using Pagos BIN Data API and use to refine your payments strategy or get to know your customers better. In BIN Data API, there are two types of data fields for which you can receive responses: Standard and Enhanced. * **Standard Data** - [Standard BIN data](#standard-data-fields) is included in every response for Pagos BIN Data API. * **Enhanced Data** - [Enhanced BIN data](#enhanced-data-fields) is available in Pagos BIN Data API when setting the `enhanced` query parameter to `"true"`. **Null/Empty Field Responses:** The data provided in an individual field response depends on what data appears in the files Pagos receives from the card brands. If a field response is `null`, this means our network files don't include any data for that field. Any bool fields marked as "Visa only" will return a `true` or `false` value for Visa BINs; for all non-Visa BINs, they'll return a `null` value. If you're using BIN Data Batch, see the [BIN Data Batch Dictionary](/bin-data-APIs/batch-api-dictionary). ## Standard Data Fields | Data Field | Variable Type | Description | Example Response | | :- | :- | :- | - | | `bank` | object | Issuing bank name and details | see nested values | | `name` | string | Issuing bank name | "Bank of America National Association" | | `phone` | string | Issuing bank phone | "180004321000" | | `url` | string | Issuing bank website | "[https://www.bankofamerica.com](https://www.bankofamerica.com)" | | `bin_min` | string | Minimum PAN value for the BIN range | "4225090000000000000" | | `bin_max` | string | Maximum PAN value for the BIN range | "4225099999999999999" | | `card_brand` | string | The name of the card brand | "Mastercard" | | `card_segment_type` | string | Indicator of consumer BIN or commercial BIN | "consumer" | | `correlation_id` | string | A unique Pagos ID that maps a BIN range to a specific network file; used for troubleshooting | "eyJGaWxlSWQiOjE0NDUsIlZlcnNpb24iOjEwfQ==" | | `country` | object | Issuing country details | see nested values | | `alpha2` | string | 2 letter country code representing the issuing country; Alpha 2 code meets the ISO3166 standards | "US" | | `numeric` | string | Numeric country code representing the issuing country; the numeric country code meets ISO 3166 standards | "840" | | `name` | string | Issuing country name | "United States" | | `number` | object | Details about underlying PAN | see nested values | | `length` | string | The length of the underlying PAN | "16" | | `prepaid` | bool | Indicator of a prepaid BIN | "true" | | `product` | object | Details about the card product | see nested values | | `product_id` | string | The product ID according to the card brand | "MWE" | | `product_name` | string | The product name according to the card brand | "World Elite Mastercard card" | | `type` | string | Indicator of the card type | "Debit" | | `flagged_for_delete_remaining_wks` | string | Countdown in weeks until this BIN range is removed from the file; [learn more](/bin-data-APIs/bin-data-api-overview#bin-ttl-time-to-live) | "4" | ## Enhanced Data Fields | Data Field | Description | Example Response | | :- | :- | :- | | `clean_bank_name` | Pagos-harmonized bank name that has been formatted to proper case, removes unnecessary punctuation and misspellings, and spells out uncommon banking acronyms | "American Federal Credit Union" | | `bank_url` | Issuing bank website | "[https://www.bankofamerica.com](https://www.bankofamerica.com)" | | `bank_phone` | Issuing bank phone number | "180004321000" | | `regulated` | Indicator of the presence of an interchange regulation on a BIN | "true" | | `regulated_name` | The name of the interchange regulation | "GOVERNMENT NON-EXEMPT INTERCHANGE FEE (WITH FRAUD)" | | `reloadable` | Indicator of reloadable or non-reloadable prepaid | "false" | | `pan_or_token` | Indicator if the BIN is a PAN or a Network Token. Note: Mastercard uses the same BIN ranges for both PANs and tokens, meaning all Mastercard BINs can be a PAN and will therefore always return pan in this field—even for those that are actually tokens. Refer to the issuer\_supports\_tokenization field to determine if the BIN supports tokens | "pan" | | `account_updater` | (Visa-only field) Account Updater enabled | "true" | | `alm` | (Visa-only field) Indicator of a BIN or Account Range participating in Account Level Management | "true" | | `domestic_only` | (Visa-only field) Domestic-only BIN or Account Ranges | "true" | | `gambling_blocked` | (Visa-only field) Indicator that this BIN is not permitted to be used for online gambling | "true" | | `level2` | (Visa and Mastercard-only field) Indicator of Level 2 interchange rate eligibility | "true" | | `level3` | (Visa and Mastercard-only field) Indicator of Level 3 interchange rate eligibility | "true" | | `issuer_currency` | The currency that was issued to this BIN to transact in | "usd" | | `combo_card` | Indicator for a card that has combined card type capabilities | "credit and prepaid" | | `bin_length` | 6 or 8 digit BIN | "6" | | `authentication` | If additional customer authentication is required, this json array will indicate the authentication\_name; this field is hardcoded based on issuer country law | "authentication\_name": "EU PSD2 - SCA" | | `cost` | Identifies associated costs by name and amount, embedded as JSON in the column | see example below | | `additional_card_brands` | If the card is associated with a secondary network (e.g. Star, pulse, nyce), this field contains that network's details; note that secondary network's typically provide less in their BIN data. | see example below | | `issuer_supports_tokenization` | Set to true if the card brand data indicates the issuing bank supports network tokenization. Note: The field doesn't indicate if the associated card actually is a PAN or token, just what it supports | "true" | | `pagos_shared_bin` | **Deprecated.** This field has been replaced by `additional_card_brands`; for continuity, it remains in the returned BIN data, but will always be set to `"false"` | "false" | | `billpay_enabled` | BIN has been enabled to make bill payments to service providers electronically, or over the internet | "false" | | `ecom_enabled` | BIN has been enabled to make ecommerce purchases, or purchases over the internet | "true" | | `virtual_card` | Set to true if the given BIN range supports virtual card creation. A null response indicates we do not know if there is support for virtual cards | “true” | | `funding_source` | Indicates the funding source for a payment card, which is different from the type. Note: This field only displays the funding source for Visa and Mastercard; all other brands will show null. | “deferred debit” | | `pagos_bin_length` | Indicates the length of the BIN as determined by Pagos using the bin\_min and bin\_max fields provided by the networks. | "8" | | `multi_account_access_indicator` | Indicates if a Visa card allows for Flexible Credentials functionality. (Note: This field is only available for Visa cards. All other brands will show null.) The possible values for this field are:
  • M - The card is multi-account managed, meaning the issuer manages which account is used and when
  • S - The card is multi-account self-serve, meaning the cardholder manages which account is used and when
  • N - The card is not a participant in multi-account functionality
| "M" | ```json theme={null} { "card": { "number": { "length": 16 }, "bin_length": 6, "pagos_bin_length": 6, "bin_min": "5244780000000000000", "bin_max": "5244789999999999999", "pan_or_token": "pan", "virtual_card": null, "level2": false, "level3": false, "alm": null, "account_updater": null, "domestic_only": false, "gambling_blocked": null, "issuer_currency": null, "reloadable": false, "additional_card_brands": [ { "card_brand": "NYCE", "bin_max": "4422669999999999999", "bin_min": "4422660000000000000", "card_brand_product": "NYCE Generic Product", "card_brand_bank_name": null, "ecom_enabled": true, "billpay_enabled": false } ], "card_brand": "MASTERCARD", "card_segment_type": "Consumer", "combo_card": null, "type": "Credit", "funding_source": "CREDIT", "prepaid": false, "product": { "product_id": "MCW", "product_name": "World Mastercard Card" }, "bank": { "name": "Citadel Federal Credit Union", "phone": null, "url": null, "clean_name": "Citadel Federal Credit Union" }, "country": { "alpha2": "US", "numeric": "840", "name": "UNITED STATES OF AMERICA" }, "authentication": { "authentication_required": false, "authentication_name": null }, "cost": { "interchange": { "regulated": false, "regulated_name": null, "domestic": null, "inter": null, "intra": null, "notes": null } }, "networkfees": {}, "correlation_id": "eyJGaWxlSWQiOjI0OTgxLCJWZXJzaW9uIjoxMjExfQ==", "issuer_supports_tokenization": true, "multi_account_access_indicator": null, "shared_bin": false, "flagged_for_delete_remaining_wks": null } } ``` # BIN Data API Error Handling Source: https://docs.pagos.ai/bin-data-APIs/bin-data-api-error-handling If the BIN Data API fails, you'll receive an error in the format of the following example: ```json theme={null} {"message":[ERROR MESSAGE]} ``` ## API Error Messages Here are the possible values of the **Error Message** text: | Message | Description | | :- | :- | | Too many requests. Please try again later. | The number of API calls has exceeded our [default limits](#bin-data-api-limits). | | Trial for this account has ended. Please contact [support@pagos.ai](mailto:support@pagos.ai). | Your trial period has expired. Contact our Support team for continued access. | | BIN Data Batch API access is not allowed. Please contact [support@pagos.ai](mailto:support@pagos.ai) | Your account has not been enabled for the BIN Data Batch product. Contact our Support team for access. | | This account is suspended. Please contact [support@pagos.ai](mailto:support@pagos.ai) | Your account is suspended. Contact our Support team for more details. | | This API key is invalid. | Our system can't validate the provided API key. This also occurs when a key is sent in the wrong header—a unified API key must be sent as `Authorization: Bearer `. See [API Authentication](/authentication/authentication-overview#authentication). | | API requires an API key in ‘x-api-key’ header. | Your request didn't include a recognized authentication header. Pass your unified API key as `Authorization: Bearer `; see [API Authentication](/authentication/authentication-overview). The legacy `x-api-key` header was [retired on September 1, 2026](/authentication/september-2026-api-migration). | | Card BIN/IIN not found. Please contact [support@pagos.ai](mailto:support@pagos.ai) | We can't find the requested BIN/IIN. This is an indicator that the BIN isn't in our most recent BIN data and is likely no longer in use. Pagos BIN Data is updated weekly. | # BIN Data API Overview Source: https://docs.pagos.ai/bin-data-APIs/bin-data-api-overview The Pagos BIN Data API is a very simple REST API that expects to receive—as input—a 6-10 digit BIN/IIN, and returns a simple JSON object back containing known details for the BIN. If you prefer to query BIN data through your AI tools, check out our guide on the [Pagos MCP Server](/mcp/getting-started-with-pagos-mcp-server) As of **September 1, 2026**, legacy API keys no long work and the legacy `parrot.prod.pagosapi.com` domain was retired. See the [September 2026 API Migration](/authentication/september-2026-api-migration) guide. ## Authentication The Pagos platform uses API keys to authenticate requests to all our services. See our [API Authentication](/authentication/authentication-overview) guide for full instructions on generating API keys and authenticating with the Pagos APIs. ## Look Up a BIN You can use cURL on the command line to submit BIN Data API requests, but you can also use API query tools like Postman or integrate the API direclty into your systems. Here’s a cURL example for details on BIN `55630400` ```bash theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins?bin=55630400' \ --header 'Authorization:Bearer ' ``` This will return the details for the BIN: ```json theme={null} { "card": { "number": { "length": 16 }, "bin_min": "5563040000000000000", "bin_max": "5563049999999999999", "card_brand": "MASTERCARD", "type": "Credit", "prepaid": false, "product": { "product_id": "MCF", "product_name": "Mastercard Corporate Fleet Card" }, "bank": { "name": "CITIBANK N.A." }, "country": { "alpha2": "US", "numeric": "840", "name": "UNITED STATES OF AMERICA" }, "correlation_id": "eyJGaWxlSWQiOjI3NiwiVmVyc2lvbiI6NX0=" } } ``` If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq). ## Enhanced Data With the BIN Data API, you can request enhanced data by including the query paramater `enhanced=true` on you request. This provides you with up to 35 additional fields beyond the standard data fields. It includes additional card brand information, estimated interchange costs, SCA regulation requirements, and more. See the [BIN Data API Dictionary](/bin-data-APIs/bin-data-api-dictionary#enhanced-data-fields) for a detailed list of the enhanced data fields available and an example of how BIN data appears in a query response. For example: ```bash theme={null} curl --request GET \ --url 'https://bin.pagos.ai/bins?bin=55630400&enhanced=true' \ --header 'Authorization:Bearer ' ``` ## Brands Covered At this time, the BIN Data API includes data for the following card brands. * Accel * Amex * ATM Card * Bancontact * Carte Bancaire * Cirrus * Culiance * Dankort * DinaCard * Diners Club * Discover * EBT * EFTPOS Australia * Elo * Hipercard * JCB * Korean Local * Maestro * Mastercard * MIR * NYCE * PayPal * Private Label * Prop * PULSE * RuPay * STAR * UATP * Unionpay * Visa ## Super Ranges The `bin_min` and `bin_max` values returned by the BIN Data API may represent a **super range**. When several adjacent BIN ranges share the exact same data, Pagos collapses them into a single range, using the `bin_min` from the first adjacent range and the `bin_max` from the last. This means a single API response can cover a wider span than a single network-issued BIN range. Super ranges do not affect how you use the API. A BIN lookup will still return the correct data for any BIN within the super range. The `bin_min` and `bin_max` values simply reflect the full extent of the collapsed range. ## Card Product ID and Name When available, we will provide the details around the card product ID and the card product name – this will denote the type of card typically present on the BIN. More details are available in the [BIN / IIN Product Code Guide](/payments-basics/card-brand-services/bin-product-code-guide). ## BIN TTL (Time-To-Live) When a BIN range no longer appears in the card network source files, Pagos doesn't immediately remove that range from the API response. Instead, we provide a grace period using the [`flagged_for_delete_remaining_wks`](/bin-data-APIs/bin-data-api-dictionary) field. For each BIN range, the value in this field will be either: * `Null` - The BIN range is active and not flagged for deletion * An integer `1-4` - The number of weeks until this BIN range is officially removed from the BIN snapshot database The first week our network source files no longer contain a particular BIN range, we'll populate this field with a `4`. Each subsequent week the BIN range remains absent, this value decreases by 1; by the fifth week, we remove the range entirely from the BIN snapshot database. If a network adds back a BIN range previously flagged for deletion, a `null` response replaces the countdown. This feature helps you: * Plan for upcoming BIN removals before they affect your systems * Maintain continuity when network files temporarily omit a BIN range due to errors * Distinguish between permanent BIN removals and temporary network file issues To research BIN history or access data for BIN ranges that have been removed, see the [BIN Continuity API](/bin-data-APIs/bin-continuity-api-overview). ## BIN Data API Limits The following are the API limits for BIN Data API calls: | BIN Data API | API Endpoint | API Limit | | :- | :- | :- | | Single BIN Lookup | [/bins](/bin-data-APIs/endpoint/single) | 100 calls every 10 seconds | | Multiple BIN Lookup (50 BINs per API call) | [/bins/multiple](/bin-data-APIs/endpoint/multiple) | 6 calls every 10 seconds | ## BIN Data API IP Addresses The following static IP addresses can be used to allowlist API traffic to the Pagos BIN Data API: * `13.248.157.210` * `166.117.218.160` ## Testing You can explore the Pagos BIN Data API in sandbox by enabling [Test Mode](/getting-started/managing-your-pagos-account#test-mode) and following the [testing](/bin-data-APIs/bin-data-api-testing) details. # BIN Data API Testing Source: https://docs.pagos.ai/bin-data-APIs/bin-data-api-testing Ensure your integration with the BIN Data API works correctly by making calls to our simulator in Test Mode. ## Step 1: Create a Pagos Account or Sign In If you’re interested in the BIN Data API, you can try it out in [Test Mode](/getting-started/managing-your-pagos-account#test-mode). [Sign up](https://secure.pagos.ai/sign-up) for a Pagos account or log into your existing account, then click the environment toggle in the top-right corner; a yellow bar will appear across the top of the Pagos Service Panel to confirm you're in Test Mode. ## Step 2: Generate Your Test Mode API Keys In Test Mode, generate an API Key for the BIN Data API. These API Keys are universal across Test Mode and will be used for testing all Pagos API products. If you've already created an API key in Test Mode, you don't need to create a new one. To generate your API key: Click your **settings** icon in the top-right corner of your Pagos Service Panel. Under **Developers**, click **API Keys**. In the **API Keys** tab, click **Create API Key** to add a new key to your account. In the side panel that opens, set your **Key Name**, then click **Create API Key**. Copy your new API Key and store it somewhere secure. This is the only time you can view this key! Click **I've Copied My Keys** to confirm and exit the side panel. ## Step 3: Test Looking up a BIN Use our [test ranges](#test-ranges) to test looking up a BIN in Test Mode. Note that the endpoint for Test Mode points to **sandbox**. ```bash theme={null} curl --request GET \ --url 'https://bin.sandbox.pagos.ai/bins?enhanced=true&bin=485427' \ --header 'Authorization:Bearer ' ``` This will return the mock details for the BIN: ```json theme={null} { "card": { "number": { "length": 16 }, "bin_length": 6, "pagos_bin_length": 6, "bin_min": "4854270000000000000", "bin_max": "4854279999999999999", "pan_or_token": "pan", "virtual_card": null, "level2": false, "level3": false, "alm": false, "account_updater": true, "domestic_only": false, "gambling_blocked": false, "issuer_currency": "USD", "reloadable": false, "additional_card_brands": [ { "card_brand": "PULSE", "bin_max": "4854279999999999999", "bin_min": "4854270000000000000", "card_brand_product": null, "card_brand_bank_name": null, "ecom_enabled": true, "billpay_enabled": true } ], "card_brand": "VISA", "card_segment_type": "Business", "combo_card": null, "type": "Debit", "funding_source": "DEBIT", "prepaid": false, "product": { "product_id": "G", "product_name": "Visa Business" }, "bank": { "name": "SPACE COAST CREDIT UNION", "phone": null, "url": null, "clean_name": "Space Coast Credit Union" }, "country": { "alpha2": "US", "numeric": "840", "name": "UNITED STATES OF AMERICA" }, "authentication": { "authentication_required": false, "authentication_name": null }, "cost": { "interchange": { "regulated": false, "regulated_name": "GOVERNMENT EXEMPT INTERCHANGE FEE", "domestic": null, "inter": null, "intra": null, "notes": null } }, "networkfees": {}, "correlation_id": "eyJGaWxlSWQiOjIzMDc5LCJWZXJzaW9uIjoyNDAyfQ==", "issuer_supports_tokenization": null, "multi_account_access_indicator": "N", "shared_bin": false } } ``` ## Test Ranges Use any BIN, first 6 to 10 digits, that fall within the below min and max bin ranges by network for testing. | BIN Range Min | BIN Range Max | Network | | :- | :- | :- | | `4854270000000000000` | `4854279999999999999` | VISA | | `4238085010000000000` | `4238085139999999999` | VISA | | `4419273340000000000` | `4419279999999999999` | VISA | | `4756410010000000000` | `4756410019999999999` | VISA | | `4821245300000000000` | `4821245409999999999` | VISA | | `4300693100000000000` | `4300693109999999999` | VISA | | `6703760000000000000` | `6703769999999999999` | MASTERCARD | | `5578061200000000000` | `5578061299999999999` | MASTERCARD | | `5407655500000000000` | `5407655599999999999` | MASTERCARD | | `5323922500000000000` | `5323922599999999999` | MASTERCARD | | `5262597100000000000` | `5262597199999999999` | MASTERCARD | | `5154875000000000000` | `5154875099999999999` | MASTERCARD | | `3113380000000000000` | `3113389999999999999` | AMEX | | `3339600000000000000` | `3339599999999999999` | AMEX | | `3344240000000000000` | `3344249999999999999` | AMEX | | `3547600000000000000` | `3547609999999999999` | AMEX | | `3761510000000000000` | `3761519999999999999` | AMEX | | `3763920000000000000` | `3763929999999999999` | AMEX | | `6011392800000000000` | `6011392899999999999` | DISCOVER | | `6503011700000000000` | `6503011799999999999` | DISCOVER | | `6509150000000000000` | `6509159999999999999` | DISCOVER | | `6516492200000000000` | `6516492299999999999` | DISCOVER | | `6557220000000000000` | `6557229999999999999` | DISCOVER | | `6559330000000000000` | `6559339999999999999` | DISCOVER | # BIN Continuity Lookup Source: https://docs.pagos.ai/bin-data-APIs/endpoint/continuity GET /bins/continuity # Get Snapshot File of All BINs Source: https://docs.pagos.ai/bin-data-APIs/endpoint/file-snapshot GET /batch/files # Multiple BIN Lookups Source: https://docs.pagos.ai/bin-data-APIs/endpoint/multiple POST /bins/multiple # Single BIN Lookup Source: https://docs.pagos.ai/bin-data-APIs/endpoint/single GET /bins # Pagos BIN Data Tools Source: https://docs.pagos.ai/bin-data-APIs/pagos-bin-data-tools Pagos provides multiple APIs for accessing our BIN data tools: Submit a BIN to our simple REST API and receive a JSON object back containing known details for that BIN! All Pagos BIN Database subscribers can access the BIN Data API. Use this file-based product to bulk retrieve BIN bank and market details via a file you add to your local database. To access the BIN Data Batch API, you must subscribe to the Batch BIN File add-on. Research the full history of a specific BIN, including when they were first seen in the network source files, last seen, and their current status. Retrieve benchmark metrics for individual BINs (e.g. approval rate), calculated from the billions of transaction data points Pagos has ingested from merchants in our networks. BIN Data API users can also query BIN data through AI agents using the [Pagos MCP Server](/mcp/getting-started-with-pagos-mcp-server). # BIN Data: Card Networks and Issuers FAQ Source: https://docs.pagos.ai/bin-database/card-network-faq ## What card brands does Pagos provide BIN data for? At this time, the BIN Data API includes data for the following card brands. * Accel * Amex * ATM Card * Bancontact * Carte Bancaire * Cirrus * Culiance * Dankort * DinaCard * Diners Club * Discover * EBT * EFTPOS Australia * Elo * Hipercard * JCB * Korean Local * Maestro * Mastercard * MIR * NYCE * PayPal * Private Label * Prop * PULSE * RuPay * STAR * UATP * Unionpay * Visa ## Why do I see Visa ranges starting with 5 or Mastercard ranges starting with 4? While traditional wisdom says Visa BINs starts with `4` and Mastercard BINs with `5`, networks can have overlapping ranges or special arrangements. Because Pagos gets BIN data from the card networks directly, the ranges in our database represent the legitimate assignments from the networks themselves. ## How does Pagos handle leading zeros in BINs? Pagos created the `bin_min_exact` and `bin_max_exact` fields to store original BINs from network files. Our search algorithm checks the first two digits of the actual range against the input. For example, with input `044855`, we'll match against ranges that start with leading zeros in the actual range field. ## What does the `card_brand_is_additional` field mean? `card_brand_is_additional` will be set to false if the BIN range is associated with a primary card network, and true if associated with a secondary network (e.g., Star, Pulse, Nyce). Secondary networks typically provide less data. If multiple networks share a BIN range and all have `card_brand_is_additional` set to false, the primary network will be Visa, Mastercard, Discover, or Amex. ## Does Pagos support Apple Pay DPAN and Google Pay DPAN lookups? Yes. A device PAN (DPAN) is essentially a tokenized PAN specific to Apple Pay. You can query the first 8 digits of the DPAN and receive information regarding the issuer of the underlying card. **Keep in mind:** * Pagos won't return the actual PAN when you query for the DPAN * The DPAN and the underlying PAN typically don't share the same first 8 digits (BIN) ## Does Pagos support gift card networks like Blackhawk and Givex? Not at this time. Gift card network support is on the roadmap. ## What percentage of issuers does the Pagos BIN Database cover? Our coverage comes directly from the network files provided by Visa, Mastercard, Discover, Amex, and other supported networks. We cover all issuers those networks report on. ## Does Pagos support Interac? Interac is not currently available. ## How does Pagos handle US Pinless Debit, Bancontact, and Dankort routing? Pagos will share the networks available on a given account range, but won't make routing recommendations. For cards known to be dual-branded in any market, we'll return all the enabled networks and flag those that are considered additional. # BIN Data: Card Types and Flags FAQ Source: https://docs.pagos.ai/bin-database/card-type-flags-faq ## Why might the product information differ from what's returned by my acquirer or processor? In the US and some other markets, card networks offer account-level management, which allows issuers to upgrade a basic card to a more premium card. Card networks don't track these upgrades, as they are preformed at the issuer-level. When this happens, the PAN-specific product code will differ from the BIN-level product designation. For example, a BIN range might be designated for `Visa Classic` cards, but individual accounts within that range can be upgraded to higher-tier products like `Visa Signature` or `Visa Infinite`. Pagos only receives information for what is tracked at the network-level today. ## Is there a flag to identify cards enabled with BNPL (Buy Now Pay Later)? There is not a BNPL flag in the BIN file, as BNPL is not enabled on a card at the BIN level. ## How do I identify corporate and small business cards? Compare the `product_name` field with the [product code guide](/payments-basics/card-brand-services/bin-product-code-guide) to identify corporate and business card products. ## How are prepaid and reloadable flags determined? When the network provides data about a card's prepaid capabilities, we set the `prepaid` field to `TRUE` or `FALSE` accordingly. If the network doesn't provide this data, we set the field to `NULL`. The specific logic differs by each card network: * **Amex** - Maps based on the Amex product code according to internal mapping tables * **Discover** - Maps based on product codes in internal mapping tables * **Mastercard** - The `reloadable` field will be set to `TRUE` if `fundingSource = PREPAID` and `nonReloadableIndicator = FALSE`; the `prepaid` field will be `TRUE` if `fundingSource = PREPAID` * **Visa** - The `reloadable` field will be set to `TRUE` if `AccountFundingSourceSubtypeCd = R`; `prepaid` will be `TRUE` if `AccountFundingSourceCd = P` ## Can a card be both `type = CREDIT` and `funding_source = DEBIT` (or vice versa)? Yes, this is possible. The `funding_source` indicates the mechanism behind how funds or credit is replenished, while `card type` is the top-level classification. For example, a Corporate debit card could have a short-term line of credit attached (`funding_source = CREDIT`), or a credit card could be funded from a bank account balance (`funding_source = DEBIT`). Similarly, a card can be `type = CREDIT` and have a `product` name that indicates a debit card. Some card networks issue cards marked as debit, but with a funding source that's actually credit. This is typical of corporate or professional cards (e.g. Debit Mastercard BusinessCard and Debit Mastercard Professional Card). ## What does the `regulated` flag indicate? The `regulated` flag depends on network-specific logic and is only populated for Visa and Mastercard in the US. For Visa, it comes directly from the network source. For Mastercard, Pagos uses the Federal Reserve data on small issuer exemption logic that matches bank names and applies the flag to US debit/prepaid products with specific criteria. # BIN Data Integration FAQ Source: https://docs.pagos.ai/bin-database/data-integration-faq ## What are the API latency expectations? Our average latency for a full round trip of BIN Data API calls from the east coast of the United States is between **150 and 250ms**. You may see additional latency based on where your systems are physically located in relation to the east coast of the United States. We recommend keeping API calls below 20 TPS to avoid hitting rate limits. # BIN Data General FAQ Source: https://docs.pagos.ai/bin-database/general-faq ## When is the BIN file ready each week? We officially update the BIN data at 00:00 UTC every Tuesday. That being said, we recommend waiting 12 hours (approximately 12:00 UTC) to account for potential network delays. Typically, issues are resolved within 6 hours, but waiting +12 hours ensures you have the most up-to-date information. ## How often do BIN database entries change? BIN data changes regularly as the card networks update their BIN ranges, add new products, and modify existing ranges. Pagos updates our files weekly to account for these regular updates. ## Why are Pagos' responses different from my current BIN list provider's responses? We receive BIN data directly from the card brands. As such, our response data is accurate and up to date according to the latest card brand records. Because other BIN providers may receive their data from third-party sources outside of the card brands, we can't speak to the accuracy of their responses. ## Why doesn't my 6-digit BIN return any information? Most card networks have moved from six-digit to eight-digit BIN ranges. When you query with a shorter BIN, we pad the value with zeros to build the 19-digit number we use to compare against bin\_min and bin\_max. For example, if you search for the 6-digit BIN `413555`, we pad it to `4135550000000000000`. In this case, the real BIN for the card in question is eight digits (`41355506`) and exists in the Pagos BIN database in the following range: * `bin_min` - `4135550600000000000` * `bin_max` - `4135550699999999999` As such, the six-digit BIN (plus padding) falls outside the actual BIN range and won't return a match in the Pagos BIN Database. To get the most accurate result, always query with as many digits as you have available — ideally the full 8-digit BIN. ## What does a Null field response mean? The data provided in an individual field response depends on what data appears in the files we receive from the card brands. If a field response is null, this means our card brand files don’t include any data for that field. ## What is the difference between the `bin_length` and `pagos_bin_length` fields? The `bin_length` field is populated directly from the network when the data is available. `pagos_bin_length` is a Pagos-specific field. We populate this field for all cards using our own logic, taking into consideration the bin\_min and bin\_max ranges and calculating the actual bin length for the range from those values. `pagos_bin_length` is very helpful in determining whether more collecting digits would benefit your business. There are use cases (e.g. US pinless debit routing or network tokenization) where the networks have meaningful differences between issuers and supported features that vary at the 9th or 10th digit. ## What does the `shared_bin` indicator mean? This field is set to true when there is more than 1 unique range available for a 6+ digit BIN query. This indicates you need to pass more BIN digits to get a more unique response. For example, if you have ranges 4444000-4555000 and 4444400-4444500, the `shared_bin` field will be set to true. ## Why do some BIN ranges show the same `bin_min` and `bin_max` values? This can happen when networks provide overlapping ranges or when there are multiple network associations for the same BIN range. The responses in other fields, such as `card_brand` and `product_name` will be different. To create a unique identifier, you should concatenate the `bin_min`, `bin_max`, and `network` fields together. You can also use the `card_brand_is_additional` field to identify primary vs. secondary networks. You should see one primary (false) and one or more additional (true) networks. In our API response, we provide a helpful ranking based on our logic, which places the big global networks (Visa, MasterCard, Amex, Discover, JCB, Unionpay) as primary and other network enablements as additional. In the [BIN batch](/bin-data-APIs/endpoint/file-snapshot) file, this preference is left in order to support as many use cases as possible. ## What does it mean when multiple ranges show the same `bin_min` and `bin_max` values AND don’t have the `card_brand_additional_network` flag set to true? When cards are co-branded, they often have payment marks and each network will claim the range as an issuer product. In cases where networks have co-processing agreements, networks will add a network’s ranges to its table to allow those cards to be routed. Networks like American Express, Discover, UnionPay, and JCB enter into agreements not to co-brand or co-badge a card, but to co-process in mutual agreements that are not usually indicated in the BIN file. The priority of the overlapping records when `additional_network` is false is left to your use case. ## How do I handle overlapping BIN ranges? It's possible for a BIN to appear in two overlapping BIN ranges between two different networks. This typically indicates one of the following: * The provided BIN is too wide of a range and more digits are required to narrow the results (e.g. the six-digit BIN is in two BIN ranges, but the eight-digit BIN is only in one) * The given BIN has both a primary and secondary card brand associated with it. The primary card brand for the BIN will be one of the main card brands—Visa, Mastercard, Amex, and Discover; the secondary is typically a pinless debit network or a regional brand (e.g. ETPOS, Dankort, Carte Bancaire). If a BIN appears in two overlapping ranges—where one range is smaller and fully contained within a larger one—use the details from the more specific (smaller) range.
Larger Range (overlapping): 6229330000000000000 - 6237969999999999999, UNIONPAY, CN Smaller Range (single): 6233550000000000000 - 6233559999999999999, UNIONPAY, TH
## What does the `funding_source` field contain? This enhanced field is currently available only for Visa and Mastercard. For Visa, it maps one-digit codes to full descriptions (C=Credit, D=Debit, H=Charge Card, P=Prepaid, R=Deferred Debit). For Mastercard, it uses the top-level funding source from their BIN file (DEBIT, CREDIT, PREPAID, NONE). # Getting Started with the Pagos BIN Database Source: https://docs.pagos.ai/bin-database/getting-started-with-bin-database This content is designed for subscribers to the Pagos BIN Database only. If you've subscribed to multiple Pagos services, head over to our [Getting Started with Pagos](/getting-started/getting-started-with-pagos) guide. With the Pagos BIN Database, you can request detailed bank and market data for the payment cards your customers transact with. Submit a 6-10 digit bank identification number (BIN)—also known as an Issuer Identification number (IIN)—for a customer's card and receive information about the card type and brand, the bank that issued it, and details of the market it was issued in, such as currency, country, and time zone. BIN data can help you better understand both your customers and their preferred payment cards. With this added context, you can design and implement a payments strategy that benefits your bottom line and improves the checkout experience for your customers! ## Request BIN Data From the Pagos APIs Pagos provides multiple APIs for accessing our BIN data tools: Submit a BIN to our simple REST API and receive a JSON object back containing known details for that BIN! All Pagos BIN Database subscribers can access the BIN Data API. Use this file-based product to bulk retrieve BIN bank and market details via a file you add to your local database. To access the BIN Data Batch API, you must subscribe to the Batch BIN File add-on. Research the full history of a specific BIN, including when they were first seen in the network source files, last seen, and their current status. Retrieve benchmark metrics for individual BINs (e.g. approval rate), calculated from the billions of transaction data points Pagos has ingested from merchants in our networks. BIN Data API users can also query BIN data through AI agents using the [Pagos MCP Server](/mcp/getting-started-with-pagos-mcp-server). ## Perform BIN Lookups Via the UI A BIN search in Pagos. Enter a 6-10 digit BIN, then click **Lookup** to query the [BIN Data API](/bin-data-APIs/bin-data-api-overview) directly from the Pagos Service Panel. The page will populate all available standard and enhanced data fields for that BIN in plain text. For a full list of the available data fields and their descriptions, see our [BIN Data API Dictionary](/bin-data-APIs/bin-data-api-dictionary). Click a sample BIN to test out the lookup functionality quickly. If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq). ### Lookup with Benchmark If your business opted in for data sharing with Pagos, you'll have a second option available: **Lookup with Benchmark**. Click this button to perform a lookup that includes benchmark metrics for the given BIN, pulled from the billions of transaction data points we’ve ingested from our merchants. Use this data to see how your performance on a given BIN compares to that of the Pagos network. At this time, the available benchmark metrics include: * Approval rate for customer-initiated transactions (CITs) * Approval rate for merchant-initiated transactions (MITs) **Important Notes:** * You'll be charged for each BIN lookup that successfully returns benchmark data. * We may not have enough data for a given BIN to provide benchmark metrics. If we can't provide benchmark data for the submitted BIN, you'll receive lookup data only and will not face the additional benchmark charge. ## Review Your BIN API Metrics To monitor and manage your usage of the BIN Data API, navigate to the **BIN** section of the Pagos Service Panel, then click the **BIN API** tab. This tab contains the following visuals: * **Requests** - The number of API requests you've made for Standard vs. Enhanced BIN data over the selected date range * **Response Time** - The response times for API requests made to for Standard vs. Enhanced BIN data over the selected date range By default, these graphs contain data from the last seven days; to view historical data, use the **Date Range** filter. ## Download the BIN Data Batch File To download a batch file of the most up-to-date BIN data pulled directly from the card networks, navigate to the **BIN** section of the Pagos Service Panel, then click the **Batch** tab. * Click **Standard BIN Batch File** to download a file of the [standard BIN data fields](/bin-data-APIs/batch-api-dictionary#standard-data-fields). * Click **Enhanced BIN Batch File** to download a file of the [enhanced BIN data fields](/bin-data-APIs/batch-api-dictionary#enhanced-data-fields) Only subscribers to [Batch BIN File add-on](https://pagos.ai/pricing) can download files from the **Batch** tab. If you prefer to use the BIN Data Batch API to request these files, see the [BIN Data Batch API Overview](/bin-data-APIs/batch-api-overview) guide. # BIN Data: Network Token Support FAQ Source: https://docs.pagos.ai/bin-database/network-tokens-faq ## What does `issuer_supports_tokenization` mean? This field indicates whether the issuer supports tokenization services. The only networks to support it at this time are Visa and Mastercard, and the value can either be true or null; it will always be null for other networks. For Mastercard, we pull the information from quarterly MDES files containing `bin_min`/`bin_max` ranges. For Visa, we receive this information in their standard file. **Note**: MasterCard mixes network token issuance in the same range as PANs, while Visa does not. ## Do Mastercard and Visa network token ranges overlap with PAN ranges? For Visa, the account ranges are separate. For Mastercard, they are normally separate but could overlap according to Mastercard's specifications. For token ranges, we recommend 8-digit BIN searches, as both networks use the 8-digit space to issue token ranges. ## What is the `multi_account_access_indicator` field? This Visa-specific field indicates whether a card can access multiple underlying funding accounts using a single primary PAN. Values are: * `M` - Multi-account managed by issuer * `S` - Multi-account self-serve by cardholder * `N` - Not a participant (single account) For all other networks, this field is set to null. # Pairing BIN Data with Other Pagos Services Source: https://docs.pagos.ai/bin-database/pairing-bin-data The Pagos BIN Database is a powerful tool that provides detailed bank and market data for the payment cards your customers transact with. To augment your payments optimization strategy, we recommend pairing the information available through our BIN Database with other card network services like the Account Updater API and Network Tokenization API. ## Creating Rules around Tokenization and Account Updates The Pagos [Network Tokenization API](/network-tokenization/overview) offers quick and easy access to global network tokens from all four major card brands with a single integration, while our [Account Updater tools](/account-updater/pagos-account-updater-tools) are account lifecycle management services for keeping card-on-file account information up-to-date for all major card brands. The Pagos BIN Database provides BIN attributes to help you better understand your customers’ PANs; with this information, you can make better decisions around how to process and store those cards. If you’re using Network Tokenization or Account Updater, you can also use that data to create and manage rules around how, when, or if certain PANs should be sent for tokenization or account updates. Here are just a few examples of the BIN data attributes you can integrate into your network tokenization and account updater strategies to make them more efficient or optimize for cost savings: * **Card Type** – When you know the type of cards your customers transact with, you can build rules around which cards you tokenize or update. If your historical processing data shows that non-reloadable prepaid cards have low approval rates or aren’t typically used for repeat purchases, you could sort out this card type from the PANs you send for tokenization. Similarly, non-reloadable prepaid cards aren’t eligible for updates through Pagos Account Updater; when you know which cards aren’t eligible for account updater, you can avoid even attempting such updates and the costs associated with the attempt. * **Issuing Country** – Certain regions have a higher issuer adoption rate for network tokenization and account updater than others. When you know what country a card is issued in, you can make decisions on a card-by-card basis as to which ones you want to tokenize or request updates on. Doing so ensures you only tokenize those cards for which you have the highest likelihood of success. * **Token Ranges** – Some card brands identify a BIN range as being a token range instead of a PAN range with a pan\_or\_token identifier. With this information, you can proactively exclude token ranges from those sent off for tokenization, since there’s no reason to tokenize a payment method that’s already a token. * **BIN Ranges** – Card brands identify the BIN ranges that aren’t eligible for account updater. You can then exclude any cards in these minimum/maximum ranges from your update requests. ## Collecting Better Data As mentioned in the section above, BIN Data's main value-add is in helping you get to know your customer base better. When you can assign data attributes to individual BINs, you can then use those attributes to sort, analyze, and spot trends in your customer and transaction data. The same is true of your network token and account updater data! With the Pagos BIN Database, you can use eight+ digit BINs to start identifying the attributes of different BIN ranges associated with successful network tokenization or account update attempts, and adapt your processes accordingly. This analytic capability is especially important in the long run, as issuer adoption of network tokenization and account updater evolves. When you know what issuing banks or issuing countries have changed their stance on these services, for example, you can immediately adapt your network tokenization and account updater strategies to leverage the right service at the right time to optimize payment performance. # Account Updater Source: https://docs.pagos.ai/card-brand-apis/account-updater Monitor and manage the Account Updater API (batch and real-time). Pagos Account Updater UI All [Pagos Account Updater](https://pagos.ai/product/account-updater) subscribers can access the **Account Updater** section of the Pagos Service Panel. Card brands like Visa and Mastercard provide issuing banks with secure communication networks to assist them in distributing updated card information to merchants or payment service providers (PSPs) who vault card credentials. By leveraging these networks, your business can decrease customer checkout friction and churn, and increase overall transaction approval rates by keeping customer card information updated. Pagos has two account updater tools: Request updated card details in batches to keep your vault up to date. Update card details in real time during checkout to boost approval rates. To access the Account Updater section, click **Account Updater** under **Card Brand APIs** in the main navigation. This section contains the following tabs: * [Batch](#batch) * [Real-Time](#real-time) * [Webhooks](#webhooks) * [Card Brand](#card-brand) If you operate a platform providing account updater services to select merchants, you'll also have a [Merchants](#merchants) tab. ## Batch The **Batch** tab provides a breakdown of the batches of card credentials you've sent to Pagos for account updates via the [Batch Account Updater API](/account-updater/batch-api-overview). To navigate this tab: Use the **Date Range** filter in the top-right corner of the page to select the time period you want to view data for. If you operate a platform, use the **Platform Merchant** drop-down to select the merchant for whom you want to view batch account updater data. The cards across the top of the page provide the following stats: * **Cards Updated** - The number of card credentials sent in batches to Pagos for credential updates * **Batches Completed** - The number of batches you've received credential updates for * **Response Success Rate** - The percentage of credentials included in your batches that received [non-error response code](/account-updater/batch-update-codes#response-codes) from the networks Each row in the table represents a batch of card credentials sent for updates in the set time period, including the update status, number of credentials included in the batch, success rate of the entire batch, and card brand contacted for updates. Click **Add Filter** to filter the table for only those batches with a specific status. Click on a batch to open a side panel with additional details including the **Batch ID** and any [response codes](/account-updater/batch-update-codes#response-codes) or [error codes](/account-updater/batch-update-codes#error-codes) returned from the network. ## Real-Time The **Real-Time** tab provides more information about the [Real-Time Account Updater API](/account-updater/real-time-api-overview) calls you've made to update individual credentials in real time, including: * **API Calls** - The number of API calls you've made to the Real-Time Account Updater API * **API Response** - The number of credentials that received [non-error response codes](/account-updater/batch-update-codes#response-codes) from the networks in real time * **Response Success Rate** - The percentage of credentials that received [non-error response codes](/account-updater/batch-update-codes#response-codes) from the networks in real time Use the **Date Range** filter in the top-right corner of the page to select the time period you want to view data for. If you operate a platform providing account updater services to a variety of merchants, use the **Platform Merchant** drop-down to select the merchant for whom you want to view batch account updater data. ## Webhooks From the **Webhooks** tab, you can add and edit [webhooks](/account-updater/batch-webhooks) for Batch Account Updater job status changes. To do so: In the Account Updater Webhook Endpoint box, click **Edit**. Paste your endpoint URL in the text box. Add your own secret key. Save this for [validating webhooks](/account-updater/batch-webhooks#validating-webhooks) in the future. Click **Save Webhook Endpoint**. The **Event Delivery Attempts** table lists the events that triggered your webhook in the set time period. Each row includes the event type, job ID associated with the batch, reason, and date created. Click **Add Filter** to filter the table for only those events with a specific status. ## Card Brand From the **Card Brand** tab, you can view the card brands you're configured to receive credential updates from (American Express, Discover, Visa, and Mastercard). To enable or deactivate any card brands, contact your Pagos Account Manager. ## Merchants This tab only appears for platform merchants. The **Merchants** tab includes a table listing the merchants operating within your platform. Each row contains the merchant name, primary contact, and creation date. Here, you'll also find each merchant's **Merchant ID**, used to identify individual merchants in the API headers of calls to [Batch Account Updater](/account-updater/batch-api-headers#merchant-identification) or [Real-Time Account Updater](/account-updater/real-time-api-headers#merchant-identification). # BIN Source: https://docs.pagos.ai/card-brand-apis/bin Perform BIN lookups, review data for requests made to the BIN Data API, or download the latest BIN Data Batch file. A BIN search in Pagos. All [Pagos BIN Database](https://pagos.ai/product/bin-data) subscribers can access the **BIN** section of the Pagos Service Panel To access the BIN section, click **BIN** in the main navigation. This section contains the following tabs: * [Lookup](#lookup) * [BIN API](#bin-api) * [Batch](#batch) ## Lookup Enter a 6-10 digit BIN, then click **Lookup** to query the [BIN Data API](/bin-data-APIs/bin-data-api-overview) directly from the Pagos Service Panel. The page will populate all available standard and enhanced data fields for that BIN in plain text. For a full list of the available data fields and their descriptions, see our [BIN Data API Dictionary](/bin-data-APIs/bin-data-api-dictionary). Click a sample BIN to test out the lookup functionality quickly. If you have questions about the data returned for any given BIN, check out our [BIN Data FAQ pages](/bin-database/general-faq). ### Lookup with Benchmark If your business opted in for data sharing with Pagos, you'll have a second option available: **Lookup with Benchmark**. Click this button to perform a lookup that includes benchmark metrics for the given BIN, pulled from the billions of transaction data points we’ve ingested from our merchants. Use this data to see how your performance on a given BIN compares to that of the Pagos network. At this time, the available benchmark metrics include: * Approval rate for customer-initiated transactions (CITs) * Approval rate for merchant-initiated transactions (MITs) **Important Notes:** * You'll be charged for each BIN lookup that successfully returns benchmark data. * We may not have enough data for a given BIN to provide benchmark metrics. If we can't provide benchmark data for the submitted BIN, you'll receive lookup data only and will not face the additional benchmark charge. ## BIN API From the **BIN API** tab, you can monitor and manage your usage of the BIN Data API. This tab contains the following visuals: * **Requests** - The number of API requests you've made for Standard vs. Enhanced BIN data over the selected date range * **Response Time** - The response times for API requests made to for Standard vs. Enhanced BIN data over the selected date range By default, these graphs contain data from the last seven days; to view historical data, use the **Date Range** filter. ## Batch From the **Batch** tab, you can download batch files of the most up-to-date BIN data directly from the card networks: * Click **Standard BIN Batch File** to download a file of the [standard BIN data fields](/bin-data-APIs/batch-api-dictionary#standard-data-fields). * Click **Enhanced BIN Batch File** to download a file of the [enhanced BIN data fields](/bin-data-APIs/batch-api-dictionary#enhanced-data-fields) Only subscribers to [Batch BIN File add-on](https://pagos.ai/pricing) can download files from the **Batch** tab. If you prefer to use the BIN Data Batch API to request these files, see the [BIN Data Batch API Overview](/bin-data-APIs/batch-api-overview) guide. # Network Tokens Source: https://docs.pagos.ai/card-brand-apis/network-tokens Monitor and manage the Network Tokenization API. Pagos Network Tokens UI All [Pagos Network Tokenization](https://pagos.ai/product/network-tokens) subscribers can access the **Network Tokens** section of the Pagos Service Panel [Network tokenization](/payments-basics/card-brand-services/network-tokenization) is a system through which card brands (e.g. Visa, Mastercard, Discover, and Amex Direct) substitute payment card primary account numbers (PANs) and other card details in payment tokens that they share with merchants. Because these tokens are provided by the network, it provides a streamlined way to securely move payment information through the transaction lifecycle. With the Pagos [Network Tokenization API](/network-tokenization/overview), your business can seamlessly execute a network tokenization strategy without changing anything about your current payment stack. One simple integration allows you to quickly tokenize all the cards in your vault, regardless of network, thereby increasing your transaction approval rate, decreasing fraud risk, and improving customer experiences. You can monitor and manage your usage of the Network Tokenization API in the Network Tokens section of the Pagos Service Panel. To do so, click **Network Tokens** under **Card Brand APIs** in the main navigation. This section contains the following tabs: * [Tokens](#tokens) * [Webhooks](#webhooks) * [Card Brand](#card-brands) If you operate a platform providing network tokenization services to select merchants, you'll also have a [Merchants](#merchants) tab. ## Tokens The **Tokens** tab provides a breakdown of the individual PANs you've sent to Pagos for tokenization via the [Network Tokenization API](/network-tokenization/overview). To navigate this tab: Use the **Date Range** filter in the top-right corner of the page to select the time period you want to view data for. If you operate a platform providing network tokenization services to a variety of merchants, use the **Platform Merchant** drop-down to select the merchant for whom you want to view token data. The cards across the top of the page provide the following stats: * **Tokens Provisioned** - The number of network tokens provisioned from primary account numbers * **API Requests** - The number of requests sent to the Network Tokenization API Each row in the table represents a token provisioned via the Network Tokenization API in the set time period, including the token status, token data (BIN, last four digits, expiration date), underlying card data (BIN and card brand), and the date when the token was provisioned. Click **Add Filter** to filter the table for only those tokens with a specific status. Click on a token to open a side panel with more details about the token and underlying PAN, including [card art details](/network-tokenization/overview#requesting-card-art) when available. ## Webhooks From the **Webhooks** tab, you can add and edit [webhooks](/network-tokenization/overview#set-up-webhooks) for token status changes and lifecycle management updates. To do so: In the Network Tokenization Webhook Endpoint box, click **Edit**. Paste your endpoint URL in the text box. Add your own secret key. Save this for [validating webhooks](/network-tokenization/webhooks#validating-webhooks) in the future. Click **Save Webhook Endpoint**. ## Card Brand From the **Card Brand** tab, you can view the card brands you're configured to provision network tokens from (American Express, Discover, Visa, and Mastercard). To enable or deactivate any card brands, contact your Pagos Account Manager. ## Merchants This tab only appears for platform merchants. The **Merchants** tab includes a table listing the merchants operating within your platform. Each row contains the merchant name, primary contact, and creation date. Here, you'll also find each merchant's **Merchant ID**, used to identify individual merchants in the [API headers](/network-tokenization/headers) of calls to the Network Tokenization API. # Changelog Source: https://docs.pagos.ai/changelog Latest updates and improvements to the Pagos products ## Data Filters We've updated the [**Date Range** Filter](/insights/insights-data-filters#date-range) in Pagos Insights. When you click the filter, you can choose from the available options (e.g. Last 7 days, Last 4 weeks, etc.) or select the following: * **Custom date until now** - Select a start date to view data between that date and today * **Custom dates** - Select a start and end date for your data Use the **Group by** dropdown to choose what time period we group your data by: hour, day, week, month, quarter, year ## BIN Insights In the **Chargebacks** tab of the [**BIN Insights**](/insights/bin-insights#chargebacks) page, we've added a column for **Chargeback Rate**. At this time, the table isn't sortable by this column, and the exported data from this page won't include chargeback rate data. ## Alerts The data segments listed in the [**Alerting Segments**](/insights/alerts/alerts-overview#alerting-segments) and [**Monitored Segments**](/insights/alerts/alerts-overview#monitored-segments) sections of an Alerts Details Page now include a **Segment Size** value, identifying how big the impacted segment is. ## Retry Performance The graph on the [Retry Performance](/insights/retry-performance#retry-graph) page can now be one of two data visualizations. Use the **Include Initial Attempt** toggle to determine which one appears: * **Retry Success Rate Contribution by Attempt** - The percentage of [Transactions Retried](/insights/retry-performance#retry-statistics) recovered with each retry attempt; appears when the toggle is in the **off** position * **Approval Rate Contribution by Attempt** - The percentage of total [Unique Transactions](insights/retry-performance#retry-statistics) approved with each attempt in the selected time period, starting with the initial transaction; appears when the toggle is in the **off** position Select which visual you want to view using . ## Charts * The creator of a custom chart in the [Charts](/insights/charts) section of Pagos Insights can now [**lock**](/insights/charts#lock-your-chart) that chart to prevent other users from making any changes to the visualization's settings or filters. * If you've built out [custom dimensions](/getting-started/managing-your-pagos-organization#adding-custom-dimensions) in your Pagos Organiztion, you can now filter custom [charts](/insights/charts) by a custom dimension parameter. ## BIN Lookups When performing BIN lookups in the Pagos Service Panel, you now have the option to perform a [**Lookup with Benchmark**](/card-brand-apis/bin#lookup-with-benchmark). Alongside standard and enhanced BIN data, your lookup will include benchmarked approval rates (CIT and MIT) for the given BIN, calculated using the billions of transaction data points we’ve ingested from our merchants. Keep in mind, each lookup that successfully returns benchmark data carries an additional charge. ## Retry Performance We've added a toggle to the **Approval Rate Contribution by Attempt** guide: [**Expand All Attempts**](/insights/retry-performance#expand-all-attempts). Click this toggle to change the graph from aggregating all attempts past 4 into a single bar (**Retry 4+**). ## Filters You can now filter your chargeback data in Pagos Insights by [Chargeback Size](/insights/insights-data-filters#chargeback-size) and original [Transaction Size](/insights/insights-data-filters#transaction-size). ## Events If you've created [Custom Dimensions](/getting-started/managing-your-pagos-organization#adding-custom-dimensions) in Pagos Insights, you can now add them as [columns](/insights/events#column-options) in the table on the **Events** page. ## MID Hierarcies If you organize your MIDs into separate brands or business units, we can assist you in building out a custom hierarchy within the Pagos Insights platform! Learn more in our [Managing Your Pagos Organization](/getting-started/managing-your-pagos-organization#adding-a-custom-mid-hierarchy) guide. ## Custom Dimensions You can now work with your Pagos Account Manager to build out your own [custom dimensions](/getting-started/managing-your-pagos-organization#adding-custom-dimensions) for breaking down your payments data in the [Charts](/insights/charts) section of Pagos Insights. Potential use cases for custom dimensions include: * Turn any [custom metadata field](#adding-metadata-or-soft-descriptors) (e.g. payment channel, subscription type, campaign name) into a dimension * Define your own categories within existing [data filters](/insights/insights-data-filters#filter-options); for example, group issuing banks into "favorite" and "non-favorite" ## Data Audit Request Form When you need help reconciling the data you see in your Pagos account with what you see in your Processor's reports, you can now submit a Data Audit Request form directly from the UI. ## Hourly Alerts We now automatically monitor your approval rate and attempted transaction count on both a daily and **hourly** basis for anomalies. Learn more in the [Alerts](/insights/alerts/alerts-overview#hourly-alerts) guide. ## September 2026 API Migration Guide Legacy API keys and the legacy BIN Data API domains are retired on **September 1, 2026**. Our new [September 2026 API Migration](/authentication/september-2026-api-migration) guide walks through everything changing on that date—unified API keys, the new `bin.pagos.ai` domains, updated static IP addresses, and batch download URLs—along with a migration checklist and troubleshooting for the most common issues. ## Chase Settlement Data Settlement data in Insights now includes transactions processed through Chase, alongside Adyen. This applies everywhere settlement data appears: * [Settlements](/insights/metrics/settlements) Metrics page * Settlement metrics and dimensions in [Charts](/insights/charts) * **Settlement Information** section of the [Events Details Page](/insights/events#event-details-page) ## Settlements in Insights You can now create data visualizations around your Adyen settlement data within Pagos Insights. The following pages contain Settlement data: * Metrics - A new [Settlements](/insights/metrics/settlements) page * Charts - New settlement [metrics](/insights/charts#metrics) (**Settlement Count** and **Settlement Valu**) and [dimensions](/insights/charts#settlements) (**Settlement Type** and **Settlement Currency**) * Data Filters - New filter options ([Settlement Type](/insights/insights-data-filters#settlement-type) and [Settlement Currency](/insights/insights-data-filters#settlement-currency)) ## Pagos MCP Server You can now use the Pagos Community Connector to configure the Pagos MCP server via Claude. Learn more in our [Getting Started with the Pagos MCP Server](https://docs.pagos.ai/mcp/getting-started-with-pagos-mcp-server#claude) guide. ## Deduplicate Filters We've added short descriptions to all deduplicate filter options available in the **Dataset** dropdown in Insights. ## Color Options You can now [change the color palette](/getting-started/managing-your-pagos-account#managing-your-pagos-user-account) of your Pagos Service Panel. The available options correlate to different types of color blindness (e.g. Deuteranopia, Protanopia, and Tritanopia). ## POS Entry Codes We've added a new filter to Insights called [**POS Entry Mode**](/insights/insights-data-filters#pos-entry-mode). Use this filter to view data for transactions where the customer's payment card information was captured in the selected manner. You can also use POS Entry Mode as a [dimension](/insights/charts#transaction) for breaking down custom Charts. For a full list of POS Entry Mode values, see the [POS Entry Mode Codes](/response-codes/pos-entry-mode-codes) reference guide. ## Alerts [Hourly alerts](/insights/alerts/alerts-overview#hourly-alerts-beta) on approval rate and attempted transaction count are now in Beta. Reach out to your Pagos Account Manager to request access. ## Alerts You can now [subscribe](/insights/alerts/alerts-overview#subscribing-to-custom-segment-alerts) to receive alert notifications for a custom segment made by another user within your Pagos Organization. ## Retry Performance The new [Retry Performance](/insights/retry-performance) dashboard is now in Beta. Learn more in [the Pagos Blog](https://pagos.ai/blog/introducing-pagos-retry-performance). Contact your Pagos Account Manager if you want to be included in the Beta. ## Costs When you download **Aggregated Data** from the [Costs](/insights/costs) section of the Pagos Service Panel, your downloaded file will now appear in the **Exports** page once it's ready. ## Opportunities We updated the [Network Tokenization](/insights/opportunities#network-tokenization) tab in the **Opportunities** page to account for the reduced savings Visa now offers for tokenized consumer credit transactions processed in the US. With the release of DCAP, the interchange savings given to eligbile transactions processed with network tokens decreased from 10bps to 5bps. Additional savings are available on transactions for which you pass specific customer and device data, but these potential savings aren't included in the Opportunities page. For more information about DCAP, see [the Pagos blog](https://pagos.ai/blog/what-visa-s-new-dcap-program-means-for-merchants). ## BIN Benchmark We launched a new widget on the Home page of the Pagos Service Panel called [BIN Benchmark](/insights/home#bin-benchmark). Updated every Wednesday, BIN Benchmark has two sections: * **Below Your Recent Average** - Identifies which of your BINS are performing below established trends in your own payments data * **Below Benchmark** - Identifies BINs in MIT and CIT categories where your approval rate falls below the Pagos network benchmark Learn more about this tool in the [Pagos blog](https://pagos.ai/blog/introducing-bin-benchmarking-a-weekly-shortlist-of-the-bins-requiring-your-attention). ## Events You can now customize the table columns in the [Events](/insights/events) page of the Pagos Service Panel. ## Charts We added the following [Dimension options](/insights/charts#dimensions) to Charts: * Durbin Regulated * Card Product Category ## Charts We've added a new [Metric](/insights/charts#metrics) to Charts: Chargeback Win Rate. ## Charts We've added a new [Metric](/insights/charts#metrics) to Charts: Per-Transaction Fees. This option is only available data ingested from Adyen, Braintree, dLocal, PayPal, and Stripe. ## Pagos AI Pagos AI now remembers a high-level summary of past conversations! Learn more in the [Pagos AI FAQ](/insights/pagos-ai-faq#does-pagos-ai-remember-previous-conversations). ## Charts We've changed the default layout for chart [Collections](/insights/charts#collections) to a scrollable list of mid-sized charts. Use the layout toggle to switch to a grid of smaller charts. ## Alerts We added an [Alerts widget](/insights/home#alerts-summary) to the Home page. Here you'll find a list of all payments data anomalies Pagos AI flagged in the last seven days. Click on any alert to navigate to the associated **Alerts Metric Details** page where you can learn more. ## Smaller Updates * **Date Range Filter** - When you select a custom date range using the [date range filter](/insights/insights-data-filters#date-range), the selected dates will appear directly on the filter's drop-down menu. This ensures you can tell at a glance what time period you're looking at data for. * **Cost: Invoices Page** - The [Dimensions drop-down menu](/insights/costs#dimensions-drop-down-menu) on the Invoices page in the Cost section of Pagos Insights now includes **Fee Type** as a breakdown option. ## Processor Data Connections You can now connect to Stripe via an OAuth connection method. Learn more in the [Connect to Stripe](/importing-data/connecting-payment-processors/connect-to-stripe) guide. ## Opportunities You can now export the data in a tab of the [Opportunities](/insights/opportunities) page. This downloads all data on the selected tab to a CSV. ## Cost Health We added a [Cost Health](/insights/home#cost-health) widget to the Home page. It surfaces two types of fee alerts: * **Fee Increases** - Any anomalous month-over-month cost spikes by fee subcategory and processor (updated once a month) * **New Fees** - New fee types that have appeared in the last 30 days ## Alerts When you click the **Focus** icon for an Alerting Segment or Monitored Segment on the Alerts Metric Details page, we now show the segment filters at the top of the focus graph. This clarifies what data we've filtered for in the visualization. ## Data Filters We added a new text field data filter to [Charts](/insights/charts) and the [Fees](/insights/costs#fees) dashboards called **Fee Description**. Use the text field to enter a specific raw fee name as it appears in your processor data. The field uses *contains* logic, meaning we'll filter for all raw fee names containing the text you enter. Apply the filter, then export your **Aggregated Data**; the **Fee Descriptions** column identifies the exact raw fee names you filtered for. ## BIN UI We moved some BIN-related content around the Pagos Service Panel. There are now two pages in the main navigation related to BINs: * **[BIN Insights](/insights/bin-insights)** - Identify the top BINs in your transaction, approval, decline, chargeback, refund, and verification data. * **[BIN](/card-network-apis/bin)** - Located in the **Card Brand APIs** section of the main nav, this page contains three tabs: * **Lookup** - Manually perform BIN lookups and see the response in plain text * **BIN API** - Monitor your usage of the BIN Data API * **Batch** - Download BIN Data Batch files ## Insights Home Your favorite [Charts](/insights/charts) now appear on the Home page when you first log into Insights. ## Custom Data Descriptions You can now add descriptions to your metadata in the [Custom Data](/insights/custom-data#descriptions) section of Insights. Navigate to the **Descriptions** tab to add descriptions, providing additional context on what each field represents. Every Pagos user in your Organization will see the same metadata descriptions in the Descriptions and Metdata tabs, as well as in the metadata filter. ​ ## Charts Click the **star** icon next to a Chart or Collection in the main [Charts](/insights/charts#editing-existing-charts) page to favorite it and bring it to the top of the page. ## Pagos AI Pagos AI is no longer in Beta, and is now available for all Pagos users. Learn more in our [Explore Pagos AI](insights/explore-pagos-ai) guide. ## Opportunities There's a new tab in the **Opportunities** section of Pagos Insights: [Visa CEDP Calculator](/insights/opportunities#visa-cedp-calculator). In this new tab, you can estimate your CEDP participation rate and data quality rate, and we'll calculate the CEDP savings (or costs) you can expect should you pass enhanced data with qualifying Visa transactions. As a part of this launch, we also changed the **Enhanced Data** Opportunities tab to **Mastercard Enhanced Data**. Here you'll find your L2/L3 savings opportunities for qualifying Mastercard transactions. ## Pagos AI Beta We've released a new Beta version of Pagos AI. Learn more in our [Explore Pagos AI](insights/explore-pagos-ai) guide. ## Charts You can now easily [edit the name and description of a custom chart](/insights/charts#editing-existing-charts): navigate to the chart in question, click the name or description, make your edits, then hit **enter**. ## Events The [event details page](/insights/events#event-details-page) for an individual transaction event (e.g. transaction, refund, chargeback, or dispute) now includes the status of that event. ## Charts We added a **Compare to Previous Period** toggle to custom charts created in the [Charts](/insights/charts) section of Pagos Insights. This toggle is only accessible on charts with the **Across Time** View that do **not** have a secondary breakdown dimension. ## Events You can now use **Order ID** to search for individual transaction events in the [Events](/insights/events) section of Insights. ## Charts We've added a new option in the [**Dataset** menu](/insights/charts#deduplicate) on individal charts in the **Charts** section of the Pagos Service Panel: **Apply to this Chart Only**. When toggled on, your selected dataset settings (**Deduplicate** and **Pending Transactions**) will save to the custom chart and remain in place even when you make dataset changes elsewhere in the UI. When toggled off, your dataset selections won't save. # Alerts If you select to receive [Alert notifications](/getting-started/managing-your-pagos-account#notifications) via email, you'll only receive up to one email per day containing all anomaly alerts from the previous day. ## Charts You can now search for individual charts or entire Collections from the Charts landing page. Click the **search** icon, then type the name of a chart or Collection in the search bar. ## Charts When creating a custom chart with [**Verification Approval Rate**](/insights/charts#verification-approval-rate) as the chosen **Metric**, you'll now see a toggle for **View Verification Count**. Clicking this toggle adds your attempted verification count to the graph, providing you context for the corresponding verification approval rate. ## Filters We've added two new filters to Insights: [Fee Type](/insights/insights-data-filters#fee-type) and [Fee Category](/insights/insights-data-filters#fee-category). You can apply these filters to each page under the [Costs](/insights/costs) section of Insights and custom [Charts](/insights/charts) built around fee metrics. ## Options The **Options** drop-down menu that appears on **Metrics** pages and individual custom [Charts](/insights/charts#options) now contains a new toggle: **Show Trend Line**. Click this toggle to add a line to the data visualization demonstrating a statistical trend over the selected date range. Keep in mind the following limitations: * The Trend Line option is only available for charts demonstrating your data across time. * It doesn’t appear in rate charts when the associated count toggle is on or in charts with a secondary Breakdown. * Trend lines exclude the most recent time interval (e.g. this week when viewing a weekly date range, or the last two days for daily intervals), as your data for that time is still coming in and could skew the trend. ## Charts You can now [duplicate existing custom Charts](/insights/charts#editing-existing-charts). To do so, click the **...** icon beside the **View** drop-down menu, then click **Duplicate Chart**. You can then make edits to the duplicate chart to customize it to your needs. ## Charts We've added a new **Metric** in Charts: [Fee Amount](/insights/charts#fee-amount). You can now create custom visualizations for the total fee amount your company faces in a given period of time. Additionally, you can now break down fee-based charts by the following **Dimensions**: * Fee Type * Fee Category * Settlement Currency ## Legacy Canary You can no longer create new triggers in Legacy Canary. For automated data monitoring and anomaly alerting, check out [Alerts](insights/alerts/alerts-overview). ## BIN Data The table in the **Data** tab of your [BIN Data](/insights/bin-data#data) page is now sortable! Click a column header to sort the table by that column's data in descending order; click the header again to sort in ascending order. ## Alerts - Decline Rate When creating a [custom segment in Alerts](insights/alerts/alerts-overview#custom-segments) for the Decline Rate metric, you must select a specific decline code to monitor. Decline Rate Custom Segment Alerts ## Charts When you create a custom visualization in [Charts](/insights/charts) for a rate metric (e.g. approval, decline, chargeback, dispute, or refund rate), you'll now have a new toggle option: **View \[event] count**. Click this toggle to add count to the chart alongside the rate measurements across time. For example, if you make a chart with the Metric set to **Refund Rate**, a **View Refund Count** toggle appears in the top-right corner of the visual; click the toggle to add refund counts as bars to the refund rate line graph. ## Events We added a new tab to [Events](/insights/events): Verifications. You can now view the individual verifications in your payments data. Click a verification in the table to view additional details about the payment method, processor, and more. ## Charts When applying a filter to a custom visualization in [Charts](/insights/charts), you can now select **All** in the parameters list for most filters. This enables you to quickly filter for all parameters except a select few (i.e. select **All** then deselect the parameters you wish to exclude). The only [filter options](/insights/insights-data-filters#filter-options) that don't have an **All** option are BIN, Issuing Bank, Metadata, and Soft Descriptor. ## Alerts You can now create **custom segments in Alerts**. Define the exact market segments you want Pagos to monitor for anomalies, and even set static thresholds for each metric. Whenever that metric crosses the threshold for your defined segment, Pagos will notify you of the change. Learn more in the [Alerts](insights/alerts/alerts-overview#custom-segments) guide. ## Chart Collections In the **Charts** section of Insights, you can now create full dashboards of custom data visualizations called **Collections**. To create a new Collection, drag and drop one chart onto another in the main Charts page. Rename the Collection to indicate who created it or the purpose it was created for. Learn more in the [Charts](/insights/charts) guide. ## Events We added a new field to the **Additional Data** section on the [Event Details page](/insights/events#event-details-page): Soft Descriptor. ## BIN Data We removed the 500 row limit on exports from the [Data](/insights/bin-data#data) tab of BIN Data. ## Events * We added more [filter options](/insights/insights-data-filters#filter-options) to each tab in the [Events](/insights/events) section of Insights. * The **Transaction Details** section on the [Event Details page](/insights/events#event-details-page) now includes **Network Advice** * Network Advice is guidance from card networks like Mastercard that helps merchants understand why a transaction was declined and how to respond. These actionable codes, such as *Do not try again (7903)* or *Retry after 24 hours*, enable merchants to make informed decisions about transaction retries, customer communication, or blocking specific users. At this time, we only receive Network Advice data from Adyen and Braintree. ## BIN Data In the [Data](/insights/bin-data#data) tab of BIN Data, we added more [filter options](/insights/insights-data-filters#filter-options) for the BIN data tables. ## Charts * We added two new [dimensions](/insights/charts#transaction): **Network Advice**. Use this option to break down your chosen metric by the advice a card network provided on how to proceed. * When you select a chargeback metric, you can now break your data down by the dimension of [Network Token](/insights/charts#payment-method) ## Insights Updates * [Charts](/insights/charts) - When you use the **By share** [view option](/insights/charts#views) to create a pie chart, the hover-over key now includes percentages * Your [account currency](/getting-started/managing-your-pagos-account#managing-your-pagos-user-account) - We've added the Swiss Franc (CHF) as a currency option in your account settings ## Charts * We expanded the number of [metric options](/insights/charts#metrics) you can break down by the [dimensions](/insights/charts#dimensions) of **BIN** and **Issuer Bank**. You can select either dimension for all metrics except Chargeback AOV, Dispute Rate/Count/Value, and cost-related metrics. * We added **Soft Descriptor** as a [filter option](/insights/insights-data-filters#filter-options) in Charts. ## BIN FAQs We've added a new section to the Pagos Product Documentation: [BIN Database](/bin-database/getting-started-with-bin-database). This section contains all content relevant to our BIN Database products, including BIN lookups and batch downloads via the Pagos Service Panel, the BIN Data API, and the BIN Data Batch API. We've also added a set of FAQ pages: * [BIN Data General FAQ](/bin-database/general-faq) * [BIN Data: Card Networks and Issuers FAQ](/bin-database/card-network-faq) * [BIN Data: Card Types and Flags FAQ](/bin-database/card-type-flags-faq) * [BIN Data: Network Token Support FAQ](/bin-database/network-tokens-faq) * [BIN Data Integration FAQ](/bin-database/data-integration-faq) ## VAMP Data for Chase We now receive TC40 data from Chase! If you import payments data from Chase, you'll now see TC40 data in your [Visa Formula](/insights/metrics/chargebacks#visa-chargeback-formula-and-vamp-data) breakdown on the Chargebacks Metrics page. ## Unified API Keys The Pagos platform now uses a single, unified API key to authenticate requests to all our services. Check out our new [Pagos API Authentication](/authentication/authentication-overview) guide for full instructions on generating your own unified API key. ## New Charts Dimensions You can now select **BIN** and **Issuer Bank** as dimensions in [Charts](/insights/charts). Select these options to create custom tables demonstrating your chosen metric broken down by the top 25 BINs or Issuers. ## Fee Data at the Transaction Level The [Event Details page](/insights/events#event-details-page) for individual transactions now includes a **Costs & Fees** section. Here you'll find all transaction-level fee information for a given event. ## Fee Data in Charts We've added more options to Charts for viewing and filtering by fee information: * New [metrics](/insights/charts#interchange-effective-rate) - **Interchange Effective Rate** or **Interchange Amount** * New [dimension](/insights/charts#fees) - **Fee Currency** * New filter option - **Fee Currency** ## Effective Rate Breakdown In the [Effective Rate](/insights/costs#effective-rate) page under **Costs**, you can now click a row in the table to view a breakdown of the fee and sale amounts used to calculate your effective rate. ## Amex Effective Rate The [Effective Rate](/insights/costs#effective-rate) page under **Costs** now includes data ingested from [Amex](/importing-data/connecting-payment-processors/connect-to-amex) data connections. ## Chargeback Metrics: VAMP When you select the [Visa formula](/insights/metrics/chargebacks#visa-formula) for calculating chargeback rate in the **Chargebacks** Metrics page, we'll now display your data broken down by the **Fraud Notification (TC40)** vs. **Chargeback (TC15)** contributions to your chargeback volume. This additional granularity helps you better understand how Visa assesses your fraud exposure under new [VAMP](/insights/metrics/chargebacks#vamp-overview) regulations. ## Alerts Update We've added a new Alert metric: [Refund Count](insights/alerts/alerts-overview#refund-count). You'll now see alerts on days when the number of refunds for a segment of your transaction volume increases unexpectedly. ## Charts Update When you create a custom Chart with a refund or chargeback [Metric](/insights/charts#metrics), there's a new [Option](/insights/charts#options) for manipulating the data by **Original Transaction Date**. Use this toggle to change the chart from showing chargebacks/refunds from the selected date range to showing chargebacks/refunds issued against transactions *originally processed* in that date range. ## Insights Updates We've added more options for navigating around the Insights platform to take your data analyses to the next level: * From [Metrics](/insights/metrics/overview#open-with), export to **Charts** to dig in further or [**Events**](/insights/events) to see the exact transaction events behind your visualizations * From [Charts](/insights/charts), export to **Events** * From [Snapshots](/insights/snapshots#open-with), export to **Charts** or **Events** * From [Alerts](insights/alerts/alerts-overview#export-options), export to **Metrics**, **Charts**, or **Events** to learn more about your data anomaly ## Alerts Timing: Chase Data Connections We’ve updated our [Alerts evaluation time](insights/alerts/alerts-overview#alert-timing) for Chase: it now runs with a two day delay instead of one day. This change is to prevent unnecessary alerts, as Chase sometimes sends data out of order. ## Alerts Update We’ve added BIN as a segmentation parameter in [Alert monitoring](insights/alerts/alerts-overview#monitored-segments). Pagos will track attempted transaction counts per BIN and notify you if any one shows a spike inconsistent with its historical patterns. Keep in mind, Alerts accounts for historical fluctuations and seasonality when identifying anomalies, so you only get notified when something truly stands out. ## Chargeback/Dispute Dataset Options By default, visualizations of chargeback and dispute data typically exclude chargebacks/disputes that result in Rapid Dispute Resolution or have the following [status categories](/response-codes/chargebacks/chargeback-status-codes): *cancelled*, *RFI*, *pre-arbitration*, *pre-dispute*, *notification\_of\_fraud*, and *pre-compliance*. You can now add these chargebacks/disputes back in using the new **All Chargeback & Dispute Statuses** toggle in the **Dataset** drop-down on the following pages of your Pagos Service Panel: * [Disputes](/insights/metrics/disputes#all-chargeback-statuses) and [Chargebacks](/insights/metrics/chargebacks#all-chargeback-statuses) Metrics Pages * [Snapshots](/insights/snapshots#all-chargeback-statuses) * [Charts](/insights/charts#all-chargeback-statuses) Additionally, when you make a custom Chart for a chargeback or dispute metric, you'll have a new [Dimensions](/insights/charts#dimensions) option: **Rapid Dispute Resolution**. This dimension breaks down your data by whether or not the transaction was resolved by Visa as Rapid Dispute Resolution. ## Network Tokenization Our Network Tokenization UI has moved into the Pagos Service Panel. All Toucan subscribers can now access their accounts via [https://secure.pagos.ai/sign-in](https://secure.pagos.ai/sign-in). All documentation has been updated to match the new UI: * [Network Tokens](/card-network-apis/network-tokens) * [Network Tokenization API Overview](/network-tokenization/overview) ## Pagos Copilot in Metrics You can now request a data analysis from Pagos Copilot on any Metrics page. Navigate to the desired page and metric, then click **Analyze Data** to generate a data summary and suggested next steps. Learn more in our [Metrics Overview](/insights/metrics/overview#pagos-copilot-analysis) guide. ## Pagos MCP Server We've released our first MCP Server. This server allows AI agents and applications to query the payments intelligence available through Pagos. Once connected, you can use AI agents to query data from our BIN Database for a given BIN number. Learn more in [Getting Started With the Pagos MCP Server](/mcp/getting-started-with-pagos-mcp-server) or check out our [Press Release](https://www.prnewswire.com/news-releases/pagos-launches-first-mcp-server-to-bring-payments-intelligence-to-ai-agents-302478266.html) on this launch! ## Parrot Batch UI BIN Data Batch subscribers can now download the latest Standard and Enhanced BIN data files directly from the [Batch](/insights/bin-data#batch) tab in the BIN Data section of your Pagos Service Panel. ## BIN Data UI Changes We made small changes to the [BIN Data UI](/insights/bin-data). You now navigate between the different BIN Data pages using tabs at the top of your Pagos Service Panel (not in the main navigation). All other functionality remains the same. ## Changelog Notifications We've added a new type of [notification](/getting-started/managing-your-pagos-account#notifications) available in the Pagos Service Panel, via email, or via Slack: Changelog notifications. Once a month, we'll notify users of updates to the changelog from the last month; click the notification to navigate to the Pagos Changelog and learn more. ## Updated L2/L3 Opportunity Breakdown We’ve improved the way we display [Enhanced Data savings opportunities](/insights/opportunities#enhanced-data) to provide a more accurate estimate of potential savings. Previously, transactions eligible for both Level 2 and Level 3 processing were grouped together as L3-eligible. Since Level 3 often offers greater fee reductions, this could lead to overestimated savings. To address this, we now break down transactions into three distinct categories: * Eligible only for Level 2 * Eligible for both Level 2 and Level 3 * Eligible only for Level 3 Each category shows its own estimated savings percentage, helping customers better understand the true value of applying higher data levels. ## Metrics to Charts We've introduced a method for navigating seamlessly between Metrics and Charts. After you identify an interesting segment of data using the filter or focus features in Metrics, click **Export**, then click **Charts** to navigate to a custom chart containing the same data segment. Learn more in our [Metrics](/insights/metrics/overview#open-with) guide. ## Notifications We've added notification capabilities to the Pagos Service Panel! You can now receive notifications in the dashboard, via email, or in a designated Slack channel whenever you receive an [alert](insights/alerts/alerts-overview) or an [data export](/insights/data-exports) is ready for download (Puffin only). Learn more in our [Managing Your Pagos Account](/getting-started/managing-your-pagos-account#notifications) guide. ## Account Updater Our Account Updater UI has moved into the Pagos Service Panel. All Loon subscribers can now access their accounts via [https://secure.pagos.ai/sign-in](https://secure.pagos.ai/sign-in). All documentation has been updated to match the new UI: * [Account Updater](/card-network-apis/account-updater) * [Batch Account Updater API Overview](/account-updater/batch-api-overview) * [Real-Time Account Updater API Overview](/account-updater/real-time-api-overview) ## Events Update Last month, we launched **Events**, which provides access to a unified view of every transaction you processed, harmoinzed across your processors. We've just added three more tabs to this section, displaying the exact transactions behind card **Chargebacks**, non-card **Disputes**, and **Refunds**. Learn more in the [Events](/insights/events) guide. ## Opportunities Update We've improved the **Opportunities** section of Insights! Now, instead of demonstrating the total transaction amount for which cost saving opportunities exist, this section estimates the exact savings amount available. With this update, you now see the dollar amount you could save, estimated based on historical cost data and how often these optimizations are typically applied across similar transactions. This gives you a clearer, more realistic picture of your optimization potential. You’ll also notice a confidence score on each opportunity. That reflects how much visibility we have into your data. For example, we can reliably estimate savings from tokenization with 90% confidence. We have less visibility into how often L2/L3 data or debit routing are actually used, so those estimates are a bit more directional. It’s also important to note that not all benefits are cost-related: network tokenization and debit routing may still increase your approval rates, even if they don’t reduce fees in every case. ### How We Estimate Opportunity Savings Your Opportunities dashboard shows where you could reduce processing costs based on the way transactions are routed and enriched. Each savings estimate is calculated based on: * Which transactions qualify (eligibility) * What the potential cost savings would be, based on real historical data and official network rates The goal is to give you a grounded, directional estimate of what you could actually save. We’ve modeled these calculations by analyzing 13+ months of transaction cost data across processors and geographies, and comparing them against published interchange documentation from Visa and Mastercard. ### Network Tokenization We look at eligible transactions (based on issuer country, card brand, funding type, and merchant processor) and apply the expected savings rate. These savings are sourced from both historical cost data and official Visa/Mastercard documentation. Since not all markets have clear cost savings, estimates are currently limited to the United States, Australia, and Japan. For example, in the United States: * Visa Consumer Credit cards see 0.10% savings * Mastercard payment cards and other Visa cards see no additional cost savings * Only domestic transactions where the merchant and issuer are both US-based experience savings ### Enhanced Data We identify transactions that could qualify for Level 2 or Level 3 data enhancements based on the card network and BIN of the associated payment card. From historical cost data, we’ve observed: * L2 saves \~0.55% * L3 saves \~0.95% * Combined average cost savings: \~0.60% We use these benchmarks to calculate potential savings on your eligible volume. Since we can’t always see whether L2/L3 data was actually applied, this estimate assumes typical usage patterns from comparable merchants. ### Debit Routing Eligible transactions include Visa and Mastercard debit/prepaid cards issued in the US. We estimate savings by applying average rates from historical interchange reports: * Regulated debit: \~0.06% savings * Unregulated debit: \~0.46% savings Savings are calculated based on the assumption that many merchants are only partially routing eligible volume to alternative debit networks—a pattern we’ve seen consistently in the data. Your estimate reflects the remaining opportunity, not what you’ve already captured. ### Why This Matters We know the differences between eligible volume and actual savings can be confusing — especially if you were used to seeing just volume in Opportunities (pre-04/07/2025). These new estimates bring you closer to the real impact of each optimization. While some opportunities (like tokenization or routing) also bring benefits like improved approval rates, we’ve focused here only on measurable cost savings. Approval benefits are something we’re actively working on surfacing in future versions. For more information, check out the [Opportunities](/insights/opportunities) guide! ## Alerts Update We've added a new Alert metric: [Decline Code Rate](insights/alerts/alerts-overview#decline-code-rate). You'll now see alerts on days when the ratio of total attempted transactions declined with a specific decline code increases unexpectedly. ## New Fee Filtering We've added an **Only New Fees** toggle to the **Fees by Category**, **Fees by Subcategory**, and **Interchange & Assessments** pages within the Costs section of Insights. Use this toggle to filter the entire page to only show data for the newest fees you've faced. Learn more in our [Costs](/insights/costs#new-fee-filtering) guide. ## Events We've added a new section to the Pagos Service Panel titled [Events](/insights/events). You now have access to a unified view of every transaction—across every processor—fully harmonized and organized in one place. Take your payments analysis to the next level by digging down to the transaction-level. ## Alerts Update Alerts are now available for all processor connections, including file-based connections like those through JP Morgan Chase or WorldPay Vantiv. See our [documentation](insights/alerts/alerts-overview) for information on alert timing for different connection types. ## Snapshots We've added a new section to Insights titled [**Snapshots**](/insights/snapshots). Here, you'll find a customizable dashboard of payments data visualizations, with a variety of charts under the following categories: * Approvals & Transactions * Declines * Payment Methods * Cards * Chargebacks * Issuers * Subscription & Stored Credentials * 3D Secure * Advanced Authentication * Refunds ## Alerts We've added another payments metric to the [Alerts](insights/alerts/alerts-overview) page: Chargeback Count. Pagos will now automatically monitor your total count of card-based disputes and alert you of anomalies. ## Alerts We've released a new section in the Pagos Service Panel called **Observability**. In this new section, you'll find **Alerts**. **Alerts** offers you a daily health check for your payment processing strategy—no manual setup required! Identify at a glance when your business has experienced unexpected and abnormal changes to key payment metrics like approval rate and attempted transaction count. Check out our [Alerts](insights/alerts/alerts-overview) guide for more information! ## Charts In the [Charts](/insights/charts) section of Pagos Insights, you can now build custom charts demonstrating the following verification metrics: * **Verification Rate** - The percentage of total verification attempts that succeeded in a given time period; calculated by dividing the total number of approved verifications by the total number of attempted verifications * **Verification Count** - The total number of attempted verifications processed in a given time period * **Verification Value** - The total combined value of all attempted verifications processed in a given time period ## Penalties The [Penalties](/insights/costs#/penalties) page under the **Costs** section of Insights now includes data imported from Adyen. This page now displays your data for all of the following connected processors: * Adyen * Braintree * Chase * Stripe * Worldpay As of December 6, 2024, we've introduced a significant change to our UI, namely moving Parrot, Peacock, Canary, Flamingo, and Puffin into a single interface: the [Pagos Service Panel](https://secure.pagos.ai/sign-in). Almost all Pagos customers use multiple Pagos products, and as such, we wanted to make it easy to access and use all your subscriptions from a single platform. For any existing Pagos users, all functionality remains the same, but the names and locations of certain products or pages have changed. This involved minor changes to the ways you [manage account details](/getting-started/managing-your-pagos-account) , add [data connections](/importing-data/managing-data-connections), and access your API keys. All documentation on these topics has been updated to match the new UI. ## Peacock Content is now under Insights Moving forward, Peacock's data aggregation and visualization resources are located in a section of the Pagos Service Panel called **Insights**. This section contains the following content: * [Metrics](/insights/metrics/overview) * [Charts](/insights/charts) * [Opportunities](/insights/opportunities) * [Risks](/insights/risks) * [Costs](/insights/costs) * [Pagos AI](/insights/explore-pagos-ai) All Pagos merchants who subscribed to Peacock before December 2024 will continue to have access to the following content, now located under a new section in the main navigation called **Peacock Legacy**: * [Standard Dashboards](/legacy-peacock/standard-dashboards) * [Custom Dashboards](/legacy-peacock/custom-dashboards) * Know Your Data ## Parrot Resources are now under BIN Data Parrot and Parrot Batch resources are now located in a section of the Pagos Service Panel section called **BIN Data**. Here you'll find three pages: Data, Lookup, and API Metrics. All Peacock subscribers can access the [**Data**](/insights/bin-data#data) page, which provides a detailed breakdown of the top BINs in your payments data. If you're subscribed to Parrot, you can also access the other two pages. From [**Lookup**](/insights/bin-data#lookup) , you can perform BIN lookups without any code or having to use the Pagos BIN Data API. The [Parrot API](/bin-data-APIs/bin-data-api-overview) continues to function as is without any changes. ## Charts We’ve added a new section to Peacock called [**Charts**](/insights/charts). With Charts, you can now build out completely customized data visualizations. Monitor and visualize any payment metric, broken down by the dimensions you’re most concerned about, in whatever chart style meets your business needs. Dive deep into the KPIs or customer segments most important to your company, and even save these charts for future use. Check it out: