Checkout Sessions

Una CheckoutSession representa un cobro que el comprador completa en una página hospedada por INGALCA. Ver la guía: Checkout hospedado.

El objeto CheckoutSession

{
  "id": "cs_9f3a2b1c...",
  "url": "https://api.pay.ingalca.com/v1/checkout/cs_9f3a2b1c...",
  "status": "open",
  "reference": "ORDEN-1042",
  "environment": "test",
  "amount": "110000.00",
  "currency": "PYG",
  "methods": ["dinelco", "transferencia"],
  "description": "Entradas Torneopolis",
  "line_items": [
    { "name": "Entrada General", "quantity": 2, "unit_amount": 50000 }
  ],
  "success_url": "https://tuweb.com/gracias",
  "cancel_url": "https://tuweb.com/carrito",
  "metadata": { "order_id": 1042 },
  "expires_at": "2026-08-04T16:00:00+00:00",
  "created_at": "2026-08-04T15:00:00+00:00"
}

Solo se obtiene en la respuesta del POST: no existe GET /v1/checkout-sessions/{id} ni un listado. Guardá el id cuando creás la sesión. Para consultar el estado del cobro, mirá los Payments ligados a ella o esperá el webhook.

Estados (status)

Estado	Significado
open	Esperando que el comprador pague.
completed	Un pago de la sesión se confirmó. La página deja de aceptar pagos.
expired	Venció (expires_at) sin pago confirmado.
cancelled	Reservado. Hoy ninguna operación deja una sesión en este estado (no hay endpoint de cancelación).

Crear una sesión

POST /v1/checkout-sessions — ver el detalle de campos y ejemplo en la guía.

Respuesta 201 en creación, 200 en replay idempotente.

Idempotencia

Reenviar el mismo reference (por tenant + environment) devuelve la sesión existente con 200 mientras esa sesión siga open y sin vencer. Si ya venció, se completó o se cerró, se crea una sesión nueva con 201 — que es lo que querés: el comprador vuelve a intentar sobre una URL viva.

No hay 409 acá, a diferencia de /v1/payments

En payments reusar un reference con otro amount devuelve 409 REFERENCE_ALREADY_USED. En checkout sessions no: mientras la sesión siga abierta, te devolvemos la sesión vieja con el monto viejo, en silencio.

Si el total de la orden puede cambiar (agregó un ítem, cambió el envío), usá un reference nuevo o esperá a que la sesión anterior venza. Si no, vas a cobrar el importe equivocado.

La página hospedada

GET /v1/checkout/{id} es la página que ve el comprador (no una API JSON). Redirigí su browser ahí usando el campo url. Es pública: la autoriza el id de la sesión mientras esté open y no vencida.

Una vez completed / expired / cancelled responde 410 con una página que le explica al comprador qué pasó y lo devuelve a tu cancel_url (o success_url si la sesión se completó). Ver Expiración.

Relación con Payment

Cuando el comprador elige un método, se crea un Payment ligado a la sesión. En el webhook y en el objeto Payment, el reference es el de la sesión (tu orden), y aparece checkout_session_id. Una sesión puede tener varios intentos (cada uno su payment_id); conciliá por reference y deduplicá por X-Ingalca-Event-Id.