Sesiones de Checkout

Una sesión de checkout es una URL de un solo uso y corta duración que aloja la página de pago. La creas en tu servidor, rediriges al cliente, y verificas el resultado al regreso. Los datos de tarjeta del cliente nunca tocan tus servidores.

Crear una sesión de checkout

POST /api/v1/checkout-sessions

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
amount	integer	Sí	Monto en la unidad menor de la divisa (p. ej., 1000 = $10.00)
currency	string	Sí	ISO 4217: USD, JMD, TTD, BBD, EUR, GYD
success_url	string	Sí	URL de redirección tras pago exitoso
failure_url	string	Sí	URL de redirección tras pago fallido
cancel_url	string	No	URL de redirección para el botón de cancelar
description	string	No	Mostrado en la página de pago y el recibo
customer	object	No	{name, email}
line_items	array	No	Detalles itemizados del pedido — ver Líneas, impuestos y detalles
subtotal	integer	No	Subtotal antes de impuestos (centavos)
tax_name	string	No	Etiqueta del impuesto (GCT, VAT, Sales Tax)
tax_rate	number	No	Tasa decimal (0.15 = 15%)
tax_amount	integer	No	Monto del impuesto en centavos
metadata	object	No	Datos arbitrarios (devueltos en webhooks y al recuperar)
gateway	string	No	Slug preferido del gateway (p. ej., powertranz_direct)
expires_in_minutes	integer	No	1–1440. Predeterminado 30.

Respuesta

{
  "id": "cs_abc123def456",
  "status": "open",
  "amount": 2500,
  "currency": "USD",
  "checkout_url": "https://app.geniuscheckout.com/checkout/cs_abc123def456",
  "expires_at": "2026-05-05T12:30:00+00:00"
}

Redirige al cliente a checkout_url. Verá la página de pago con tu marca, el resumen del pedido y el formulario de tarjeta.

Recuperar una sesión de checkout

GET /api/v1/checkout-sessions/{id}

Verifica antes de cumplir

Usa este endpoint para confirmar el estado del pago tras la redirección del cliente. Nunca confíes en los parámetros de la URL — las URLs de redirección no contienen datos de pago, solo el ID de la sesión.

Respuesta

{
  "id": "cs_abc123def456",
  "status": "completed",
  "amount": 2500,
  "currency": "USD",
  "description": "Pedido #1042",
  "completed_at": "2026-05-05T12:15:00+00:00",
  "transaction": {
    "id": "txn_789xyz",
    "receipt_number": "RCT-000042",
    "status": "captured",
    "card_brand": "Visa",
    "card_last4": "0071",
    "gateway_transaction_id": "5ABCABEC-4867-410B-B76C-E85721CF859B",
    "token_id": "tok_abc123"
  }
}

Estados de sesión

Estado	Significado
open	El cliente aún no ha completado el checkout
completed	Pago capturado
failed	El pago fue intentado y rechazado
expired	La sesión pasó su expires_at sin completarse
cancelled	El cliente usó el botón de cancelar

Siguiente

• Flujo de pago — el diagrama completo desde la creación hasta el webhook
• Webhooks — la fuente autoritativa
• Tokenización y recurrencia — reutiliza el token para renovaciones