Token Intents

A Token Intent is a short-lived resource that simplifies the collection and validation of sensitive data from public applications. Token Intents serve as placeholders for sensitive data similarly to Tokens, and allow for additional validation to be performed (e.g. Credit Card Authentication, 3DS, Fraud Checks) before being converted into a Token for long-term retention.

A Token Intent automatically expires after 1 day. You may request a change to this default TTL (up to 48 hours) in your Tenant Quotas in the portal.

Create Token Intent

Create a new token intent.

POST

https://api.basistheory.com/token-intents

Permissions

token-intent:create

Request

curl "https://api.basistheory.com/token-intents" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "type": "card",
  "data": {
    "number": "4242424242424242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "cvc": "123"
  }
}'

await client.tokenIntents.create({
  type: "card",
  data: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    cvc: '123'
  },
});

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

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

const tokenIntent = await bt.tokenIntents.create({
  type: "card",
  data: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    cvc: '123'
  },
});

await client.TokenIntents.CreateAsync(new CreateTokenIntentRequest
{
  Type = "card",
  Data = new
  {
    number = "4242424242424242",
    expiration_month = 12,
    expiration_year = 2025,
    cvc = "123",
  }
});

client.token_intents.create(
  type="card",
  data={
    "number": '4242424242424242',
    "expiration_month": 12,
    "expiration_year": 2025,
    "cvc": '123'
  }
)

new TokenIntentsClient(ClientOptions.builder().build()).create(CreateTokenIntentRequest.builder()
    .type("card")
    .data(new HashMap<String, Object>() {{
        put("number", "4242424242424242");
        put("expiration_month", 12);
        put("expiration_year", 2025);
        put("cvc", "123");
    }})
    .build());

tokenIntent, err := client.TokenIntents.Create(ctx, &basistheory.CreateTokenIntentRequest{
    Type: "card",
    Data: map[string]interface{}{
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2025,
        "cvc": "123",
    },
})

Request Parameters

Attribute	Required	Type	Default	Description
`type`	true	string	`null`	The type of token intended to be created
`data`	true	any	`null`	The data to tokenize - must satisfy validation rules for the chosen token type

The type network_token is not available at this time.

Response

Returns a 201 status code with a response body containing a Token Intent on success. Returns an error if there were validation errors, or the Token Intent failed to create.

{
  "id": "665bf471-d675-4165-9336-4fc9c1a73fad",
  "tenant_id": "8935ed5e-c082-4837-9063-6f0a2b4265dc",
  "type": "card",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "brand": "visa",
    "funding": "credit",
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    }
    "authentication": "sca_required"
  },
  "fingerprint": "BzQfn8W5PTjHMZgmJfbTjNceWNTnqLEEoEEuhtS7fHca",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2024-10-30T19:23:57+00:00"
}

Get a Token Intent

Retrieves a Token Intent by its ID.

GET

https://api.basistheory.com/token-intents/{id}

Permissions

token-intent:read

Request

curl "https://api.basistheory.com/token-intents/665bf471-d675-4165-9336-4fc9c1a73fad" \
-H "BT-API-KEY: <API_KEY>"

await client.tokenIntents.get("665bf471-d675-4165-9336-4fc9c1a73fad");

await client.TokenIntents.GetByIdAsync("665bf471-d675-4165-9336-4fc9c1a73fad");

client.token_intents.get(
  id="665bf471-d675-4165-9336-4fc9c1a73fad"
)

new TokenIntentsClient(ClientOptions.builder().build()).get("665bf471-d675-4165-9336-4fc9c1a73fad");

tokenIntent, err := client.TokenIntents.Get(ctx, "665bf471-d675-4165-9336-4fc9c1a73fad")

URI Parameters

Attribute	Required	Type	Default	Description
`id`	true	string	`null`	The ID of the token intent

Response

Returns a 200 status code with a response body containing a Token Intent on success. Returns an error if the Token Intent was not found or you don't have permission to access it.

{
  "id": "665bf471-d675-4165-9336-4fc9c1a73fad",
  "tenant_id": "8935ed5e-c082-4837-9063-6f0a2b4265dc",
  "type": "card",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "brand": "visa",
    "funding": "credit",
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    }
    "authentication": "sca_required"
  },
  "fingerprint": "BzQfn8W5PTjHMZgmJfbTjNceWNTnqLEEoEEuhtS7fHca",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2024-10-30T19:23:57+00:00"
}

Delete Token Intent

Deletes a Token Intent without waiting for expiration. Use this endpoint to remove Token Intents that fail validation.

DELETE

https://api.basistheory.com/token-intents/{id}

Permissions

token-intent:delete

Request

curl "https://api.basistheory.com/token-intents/dda42a6b-964b-46d8-b315-eb6dfda37c32" \
-H "BT-API-KEY: <API_KEY>" \
-X "DELETE"

await client.tokenIntents.delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

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

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

await bt.tokenIntents.delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

await client.TokenIntents.DeleteAsync("id");

client.token_intents.delete(
  id="id",
)

new TokenIntentsClient(ClientOptions.builder().build()).delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

err := client.TokenIntents.Delete(ctx, "dda42a6b-964b-46d8-b315-eb6dfda37c32")

