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

Store the card once, then charge the token as many times as you need:

1. Create a customer (skip if one already exists).
2. Vault the card against that customer to get a token.
3. Charge the token on any Sale or Authorization and Capture.

Step 1: Create a customer

A customer represents the cardholder whose card you're storing. Create one with POST /checkout/v3/customer.

Retrieve a customer later with GET /checkout/v3/customer/{id}.

Step 2: Vault the card

Store the card against the customer with POST /checkout/v3/customercardaccount/{customerId}, where {customerId} is the customer's id.

POST /checkout/v3/customercardaccount/10000001221810

{
  "name": "Alex Johnson",
  "number": "4100000000000126",
  "expiryMonth": "12",
  "expiryYear": "2030",
  "cvv": "211",
  "avsStreet": "2001",
  "avsZip": "30068"
}

A successful call returns 201 Created with the stored card's id, last4, 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}.

Step 3: 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

{
  "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.
• 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