Skip to main content

Account Updater
Enterprise

Account Updater is an Enterprise feature. Contact support@basistheory.com to request access.

Basis Theory supports merchants who leverage card-on-file transactions or subscription billing models by allowing payment card data to be collected and securely vaulted for future transactions. However, vaulted card details can become outdated when cards are re-issued due to card expiration, account closures, lost or stolen cards, or fraud prevention. This can result in failed transactions and billing disruptions, leading to involuntary customer churn or lost revenue. Account Updater enables you to keep vaulted card tokens up to date with the latest information from the card networks, improving transaction success rates.

Each request to update a batch of cards is referred to as an Account Updater Job. Job requests and results are transmitted using CSV-formatted flat files containing Basis Theory tokens. Jobs are submitted in a 2-step process - first, create an account updater job and receive an upload URL in the response, then upload your request CSV file directly through the upload URL. Once all updates have been received from the card networks and the job has been completed, you will receive a webhook reporting the overall job status. If successful, the job's result details can be downloaded in CSV format, which you can use to update token id references in your system.

Basis Theory currently supports updating card tokens against the Visa, Mastercard, American Express, and Discover networks.

Create Account Updater Job

Creates an Account Updater Job to update a batch of card tokens. Responds with an Account Updater Job including an upload_url to submit a request CSV file for processing.

POST
https://api.basistheory.com/account-updater/jobs
Copy

Permissions

account-updater:job:create

Expiration

You have one hour to upload a request file, at which time the job and upload url will expire and the job will be removed. Attempting to retrieve an expired job will result in a 404 status code. If a job expires, simply start the process again by creating a new job.

Request

curl "https://api.basistheory.com/account-updater/jobs" \
-X POST \
-H 'Content-Type: application/json' \
-H 'BT-API-KEY: ...' \
-d '{ "callback_url": "https://api.merchant.com/account_updater/job_notification" }'

Request Parmeters

ParameterRequiredTypeDefaultDescription
callback_urlfalsestringThe URL that will be called once a job has completed

Response

{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"callback_url": "https://mycallback.com",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
}

Upload Request File

Once you have created a Request CSV File, you can use the upload_url for the 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.

The maximum upload file size is 30 MB per file (approx. 300k tokens)
curl -X PUT -T "/local/path/to/file" "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."

Get Account Updater Job

Retrieves an Account Updater Job. This endpoint can be used to poll for job failure or completion if webhook callbacks are not desired.

GET
https://api.basistheory.com/account-updater/jobs/{id}
Copy

Permissions

account-updater:job:read

Request

curl "https://api.basistheory.com/account-updater/jobs/93f3da5e-7887-408c-88ed-b10a5fdb423a" \
-H 'BT-API-KEY: ...'

Response

{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"callback_url": "https://mycallback.com",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
}

List Account Updater Jobs

Return a list of all Account Updater Jobs created for the tenant.

GET
https://api.basistheory.com/account-updater/jobs
Copy

Permissions

account-updater:job:read

Request

curl "https://api.basistheory.com/account-updater/jobs" \
-H 'BT-API-KEY: ...'

Sort Order

This endpoint returns newest jobs first.

Query Params

ParamDescription
sizeThe maximum number of jobs to return in the response. Defaults to 20.
startThe cursor at which the result set should start. This is the value of the next cursor returned in the previous response.

Response

{
"pagination": {
"page_size": 20,
"next": "Q1JFQVRFRF9BVCMyMDI0LTA0LTI1VDE2OjU4OjA3LjgyMVo="
},
"data": [
{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"callback_url": "https://mycallback.com/",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
},
...
]
}

Account Updater Job Webhook

When a job status changes to either completed or failed, the following webhook will be sent to the configured callback_url.

Webhook Payload

{
"type": "account-updater.job.completed",
"timestamp": "2024-04-10T11:45:13.877Z",
"data": {
"job_id": "b4c1a8f0-9a17-4d80-849e-32e4bf5b7c61",
"status": "completed"
}
}

Webhook Types

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

Properties

PropertyDescription
job_idThe identifier of the job
statusThe status of the job

Download Result File

Once a job is in the completed status, you can use the download_url returned when retrieving a job to download the Result File.

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

File Format Specifications

Request File Format

Account Updater request CSV files must use the following format:

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

Properties

PropertyDefinitionRequired
tokenA card token to be updated. The expiration date in this token is optional, and if present, will be sent to the networks when requesting updates.true
expiration_yearThe 2-digit expiration year of the account number. This is not required if the card token has expiration_year stored.false
expiration_monthThe 2-digit expiration month of the account number. This is not required if the card token has expiration_month stored.false
merchant_idThe merchant identifier (provided by Basis Theory) under which this update request is submittedtrue

Result File Format

The result file is used to communicate any tokens created as a result of an updated account number or expiration date. This file only includes rows that resulted in a successful update, a warning, or an error (see Result Codes for details). Rows that did not result in any updates are omitted from the result file.

Account Updater result CSV files will use the following format:

