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

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

Node

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

JavaScript (legacy)

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'
  },
});

C#

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

Python

client.token_intents.create(
  type="card",
  data={
    "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

Only card Token Intents are generally available at this time. Please reach out to request access to other token types.

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",
    "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

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

Node

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

JavaScript (legacy)

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");

C#

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

Python

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

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.
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

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
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, 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

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

Authentication Types

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