Batch Account Updater
Last updated: June 18, 2025
The Batch Account Updater enables you to:
- Upload a secure batch file to our SFTP server to manually update your Mastercard and Visa cards on file.
- Automatically update your American Express cards.
You can enable the following services individually with the Batch Account Updater service:
| Card scheme | Service | Description |
|---|---|---|
Mastercard | Batch via SFTP | Requests updated details from schemes for the cards you provide in a batch file. Cards do not need to be stored in the Vault. Updated card details are returned securely so that you can store them independently. For Visa and Mastercard, your PCI compliance level must be SAQ D or higher to use this update mechanism. |
Visa | ||
American Express | American Express Account Updater | Checkout.com securely sends your recurring billing and card-on-file information to American Express. Every 24 hours, we match your recurring billing data with American Express card member information. We then receive a secure file back, providing updates for cards that have been replaced, renewed, or closed and update your stored data. |
Information
American Express Account Updater happens automatically every 24 hours. You don't need to upload a batch file.
To manually update your Mastercard and Visa instruments via SFTP, follow these steps:
- Configure your Secure File Transfer Protocol (SFTP) server.
- Prepare the batch file.
- Encrypt the batch file.
- Upload the batch file to the SFTP server.
To manually upload update card details in bulk, you must first configure an SFTP server to upload your batch files to.
To create a public and private key pair, run the following command in your command line tool:
This generates:
- A public key, with the file name
checkout-sftp.pub. - A private key, with the file name
checkout-sftp.
To retrieve the public key using the command line, run the following command in your command line tool:
Alternatively, you can locate and open the file using your system's file explorer.
Contact your account manager or [email protected] to request an SFTP server and provide them with your public key.
In return, you'll receive the following:
- An SFTP server
- A port
- A username
To sign in to your SFTP server, use the following credentials:
- Username – The username provided to you by Checkout.com
- Password – The private key you generated in an earlier step
When you sign in to your SFTP server, you can access:
- The uploads folder, where you upload your batch files.
- The results folder, where we return the results of each batch request.
Your batch file must follow RFC 4180 standards and use a specific format so that it can be processed successfully.
The CSV file must have the following fields:
- Card number – Updated card number.
- Expiry month – Updated expiry month. This field is numeric, in the form of
MM. - Expiry year – Updated expiry year. This field is numeric, in the form of
YYYY. - Reference – Your reference for the card. Don't include sensitive data in this field.
Encrypt the batch file to protect any sensitive information it may contain, such as card numbers or customer names.
Before you begin, install GnuPG using one of the following options:
- GnuPG installer – Windows and macOS
- Homebrew, using the
brew install gnupgcommand – macOS only, requires Homebrew to be installed - Chocolatey, using the
choco install gnupgcommand – Windows only, requires Chocolatey to be installed
Then, follow the steps for the environment you want to encrypt the batch file for:
- Import the public Checkout.com key for the test environment, using the following command in your terminal:
- Confirm that the key imported successfully:
- Encrypt the CSV with the imported key. In the following command, replace
[FILE_NAME]with your CSV file name, and[KEY_ID]with the ID listed in the output from the previous step:
By default, the encrypted file is created in the same directory as the source file, with a .gpg file extension. For example, example.csv.gpg.
Sign in to your SFTP server and upload the batch file to the uploads folder.
If you encounter an issue when uploading or processing your batch file, ensure that the file:
- Has a .GPG or .ASC file extension.
- Contains comma-separated data in CSV format – other delimiters are not supported
- Is encoded using UTF-8
- Is encrypted with PGP
- Uses a character set that follows Unicode standards
- Does not exceed 100MB in size
- Does not exceed the 100,000 row limit
Once you successfully upload the batch file, it's added to the processing queue. The file is automatically deleted after 24 hours.
When your batch request is processed, you'll receive a file in your SFTP server's results folder.
The results file is a CSV file containing the following headers:
- Correlation ID – An identifier of the change request.
- Source ID – The Checkout.com card source identifier, if the request was not made using a Card Number
- Reference – Your reference for the card, from the original request
- Response Code – The response code indicating the result of the card's Account Updater request. This can be one of:
errorno_changeupdated_cardupdated_expirydisabled
- Response Summary – If the response code is
error, the error code. - Card number – The number of the updated card.
- Expiry Month – The updated expiry month.
- Expiry Year – The updated expiry year.
- Scheme – The scheme of the updated card.
The following table provides a description for each possible response code:
| Response code | Description |
|---|---|
| The card has been disabled. |
| There was an error processing the data record. View the response summary to determine the reason for the error. |
| The card details have not changed. |
| Card details have been updated, including a change to the card number. |
| Card details have been updated. Only the expiry month and/or expiry year have changed (the card number did not change). |