Skip to main content

Real-Time Implementation

This guide provides an overview of how to implement Real-Time Account Updater. It covers the initial setup, how to request an update, and how to process 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:real-time:invoke
Save the API Key from the created Private Application as it will be used later in this guide.

Request Real-Time Update​

Given a vaulted card token that you wish to update, first identify whether your system persists the expiration date within the card token. If not persisted in the token, you will need to provide the expiration_month and expiration_year parameters in the update request.

Submit a request for a real-time update through the API or an SDK using the API key for the application created above.

curl "https://api.basistheory.com/account-updater/real-time" \
  -H 'Content-Type: application/json' \
  -H 'BT-API-KEY: ...' \
  -X POST \
  -d '{
    "token_id": "b4b89606-794a-4652-b375-f4e1d717a5db"
  }'

Process the Result​

The API response will include a result_code that indicates the outcome of the update request. Note that some warning-level result codes may require additional action on your part.

If an update was received, the response will contain the new_card field containing a 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.