URI Parameters

Attribute	Required	Type	Default	Description
`id`	true	string	`null`	The ID of the token intent

Response

Returns a 204 status code and empty body on success. Returns an error if the Token Intent failed to delete.

Convert Token Intent to Token

To convert a Token Intent into a Token, you'll utilize the Create Token or Tokenize endpoint by passing in a token_intent_id instead of type and data. All other attributes of a token are available during the conversion.

Conversion Rules

Card

Attribute	Rule
`cvc`	The CVC will not be moved to the Token, as the Card has been authorized. Ensure all actions have been completed with the CVC before conversion.

Deduplication

If token deduplication is enabled, and a Token exists in your Tenant with the same fingerprint and container as the converted token, then the existing Token will be updated. This update operation follows the same merge-patch behaviors that are used when updating a Token.

Token Intent Object

Attribute	Type	Description
`id`	string	Unique identifier of the Token Intent, which can be used in detokenization expressions or to convert to a token
`tenant_id`	uuid	The Tenant ID which owns the Token Intent
`type`	string	The type of token intended to be created
`card`	object	The Card Details when `type` is `card` or `card_number`, otherwise `null`.
`bank`	object	The Bank Details when `type` is `bank`, otherwise `null`.
`network_token`	object	The Card Details when `type` is `network_token`, otherwise `null`.
`authentication`	object	The 3DS authentication information (ie: cryptogram) when `type` is `network_token`, otherwise `null`.
`fingerprint`	string	Uniquely identifies the contents of this Token Intent using the default fingerprint expression for the Token Types
`expires_at`	string	The expiration date for this Token Intent
`created_by`	uuid	The Application ID which created the Token Intent
`created_at`	date	Created date of the Token Intent in ISO 8601 format
`_extras`	object	(Response-Only) An object containing information regarding the tokenization process

Extras Object

Attribute	Type	Description
`network_token_ids`	array	A list of network token IDs that were created based on the current token intent

Card Details

Attribute	Type	Description
`bin`	string	Six to eight digit BIN of the card
`last4`	string	Last four digits of the card
`expiration_month`	number	The 2-digit expiration month of the card
`expiration_year`	number	The 4-digit expiration year of the card
`brand`	string	The primary card brand
`funding`	string	The primary funding type of the card
`segment`	string	The segmentation of the card (eg., Consumer, Commercial)
`issuer`	object	Describes the country and issuing bank. See Issuer for details
`issuer_country`	object
.alpha2	string	Issuing country ISO3166 alpha country code
.numeric	string	Issuing country ISO3166 numeric country code
.name	string	Issuing country name
`authentication`	string	The authentication type required for this card
`additional`	array	Contains additional details associated to the same BIN number. See Card Additional for details.

Card properties shows the primary card details, while Card.additional provides additional card details found for the same BIN.

If a card number does not correspond to any known BIN Details, then brand, funding, issuer_country, and authentication will default to null and the default BIN will be returned.

Card Additional

Attribute	Type	Description
`brand`	string	An additional card brand
`funding`	string	An additional funding type of the card
`authentication`	string	An additional authentication type required for this card
`issuer`	object	Describes the country and issuing bank. See Issuer for details

Authentication Types

Authentication Type	Description
`sca_required`	Indicates that Strong Customer Authentication (SCA) is required (e.g. 3DS)

Card Brands

The following card brands are supported in the card property (primary details). Please note that the additional property may contain extra card brands not listed in this table.

Brand	Description
`american-express`	American Express
`diners-club`	Diners Club
`discover`	Discover
`ebt`	EBT
`elo`	Elo
`hipercard`	Hipercard
`jcb`	JCB
`mastercard`	Mastercard
`mir`	MIR
`private-label`	Private Label
`proprietary`	Proprietary
`unionpay`	UnionPay
`visa`	Visa

Card Funding Types

Funding Type	Description
`credit`	Credit Card
`debit`	Debit Card
`prepaid`	Prepaid Card

Issuer

Attribute	Type	Description
`country`	string	Issuing country ISO3166 alpha country code
`name`	string	Issuing bank name

Bank Details

Attribute	Type	Description
`routing_number`	string	The routing number of the bank account
`account_number_last4`	string	Last four digits of the bank account number

Create Token Intent​

Permissions​

Request​

Request Parameters​

Response​

Get a Token Intent​

Permissions​

Request​

URI Parameters​

Response​

Delete Token Intent​

Permissions​

Request​

URI Parameters​

Response​

Convert Token Intent to Token​

Conversion Rules​

Card​

Deduplication​

Token Intent Object​

Extras Object​

Card Details​

Card Additional​

Authentication Types​

Card Brands​

Card Funding Types​

Issuer​

Bank Details​

Create Token Intent

Permissions

Request

Request Parameters

Response

Get a Token Intent

Permissions

Request

URI Parameters

Response

Delete Token Intent

Permissions

Request

URI Parameters

Response

Convert Token Intent to Token

Conversion Rules

Card

Deduplication

Token Intent Object

Extras Object

Card Details

Card Additional

Authentication Types

Card Brands

Card Funding Types

Issuer

Bank Details