Idempotency

Basis Theory supports idempotency to guarantee multiple retries of the same request do not unintentionally perform the same operation more than once.

Our API endpoints accept a client-provided Idempotency Key if sent with the BT-IDEMPOTENCY-KEY HTTP header within POST, PUT and PATCH methods.

If an Idempotency Key is not provided by the client, retrying the same request might result in unwanted behavior. Some operations also enforce their own retry rules, such as 3DS session authentication.

The Idempotency Key must be a unique value generated by the client which is used by the Basis Theory API to identify subsequent requests belong to an original request. The Idempotency Key generation is up to the client, but we strongly recommend using a unique identifier such as UUID to avoid collisions.

When the first request comes in, its response status code and body is saved. Whenever a subsequent request comes in with the same Idempotency Key, the previous stored result will be returned if it succeeded. If the first request failed, the result is not stored and a subsequent request with the same Idempotency Key is processed as a new request. If any subsequent request comes in while the first is still processing, a 409 status code is returned.

If an Idempotency Key is provided for a GET or DELETE request, it is ignored and idempotency logic is not invoked, since these HTTP verbs are idempotent by definition.

All idempotency keys and their respective results are deleted after 24 hours. Therefore, if an Idempotency Key is reused after 24 hours, it will be handled as a new request.

Proxy requests do not currently support idempotency. Please reach out if you would like this capability.

Example

cURL

curl "https://api.basistheory.com" \
-H "BT-API-KEY: <API_KEY>" \
-H "BT-IDEMPOTENCY-KEY: aa5d3379-6385-4ef4-9fdb-ca1341572153"

Node

let token = await client.tokens.create(
    {...},
    {idempotencyKey: '<YOUR IDEMPOTENCY KEY>'}
);

JavaScript (legacy)

import {BasisTheory} from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const applications = await bt.tokens.create(
{},
{
  idempotencyKey: "aa5d3379-6385-4ef4-9fdb-ca1341572153",
}
);

C#

await client.Tokens.CreateAsync(new CreateTokenRequest
    {...},
    new IdempotentRequestOptions
    {
        IdempotencyKey = Guid.NewGuid().ToString(),
    }
);

Python

client.tokens.create(
    ...
    idempotency_key=idempotency_key
)

Go

idempotencyKey := uuid.NewString()

tokenCreatedResponse, err := client.Tokens.Create(
  context.TODO(),
  &basistheory.CreateTokenRequest{
    ...
  },
  option.WithIdempotencyKey(&idempotencyKey),
)

3DS Session Authentication

The following rules apply to sessions created after session authentication idempotency is enabled for your tenant. Sessions created earlier retain their previous behavior. Contact us to confirm availability for your tenant.

Once authentication starts for a session, repeating the request cannot start another authentication for that session. This applies to both Authenticate Session and the redirect flow, including requests without a BT-IDEMPOTENCY-KEY. Changing the key or waiting for its 24-hour expiry does not allow authentication to start again.

If you reuse a key with a cached successful response, the API returns that cached response as described above. Otherwise, session authentication follows these rules:

Condition	Response
The request matches the original authentication request and a result has been saved	200 with the saved authentication, including any challenge result already recorded on the session.
Authentication has started, but no result has been saved	409. A later request can return a result if one becomes available; it cannot restart authentication.
Authentication has started and the request contains different authentication data or metadata	409. Use the original request for that session.
A concurrent session update prevents authentication from starting	409. Retry with the same session ID and request.

Validation failures before authentication starts allow you to correct the request and try again. Authentication input is limited to 262,144 UTF-8 bytes of serialized JSON, including metadata; larger input returns 413 before authentication starts.

A timeout or a 409 without a saved result does not establish the authentication outcome. Retrieve the session to check its current authentication. If no result is available, contact us with the session ID. Authentication retries do not automatically recover a missing result.