Batch Implementation

This guide provides an overview of how to implement Batch Account Updater. It covers the entire process, from initial setup to creating the batch job, generating and uploading the input request file, downloading the batch job results, and processing the results.

Initial Setup

First, ensure that you have completed the Account Updater Setup guide. This step is only required once.

Private Application

You will need a Private Application to allow your backend to call Basis Theory APIs. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

• Permissions: account-updater:job:create, account-updater:job:read

Save the API Key from the created Private Application as it will be used later in this guide.

Configure Webhooks (Recommended)

Configure a webhook to receive notifications for job status changes. You are able to subscribe to the following event types:

• account-updater.job.created
• account-updater.job.completed
• account-updater.job.failed

1. Create Batch Job

Start by creating an Account Updater Batch Job which responds with an Account Updater Job. We will use the upload_url in the response below to upload a request CSV file for processing.

You have one hour to upload a request file, at which time the job and upload url will expire. If a job expires before uploading the request file, simply start the process again by creating a new job.

2. Create Request File

Next we must create a request CSV file containing the card tokens you would like to update.

When testing, you can simulate various scenarios using the Account Updater Test Cards. You can either use the API to create tokens containing these test card numbers, or use this script to quickly generate test card tokens within your test tenant.

If your card tokens include an expiration date, you may omit the expiration_month and expiration_year fields.

Test tenants can always omit the merchant_id field -- only include merchant_id in production requests IF Basis Theory explicitly instructed you to do so during Account Updater onboarding.

Example Request File

token,expiration_year,expiration_month,merchant_id
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,,,

Large batches of tokens over the request file size limit can be split into multiple files and processed in parallel by creating multiple jobs.

3. Upload Request File

Once you have created a request CSV file, you can use the upload_url received when creating the batch job to submit your file for processing. You can use the upload_url to upload your file using any usage patterns supported by S3 pre-signed URLs.

cURL

curl -X PUT -T "/local/path/to/file" "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."

Node

const fileName = `.data/${jobId}/request.csv`; // create your csv request file here
const fileStats = fs.statSync(fileName);

const response = await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'text/csv',
    'Content-Length': fileStats.size,
  },
  body: fs.createReadStream(fileName),
  duplex: 'half',
});

4. Wait for Job Completion

There are two ways to receive notifications about the status of your batch jobs:

1. (Preferred) Configure webhooks to receive an account-updater.job.completed event when the job is completed.
2. Poll the Get Account Updater Job endpoint and wait for the job status to change to completed.

Job Timing

Tenant Type	Job Completion Time
Test	Near real-time
Production	Typically 1 day, can take up to 7 days

Production jobs may take longer to complete and are dependent on the card networks' processing times, which can take up to 7 days.

We recommend submitting your batch jobs at least 7 days before any recurring transactions are scheduled to ensure the update has time to complete.

5. Download Result File

Once a job is in the completed status, retrieve the job details to obtain the download_url which you will invoke to download the Result File.

You may use any usage patterns supported by S3 pre-signed URLs to download this file.

cURL

curl -o "output-file-name" "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."

Node

await axios.get("https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/...", {responseType: 'stream'})
  .then(response => {
    // Create a write stream to save the file
    const writer = fs.createWriteStream("results.csv");

    // Pipe the response stream into the write stream
    response.data.pipe(writer);

    // Return a promise that resolves when the file has been downloaded
    return new Promise((resolve, reject) => {
      writer.on('finish', resolve);
      writer.on('error', reject);
    });
})

6. Process the Result File

The Result File contains the results of the batch job, including a result_code for each row. Process this file in your system and take appropriate actions based on the result codes - note that some warning-level result codes may require additional action on your part.

Rows that received an update will contain the new_card field with the id of a new card token. The token references in your system should be updated accordingly, and this new token should be used for future transactions. You have the option to retain the old token that was replaced or delete it once it is no longer needed.

Rows that did not result in any updates, warnings, or errors are omitted from the result file.