token,expiration_year,expiration_month,new_token,new_expiration_year,new_expiration_month,result_code
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,b2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,UPD_PAN
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,30,02,,,,WRN_CLOSED_ACCOUNT

Properties

PropertyDefinitionAlways Returned
tokenThe card token to be updated, as sent in the request filetrue
expiration_monthThe expiration_month that was sent in the request file.false
expiration_yearThe expiration year that was originally sent.false
new_tokenThe new card token created with updated card details. Update any references to this token in your systems.false (only on successful update)
new_expiration_monthThe new expiration month returned from the update.false
new_expiration_yearThe new expiration year returned from the update.false
result_codeCode summarizing the processing status of the row. See Result Codes below for details.true

Result Codes

Code Prefixes

PrefixDescription
UPDA update was received from the network; update your records with the updated token.
WRNThe token was correctly processed, although it did not result in an update. Action is potentially required.
ERRAn error occurred while processing the file or token, requiring action.

Result Codes

Result CodeDescriptionAction
UPD_PANThe issuer updated the account number, or account number and expiration date.A new token has been created. Update your records.
UPD_EXP_DATEThe issuer updated the expiration date.A new token has been created. Update your records.
UPD_BRAND_CONVThe card brand has changed but the issuer remains the same. The account number or expiration may or may not be changed.If a new token has been created, update your records.
UPD_CORRECTEDThe issuer corrected a previous update.A new token has been created. Update your records.
WRN_CLOSED_ACCOUNTThe issuer closed the account holder’s account.Exclude the token from future account updater requests.
WRN_CONTACT_CARDHOLDERThe merchant should contact the account holder for additional information on the account.No Update - Reach out
WRN_ISSUER_NOT_ENROLLEDThe issuer for the requested card number does not participate in the Account Updater program.No update - consider removing this token from future requests.
WRN_ISSUER_NO_DATAThe issuer provided no information regarding the specific card number requested.No update - consider removing this token from future requests.
WRN_OPT_OUTThe cardholder has opted out of the account updater service.No update - consider removing this token from future requests.
ERR_UNDEFINEDUndefined error.Contact support.
ERR_INVALID_PANThe card number is invalid.Check that this token contains a valid card number for one of the supported networks (Visa, Mastercard, American Express, or Discover). Omit from future requests.
ERR_INVALID_TOKENToken not found.Check that the token is of type card and that the token exists in this tenant.
ERR_INVALID_EXP_DATEThe expiration date was invalid.Check expiration month and year exist on the token or in the row's expiration_month and expiration_year fields
ERR_INVALID_CONFIGInvalid Account Updater configuration.Verify that the merchant_id matches the one given to you during onboarding. If your merchant_id matches, contact support.

Test Cards

The following cards can be used to test the Result Codes.

PANExp. MonthExp. YearResult Code
4111111111111111122023UPD_PAN
6011690151507086122023UPD_EXP_DATE
6011760519541711122023UPD_BRAND_CONV
6011490740263725122023UPD_CORRECTED
5461310156953048122023WRN_CLOSED_ACCOUNT
4929980395567582122023WRN_CONTACT_CARDHOLDER
4916725297925395122023WRN_ISSUER_NO_DATA
5580422612666704122023WRN_ISSUER_NOT_ENROLLED
4035501000000008122023WRN_OPT_OUT
6011178332216017122023ERR_UNDEFINED
6011648103759866122023ERR_INVALID_EXP_DATE
378025849667382122023ERR_INVALID_PAN
370000000000002122023ERR_INVALID_CONFIG
4711358892785746122023(No change and not returned in file)

Code Sample to generate test cards

#You will need an API Key with `token:create`

curl --location 'api.flock-dev.com/tokenize' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'BT-API-KEY: <BT API KEY>' \
--data '[
{
"type": "card",
"data": {
"number": 4111111111111111,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 6011690151507086,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 6011760519541711,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 6011490740263725,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 5461310156953048,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 4929980395567582,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 4916725297925395,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 5580422612666704,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 4035501000000008,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 4711358892785746,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 6011178332216017,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 6011648103759866,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 378025849667382,
"expiration_month": "12",
"expiration_year": "2023"
}
},
{
"type": "card",
"data": {
"number": 370000000000002,
"expiration_month": "12",
"expiration_year": "2023"
}
}
]
'

Resources

Account Updater Job

PropertyTypeDescription
idstringIdentifier for the account updater job
tenant_iduuidThe tenant this job is associated with
statusstringThe job status, values include: failed, completed, pending, processing
callback_urlstringThe URL that will be called once a job has completed
expires_atdatetimeTime the upload URL will expire. This property is only returned while the job is in the pending status.
created_byuuidThe id of the application used to create the job
created_atdatetimeTimestamp when this job was created
upload_urlstringThe URL to which the Request File should be uploaded. This will only be returned when the job is in the pending status.
errorsarray<string>An array of error messages encountered when attempting to process the job
download_urlstringThe URL to download the Result File. This will only be returned when the job is in the completed status.