Tokenization API

What crosses the wire

• Where it sits

  Between card entry and every later charge. The token is created once, from a hosted surface, and after that your systems reference it instead of a card: for a repeat purchase, a subscription, a deposit and balance, or a charge taken in a different channel.

• What you send

  For creation, nothing sensitive — the hosted surface supplies the credential and your server receives the reference. For reuse and lifecycle operations, the token itself plus the customer record it belongs to. The reference documents the exact fields.

• What comes back

  A token reference and enough non-sensitive detail to show a customer which card they are using: brand and last four digits, not the number. Anything that would let you reconstruct the credential is deliberately absent.

When to use it

• Anything charged more than once

  Subscriptions, instalments, memberships, deposits followed by a balance: each one needs a credential that survives the first transaction without your systems holding a card.

• One-click and returning customers

  A stored token turns a repeat purchase into a confirmation rather than a card entry, and it works whether the customer returns online or calls in.

• Keeping PCI scope narrow

  Storing tokens instead of card numbers keeps raw credentials out of your environment, which narrows what has to be assessed rather than adding controls around holding them.

How to implement Tokenization API

What fails, and how you find out

• Storing anything beside the token

  Keeping the card number as well, even briefly, even encrypted, puts the credential back in your environment and undoes the reason for tokenizing at all.

• A token nobody can attribute

  A token stored without the customer record it belongs to becomes unusable the moment someone asks which card is on file. Write both in the same transaction.

• Tokens that are never retired

  A customer who deletes a card expects it gone. A vault that only ever grows is a compliance problem and a support problem, and the deletion path is the one integrations most often skip building.

• Assuming a token outlives a reissue on its own

  The token reference survives, but the credential behind it has to be refreshed. Without Account Updater enrolment, a reissued card fails on the next charge with a decline nobody caused.

Sandbox versus production

• Tokens do not cross environments

  A token created in sandbox has no production counterpart and cannot be charged with production keys. Every stored credential has to be created again in the environment it will be billed in.

• Lifecycle operations are safe to rehearse

  Creating, replacing and deleting tokens in sandbox is the practical way to prove your deletion path works, which is difficult to test convincingly against real customer records.

• Updater behaviour is simulated

  Sandbox can show a refreshed credential flowing through to a stored token, but real coverage depends on the network and issuer participating. Build the handling in sandbox; expect variation in production.