Card Tokenization: Store Cards for Future Payments

Tokenization replaces a raw card number with a reusable reference — a token prefixed with vt_ — that Therius stores securely in its vault. Once a card is tokenized, you never need to collect the card details again. Tokens are scoped to your merchant account, carry BIN metadata (card brand, type, and issuer), and work on any future purchase or authorization call exactly like the original card data.

Two Ways to Tokenize

1. During a Payment

Add "tokenize": true inside card.cardData (or card.nonceData if using the JS SDK nonce flow), and include a shopper.id to associate the token with a specific customer. The payment processes normally, and the response includes the new token.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "paymentMethod": {
    "type": "card",
    "card": {
      "cardData": {
        "cardNumber": "4111111111111111",
        "cardholderName": "Ada Lovelace",
        "expiryMonth": "12",
        "expiryYear": "2030",
        "cvv": "123",
        "tokenize": true
      }
    }
  }
}

The response includes a token field alongside the normal payment fields:

{
  "status": "captured",
  "paymentCode": "PAY-abc123",
  "token": {
    "id": "vt_4xK9mNpQ2rLsT7uV",
    "expirationDate": "2030-12-31",
    "tokenCreationReference": "PAY-abc123"
  }
}

Store token.id against the shopper in your database. It is the only thing you need to charge them again.

Cards on asynchronous payments

A card is saved only once the payment is approved. When the provider answers a card payment with pending (4ON, for example), the response has no token yet: Therius holds the card, encrypted, until the payment settles, then saves it, or erases it if the payment fails. When the card is saved you receive:

The payment.captured (or payment.authorized) webhook, with data.token in the same shape as above, when the card was saved before the webhook was sent.
A token.created webhook with data.token, data.payment_id and data.payment_code. This is the reliable one: store the token from it, because the payment webhook can be sent before the card is saved.

See Saved card events.

2. Standalone Token Creation

Call POST /token to store one or more cards as tokens without making a payment. This is useful during account setup flows where you want to save a card on file before the first purchase.

{
  "merchantCode": "MERCHANT_001",
  "shopper": { "id": "shopper-42" },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardholderName": "Ada Lovelace",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvv": "123"
    }
  }
}

The response returns the same token value (vt_...) without processing a charge.

Using a Token on Future Requests

Pass card.tokenData.token instead of card.cardData on any subsequent purchase or authorization. The request shape and the response shape are identical to a normal payment.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-002",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "paymentMethod": {
    "type": "card",
    "card": {
      "tokenData": {
        "token": "vt_4xK9mNpQ2rLsT7uV"
      }
    }
  }
}

CVV on Tokenized Cards

You can optionally include card.tokenData.cvv when charging a token. Some acquirers require the CVV for cardholder-initiated transactions (CIT) but not for merchant-initiated transactions (MIT) or recurring charges.

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "tokenData": {
        "token": "vt_4xK9mNpQ2rLsT7uV",
        "cvv": "123"
      }
    }
  }
}

If you are running a subscription or an automated retry, omit the CVV — the shopper is not present to provide it.

Wallet Tokenization

Apple Pay and Google Pay payment methods can also be saved for recurring use. Set "tokenize": true inside the wallet’s own object, alongside a shopper.id.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "USD", "value": 5000, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "paymentMethod": {
    "type": "applepay",
    "applepay": {
      "token": "<wallet payment token from device>",
      "tokenize": true
    }
  }
}

The resulting vt_... token behaves identically to a card token on future requests.

ACH Tokenization

Bank account details submitted via ACH can be tokenized the same way. Set "tokenize": true inside the ach object. bankAccountNumber, bankRoutingNumber, bankAccountType, and payerName are also required on the charge itself (see Bank Transfers).

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "USD", "value": 5000, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "paymentMethod": {
    "type": "ach",
    "ach": {
      "payerName": "Ada Lovelace",
      "bankAccountNumber": "123456789",
      "bankRoutingNumber": "021000021",
      "bankAccountType": "checking",
      "tokenize": true
    }
  }
}

The response returns a vt_... token you can use on future ACH charges without asking the shopper for their bank details again — pass it as a flat token in place of the raw bank fields.

Token lifecycle

A token is active, deleted, erased or expired. Check it at any time with GET /token/{token}.

Status	What it means	Can it be charged?
`active`	The card is saved and in use.	Yes.
`deleted`	The shopper removed the card, a support agent deleted it, a newer save of the same card replaced it, or Therius retired it (see below).	Yes, until the card data is erased. The response carries the header `X-Therius-Token-Status: deleted`.
`erased`	The card data was permanently erased under the retention policy.	No.
`expired`	The token’s own expiration date has passed.	No.

When card data is erased

Therius does not keep card data forever.

A deleted card is erased 2 years after the latest of its deletion, its last payment and the end of the last subscription that used it. Using the token again moves that date.
A card nobody deleted is retired when it expired more than 30 days ago, or when no payment was made with it for 18 months. A retired card becomes deleted with deletedReason expired or unused, you receive token.deleted, and its data is erased 30 days later.
A card that an active subscription or a payout beneficiary still uses is never retired or erased.

Erasing removes the encrypted card number, the network token and any bank account details, and deletes the card at Therius’s card vault provider. The brand, last four digits and expiry stay, so past payments keep showing “Visa ••••4242”. The token itself stays too, so your references to it never dangle.

Knowing when a token stops working

Webhooks: token.deleted when a card is deleted or retired, token.erased when its data is erased, and subscription.payment_method_removed when a shopper deletes the card a subscription renews on. See Webhook events.
Errors: charging a token that can no longer be charged returns 400 with a code you can branch on.

`code`	Meaning	What to do
`token_erased`	The card data was erased.	Ask the shopper for a new card.
`token_expired`	The token’s expiration date has passed.	Ask the shopper for a new card.
`token_not_found`	No such token for your merchant account.	Check the value you stored.

A subscription keeps charging its card after the shopper deletes it from their saved cards, until you replace the payment method with Update payment method. Use subscription.payment_method_removed to ask the shopper for a new card in time.

Security

Therius tokens are PCI-safe. A vt_... token is usable only within the Therius vault and only by your merchant account. It cannot be used to retrieve the raw card number, and it is not accepted by any external payment system. Storing tokens instead of card data means your database is out of scope for PCI DSS requirements related to PANs.

Get Started

Core Concepts

Guides

Webhooks

AI Assistant

E-Commerce Plugins

Card Tokenization: Store Cards for Future Payments

Two Ways to Tokenize

1. During a Payment

Cards on asynchronous payments

2. Standalone Token Creation

Using a Token on Future Requests

CVV on Tokenized Cards

Wallet Tokenization

ACH Tokenization

Token lifecycle

When card data is erased

Knowing when a token stops working

Security

​Two Ways to Tokenize

​1. During a Payment

​Cards on asynchronous payments

​2. Standalone Token Creation

​Using a Token on Future Requests

​CVV on Tokenized Cards

​Wallet Tokenization

​ACH Tokenization

​Token lifecycle

​When card data is erased

​Knowing when a token stops working

​Security

Two Ways to Tokenize

1. During a Payment

Cards on asynchronous payments

2. Standalone Token Creation

Using a Token on Future Requests

CVV on Tokenized Cards

Wallet Tokenization

ACH Tokenization

Token lifecycle

When card data is erased

Knowing when a token stops working

Security