Tokenization & Recurring Payments

Every successful payment auto-creates a reusable token (tok_xxx). The token is a stand-in for the customer's card. No card data is ever exposed to your system, and the token works across charges of any amount or schedule.

Get the Token

The token_id is returned in two places:

• The GET /checkout-sessions/{id} response → transaction.token_id
• The payment.completed webhook → payload_redacted.token_id

Store it on the customer record.

Charge a Token

POST /api/v1/charge-token

{
  "token_id": "tok_abc123",
  "amount": 999,
  "currency": "USD",
  "order_id": "RENEWAL-1042"
}

Success response

{
  "status": "captured",
  "token_id": "tok_abc123",
  "amount": 999,
  "currency": "USD",
  "gateway_transaction_id": "5ABCABEC-4867-410B-B76C-E85721CF859B"
}

Failure response

{
  "status": "failed",
  "token_id": "tok_abc123",
  "error_code": "05",
  "error_message": "Declined — insufficient funds"
}

Use cases

• Subscription renewals — charge the token on a billing schedule.
• Saved cards — let returning customers reuse a card without re-entering it.
• Top-ups — wallet balances, reload flows.
• Pay-as-you-go — per-API-call billing, metered usage.

Subscription billing

Genius Checkout has a built-in subscription engine that schedules charges, retries failed renewals, and emits subscription.charged events. See the merchant dashboard's Subscriptions section, or build your own scheduler on top of charge-token.

Token lifecycle

• A token stays active until you revoke it from the merchant or customer portal.
• A revoked token returns failed with a clear error if you try to charge it.
• Tokens are scoped per merchant — one card used at two merchants creates two distinct tokens.

Next

• Refunds — issue full or partial refunds
• Code Samples → Recurring Charge