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: you can attach it to a customer exactly once, at which point it is consumed.

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 expirationTime (or null, depending on the path) and is ready to be attached.
  • Consumed: The token has been attached to a customer via POST /customers/{id}/payment-instruments. It is now permanently used up and cannot be reused.
  • Expired: The token's expirationTime has passed before an attach call can occur. 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",
  "createdTime": "2025-12-18T08:30:16+00:00",
  "expirationTime": null
}

The expirationTime may be null if the token does not auto-expire, or a future timestamp by which the attach call must happen.

Relation to payment instrument lifecycle​

A token is distinct from a payment instrument. The attach call turns a token into a payment instrument:

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

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; attach them immediately.
Trying to attach the same token to two customersThe second attach call fails because the token was consumed by the first call.
Treating the token as a payment instrumentTokens cannot be used directly on POST /subscriptions or POST /transactions. You must attach them first to get a paymentInstrumentId.