Skip to main content

Token lifecycle

A payment-instrument token is a short-lived value created during tokenization. It has a defined lifecycle and is single-use: it can be spent exactly once, either on a transaction or on an attach call, at which point it is consumed. The token also carries the CVV the customer typed, and that CVV covers exactly one charge.

For differences between tokenization paths, see When to use FramePay vs server-side. For the attach call, see Attach a token to a customer.

Stages​

  • Created: The token is returned by the tokenization call. It has an expiratedAt (or null, depending on the path) and is ready to be spent.
  • Consumed: The token has been spent, either by POST /transactions with paymentInstruction.token or by attaching it to a customer via POST /customers/{id}/payment-instruments. It is now permanently used up and cannot be reused, including by the other of those two calls.
  • Expired: The token's expiratedAt has passed before it was spent. The token can no longer be used; re-tokenize the card to obtain a new one.

Response shape​

A successful tokenization call returns:

{
  "id": "Token ID",
  "createdAt": "2025-12-18T08:30:16+00:00",
  "expiratedAt": null
}

The expiratedAt may be null if the token does not auto-expire, or a future timestamp by which the token must be spent.

Relation to payment instrument lifecycle​

A token is distinct from a payment instrument. Either way of spending the token produces one, and which path you take depends on what you are building.

Transactions: the customer-initiated charge creates the instrument.

Token (created) → POST /transactions (CIT) → Payment instrument returned on the response → Usable for merchant-initiated charges once result is "approved"

Subscriptions: attach creates the instrument first.

Token (created) → Attach → Payment instrument (inactive) → First hosted-form payment → Payment instrument (active) → Auto-charged on renewals

See Card on file for the transaction path and Attach a token to a customer for the subscription path.

For payment instrument states (inactive, active, expired, deactivated), see Payment instrument lifecycle.

Common mistakes​

MistakeResult
Storing the token to save it for laterThe token expires before you use it, requiring you to re-tokenize. Tokens are single-use and short-lived; spend them immediately.
Trying to attach the same token to two customersThe second attach call returns 422 (UnprocessableContent) because the token was consumed by the first call.
Sending a token to POST /subscriptionsThe field is silently ignored: no error, no payment instrument, and the subscription behaves as if no card had been supplied. Subscriptions charge only a paymentInstrumentId, so attach the token first. See Attach a token to a customer and Create a subscription.
Attaching a token before charging itOn POST /transactions the token is the correct instruction whenever the customer is present. Pass { "paymentInstruction": { "token": "<token>" } }. Attaching first spends the token, and the CVV it carried then covers only the instrument's first charge; every charge after that declines.
Spending a token twiceBoth directions fail, with different errors. Attaching a token already spent, whether on a transaction or on an earlier attach, returns 422 (UnprocessableContent). Charging a token already spent on an attach call fails with PaymentInstrumentInvalidToken. Pick one path per token.