Card vaulting (tokenization) stores a customer's card securely and returns a token you reuse for future payments, so you never handle or store the raw card number again. Tokens are always stored against a Customer as a Customer Card Account, which links the token to a customer profile.

Vaulting powers the payment experiences your customers expect: one-click checkout, subscriptions, and recurring billing, with less PCI scope for you.

Common use cases

One-click checkout for returning customers
Recurring and subscription billing
Charging a saved card for a later or repeat purchase

How vaulting works

Every vaulted card is stored against a Customer as a Customer Card Account and returns a reusable token. There are two verified ways to vault:

Method	When to use
Vault during a sale (`shouldVaultCard: true`)	The primary path — store the card as part of a normal payment, in one call.
Vault an existing payment	Save the card from a payment you already ran, by referencing its `paymentId`.

Method 1: Vault during a sale (recommended)

Set shouldVaultCard: true on POST /checkout/v3/payment. The card is charged and stored in the same call, and the response returns the reusable card under cardAccount (cardId + token).

POST /checkout/v3/payment
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "merchantId": 1000157980,
  "amount": 25.00,
  "tenderType": "Card",
  "paymentType": "Sale",
  "shouldVaultCard": true,
  "cardAccount": {
    "number": "4100000000000126",
    "expiryMonth": "12",
    "expiryYear": "30"
  },
  "customerName": "Alex Johnson",
  "source": "API"
}

The response includes the stored card so you can charge it later:

{
  "id": 4100000001181552,
  "status": "Approved",
  "cardAccount": {
    "cardType": "Visa",
    "last4": "0126",
    "cardId": "krUFoe65m8745tyX6lWBSezfPmcf",
    "token": "TK9OUKWS7YFDNR32JC4E9L575VZ18G2N"
  }
}

See Sale → Scenario 3 for the complete request and response.

Method 2: Vault an existing payment

To save the card from a payment you already ran, call POST /checkout/v3/customercardaccount, passing the customer id and the source paymentId as query parameters. This stores the card the payment used — you never re-collect the raw PAN.

Create the customer first (if one doesn't exist) with POST /checkout/v3/customer and use its id as {customerId}. A customer requires at least a first and last name plus your merchantId — a fully anonymous, vault-only record is not supported. If you don't have personal data, put a reference value (for example, a folio or account number) in the name fields.

POST /checkout/v3/customercardaccount?id={customerId}&paymentId={paymentId}
Content-Type: application/json
x-api-key: YOUR_API_KEY

A successful call returns 201 Created with the stored card's id, last4, cardId, and the token you'll charge against.

{
  "id": 10000001221810,
  "last4": "0126",
  "cardId": "KyCexTXUStE9clx7GO42EB4r9h0f",
  "token": "TK9OUKWS7YFDNR32JC4E9L575VZ18G2N"
}

Retrieve all stored cards for a customer with GET /checkout/v3/customercardaccount/{customerId}.

Charge the token

Pass the token inside cardAccount on any payment. The vaulted card behaves exactly like a raw card, so it works for both Sale and Authorization and Capture.

POST /checkout/v3/payment
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "merchantId": 1000157980,
  "amount": 25.00,
  "tenderType": "Card",
  "paymentType": "Sale",
  "cardAccount": {
    "token": "TK9OUKWS7YFDNR32JC4E9L575VZ18G2N"
  },
  "source": "API"
}

The response returns the payment id, its status, and a paymentToken for follow-on actions (void, adjustment, refund). See Sale for the full response and tracking.

📘
A vaulted token (stored card) and a paymentToken (a specific transaction) are different. Only a token returned by a vaulting call — shouldVaultCard: true or POST /checkout/v3/customercardaccount — is a reusable stored-credential token. The cardAccount.token echoed on an ordinary payment response is transaction-scoped (it matches that payment's paymentToken) and will not work to charge the card later. Use the vaulted token to start a new payment; use the paymentToken to act on an existing one.

Best practices

Get consent. Store a card only with the customer's agreement, and tell them how it will be used (one-time, recurring, or subscription).
Vault once, reuse the token. Never re-collect or store the raw PAN; keep only the token.
Saved cards are isolated per merchant. Vaulted cards belong to a single merchant account; one merchant can never see or charge another merchant's stored cards.
Keep cards current. Enable Account Updater so expired or reissued cards keep working without customer action.
Send AVS data. Include avsStreet and avsZip when vaulting to support AVS checks at payment time.

Used in these scenarios

Vaulting shows up in the core sale flows:

Charge a card and save it for next time: vault the card during a sale.
Charge a saved card: charge the stored token later.

Next steps

Account Updater

Keep vaulted cards current automatically.

Sale

Charge a vaulted token in one step.

Card Vaulting