Tokenization Flow
How card tokenization and subsequent charges work end-to-end.
Card tokenization lets you vault a customer's card once and reuse it for future charges without handling raw card data again. This is the foundation for one-click payments and subscriptions.
#1. Tokenize the Card
Send a POST /api/v1/payments/card/tokenize request with the customer's card details. The response includes a cardToken — a secure reference you store on your side.
The token is valid for up to 90 days by default (configurable via expirationDate). The original card details are never stored by you.
#2. Charge Using the Token
For subsequent payments, send POST /api/v1/payments/card/charge with the cardToken instead of raw card details. The charge follows the same flow as a standard card payment — including 3DS if required by the issuer.
This enables:
- One-click checkout — the customer doesn't re-enter card details
- MIT (Merchant-Initiated Transactions) — charge without the customer present
- Subscription billing — see Recurring Payments
#3. 3DS on Subsequent Charges
Even with a saved token, the card issuer may still require 3DS for high-value or unusual transactions. Your charge response will include transactionStatus: "CUSTOMER_VERIFICATION" and a challengeUrl if this happens — handle it the same way as a first-time payment.
#4. Webhook & Status
Exirom sends a webhook to your callbackUrl with the final transactionStatus once the charge completes. Use GET /api/v1/payments/card/status/{id} as a fallback if the webhook is missed.
#Related
- API Reference: POST /api/v1/payments/card/tokenize — Tokenize endpoint spec, Try It
- API Reference: POST /api/v1/payments/card/charge — Charge endpoint spec, Try It
- Recurring Payments — Automated subscription billing
- Payment Process Flow — Standard (non-tokenized) payment flow