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.

📘

Verify a card before you store it

To confirm a card is valid without charging it, run an account verification ($0 auth) first, then vault the card.

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 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. The response also includes isDebit, which tells you whether the saved card is a debit (true) or credit (false) card.

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

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.

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

See also

• Account Updater: refresh stored cards automatically
• Sale: charge a vaulted token
• Authorization and Capture: reserve then capture a vaulted token
• Transaction Context: send Credential-on-File context for stored cards