Stripe Forward

Tokenize

Endpoint conforming to Stripe's API contract to use their Forwarding API and create a card token.

This endpoint differs from the Create Token endpoint by conforming to Stripe's Forwarding API contract: card contains Stripe's payment method details, and metadata contains any Basis Theory specific token attributes that were specified when calling the Forwarding API.

The card object will then be transformed to the Basis Theory's card token data, so any expression used in the original request to the Forwarding API referring to card data must reference the final transformed data object as shown in the example request below. Specifically, in line 16 when referencing the card's expiration month, it is data.expiration_month and not card.exp_month.

{
  "data": {
    "number": "...",
    "expiration_month": "...",
    "expiration_year": "...",
    "name": "..."
  }
}

POST

https://api.basistheory.com/connections/stripe-forward/tokenize

Permissions

token:create

Request

cURL

curl "https://api.basistheory.com/connections/stripe-forward/tokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "card": {
    "number": "4242424242424242",
    "exp_month": "07",
    "exp_year": "2030",
    "cvc": "123",
    "name": "John Doe"
  },
  "metadata": {
    "mask": {
      "number": "{{ data.number | reveal_last: 4 }}",
      "expiration_month": "{{ data.expiration_month }}",
      "expiration_year": "{{ data.expiration_year }}",
      "name": "{{ data.name }}"
    },
    "containers": [ "/pci/high/" ],
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    },
    "search_indexes": [
      "{{ data.number | last4 }}"
    ],
    "fingerprint_expression": "{{ data.number }}",
    "deduplicate_token": true,
    "expires_at": "8/26/2030 7:23:57 PM -07:00"
  }
}'

Request Parameters

Attribute	Required	Type	Default	Description
card	true	Stripe Card	null	The card details to tokenize.
metadata	false	Stripe Metadata	null	Basis Theory's token attributes used when creating the card token.

Stripe Card

Attribute	Required	Type	Default	Description
number	true	string	null	The card number without any separators
exp_month	false	string	null	Two-digit string representing the card's expiration month
exp_year	false	string	null	Four-digit string representing the card's expiration year
cvc	false	string	null	Three or four-digit card verification code with automatic expiration
name	false	string	null	The Cardholder Name

Stripe Metadata

Attribute	Required	Type	Default	Description
id	false	string	null	A value or expression specifying the token's ID. If not specified, a UUID will be assigned.
mask	false	any	Depends on the token type	Token data mask. Can be an object, array, or any primitive type such as an integer, boolean, or string. See mask expressions.
containers	false	array	Depends on the token type	Array of containers to place this token within. Each container is a path representing a logical grouping of tokens. See Token Containers for details.
metadata	false	map<string, string>	null	A key-value map of strings containing non-sensitive data.
search_indexes	false	array	null	Array of expressions used to generate indexes to be able to search against.
fingerprint_expression	false	string	{{ data | stringify }}	Expressions used to fingerprint your token.
deduplicate_token	false	bool	null	Whether the token is deduplicated on creation.
expires_at	false	string	null	ISO8601 compatible Token expiration DateTime. See Token Expiration for more details.

Never reveal sensitive information in the id of your token. See the documentation on Aliasing to learn more about best practices when specifying your own token ID.

Never store sensitive plaintext information in the metadata of your token.

Response

Returns a token if the token was created. Returns an error if there were validation errors, or the token failed to create.

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "data": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": "07",
    "expiration_year": "2030",
    "name": "John Doe"
  },
  "mask": {
    "number": "{{ data.number | reveal_last: 4 }}",
    "expiration_month": "{{ data.expiration_month }}",
    "expiration_year": "{{ data.expiration_year }}",
    "name": "{{ data.name }}"
  },
  "containers": ["/pci/high/"],
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "search_indexes": ["{{ data.number | last4 }}"],
  "fingerprint": "2W6iy15GJoqj5V696BnsadZVTst5fjJf24iW9Kg6hFDa",
  "fingerprint_expression": "{{ data.number }}",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2030-08-26T19:23:57-07:00"
}

For security reasons, the data and metadata attributes are redacted from the response when a token is deduplicated, unless the API Key has token:read permission in the targeted container. Click here to learn more about this behavior.