> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Account Updater 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.

<Note>
  Review our [Testing](/account-updater/batch-testing) guide for full instructions on how to test the Batch Account Updater API in the sandbox.
</Note>

## 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.

<Warning>
  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.
</Warning>

To register your encryption keys:

<Steps>
  <Step>
    Click your **settings** icon in the top-right corner.
  </Step>

  <Step>
    Under **Developers**, click **API Keys**.
  </Step>

  <Step>
    Click the **Action API** tab.
  </Step>

  <Step>
    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)
  </Step>

  <Step>
    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.
  </Step>

  <Step>
    Click **Create** to store your public key and exit out of the side panel.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

### 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.<br />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                             |