Tokenización y pagos recurrentes

Cada pago exitoso crea automáticamente un token reutilizable (tok_xxx). El token sustituye a la tarjeta del cliente. Ningún dato de tarjeta se expone a tu sistema, y el token funciona para cobros de cualquier monto o calendario.

Obtener el token

El token_id se devuelve en dos lugares:

• La respuesta de GET /checkout-sessions/{id} → transaction.token_id
• El webhook payment.completed → payload_redacted.token_id

Guárdalo en el registro del cliente.

Cobrar un token

POST /api/v1/charge-token

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

Respuesta exitosa

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

Respuesta fallida

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

Casos de uso

• Renovaciones de suscripción — cobra el token según un calendario.
• Tarjetas guardadas — clientes recurrentes reutilizan una tarjeta sin reingresarla.
• Recargas — saldos de billetera, flujos de recarga.
• Pago por uso — facturación por llamada API, uso medido.

Facturación de suscripciones

Genius Checkout incluye un motor de suscripciones integrado que programa cobros, reintenta renovaciones fallidas y emite eventos subscription.charged. Mira la sección Subscriptions del panel del comerciante, o construye tu propio scheduler sobre charge-token.

Ciclo de vida del token

• Un token permanece activo hasta que lo revoques desde el panel del comerciante o el portal del cliente.
• Un token revocado devuelve failed con un error claro si intentas cobrarlo.
• Los tokens están limitados por comerciante — la misma tarjeta usada en dos comerciantes crea dos tokens distintos.

Siguiente

• Reembolsos — emite reembolsos totales o parciales
• Ejemplos de código → Cobro recurrente