Real-Time Account Updater

Enterprise

Account Updater is an Enterprise feature. Request access in the portal.

Real-Time Update

Attempts to retrieve updates to a single card token in real-time. Possibly returns a new card token if there were updates available.

POST

https://api.basistheory.com/account-updater/real-time

Permissions

account-updater:real-time:invoke

Request

cURL

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"
  }'

Node

await client.accountUpdater.realTime.invoke({
  tokenId: 'b4b89606-794a-4652-b375-f4e1d717a5db',
});

C#

await client.AccountUpdater.RealTime.InvokeAsync(new RealTimeAccountUpdaterRequest
{
  TokenId = "b4b89606-794a-4652-b375-f4e1d717a5db"
});

Java

AccountUpdaterRealTimeResponse response = new AccountUpdaterClient(ClientOptions.builder().build())
    .realTime()
    .invoke(AccountUpdaterRealTimeRequest.builder()
        .tokenId("b4b89606-794a-4652-b375-f4e1d717a5db")
        .build());

Python

client.account_updater.real_time.invoke(
  token_id = "b4b89606-794a-4652-b375-f4e1d717a5db"
)

Go

client.AccountUpdater.RealTime.Invoke(ctx, &basistheory.RealTimeAccountUpdaterRequest{
    TokenId: "b4b89606-794a-4652-b375-f4e1d717a5db",
})

Request Parameters

Attribute	Required	Type	Description
token_id	true	string	Card Token identifier
expiration_month	false	integer	The 2-digit expiration month of the account number. Not required if the card token already stores this value.
expiration_year	false	integer	The 4-digit expiration year of the account number. Not required if the card token already stores this value.
deduplicate_token	false	boolean	Whether to deduplicate tokens when performing updates
configuration_merchant_id	false	uuid	The tenant merchant whose Account Updater configuration is used for this request. Does not affect which tokens the request can read. See Merchant Scoping and Configuration.
merchant_id	false	uuid	Deprecated: use configuration_merchant_id instead. Legacy alias kept for backward compatibility with lower precedence.

The token_id must correspond to a card token in your tenant and the card must contain a number valid for the Visa or Mastercard networks. If the card number corresponds to a different network, the WRN_UNSUPPORTED_NETWORK result code will be returned.

If the card token is missing an expiration date, the expiration_month and expiration_year parameters must be provided. If the token already contains an expiration date, these parameters will override the token's expiration date when requesting updates from the network.

The deduplicate_token parameter will override the tenant-level deduplicate tokens setting. If token deduplication is enabled and an account update is received with data matching an existing token's fingerprint, the existing token will be updated and returned in new_token instead of creating a new token.

Merchant Scoping and Configuration

Merchants affect a request in two independent ways:

• Token scope is set by the optional BT-MERCHANT-ID request header. The token_id is resolved within that merchant's scope, and any updated token is created under the same merchant. Without the header, the request runs at the tenant level.
• Account Updater configuration is selected by the optional configuration_merchant_id parameter, which determines the merchant configuration (the merchant details registered with the card networks during onboarding) used to request updates. When omitted, it defaults to the configuration of the BT-MERCHANT-ID header merchant, then to the tenant-level configuration.

Use Case	How to Configure
Tenant-level tokens using the tenant's configuration	Omit the BT-MERCHANT-ID header and configuration_merchant_id.
Tenant-level tokens using a merchant's configuration	Omit the BT-MERCHANT-ID header and set configuration_merchant_id. This is the most common pattern for tenants onboarded with multiple merchant configurations whose tokens are not merchant-scoped.
A merchant's tokens using that merchant's configuration	Send the BT-MERCHANT-ID header. The header merchant's configuration is used by default.
A merchant's tokens using a different merchant's configuration	Send the BT-MERCHANT-ID header and set configuration_merchant_id.

If the selected merchant does not have its own Account Updater configuration, the tenant-level configuration is used.

Response

Property	Type	Description
new_token	object	Returns a new token if an update was found.
result_code	string	The result code of this update request

{
  "new_token": {
    "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
    "type": "card",
    "data": {
      "number": "XXXXXXXXXXXX4242",
      "expiration_month": 12,
      "expiration_year": 2027
    },
    "card": {
      "bin": "42424242",
      "last4": "4242",
      "expiration_month": 12,
      "expiration_year": 2027,
      "brand": "visa",
      "funding": "credit",
      "issuer_country": {
        "alpha2": "PL",
        "name": "Bermuda",
        "numeric": "369"
      },
      "authentication": "sca_required"
    },
    ...
  },
  "result_code": "UPD_PAN"
}