Crear una sesión de checkout

post/v1/checkout/sessions

Crea una sesión de checkout embebido. Llamala desde tu server con sk_. Devuelve un client_secret (una sola vez) que pasás al drop-in @cauril/checkout-js en el browser para cobrar sin tocar datos de tarjeta (PCI SAQ-A). Requiere el header Idempotency-Key.

Request

BASH

curl -X POST https://api.cauril.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "success_url": "string",
    "cancel_url": "string",
    "allowed_methods": [
      "card"
    ],
    "return_url": "string",
    "customer_email": "string",
    "locale": "es",
    "provider": "stripe",
    "routing_hint": {
      "country": "BR"
    },
    "appearance": {},
    "metadata": {}
  }'

Parámetros

Idempotency-Keyheaderreq

string

Clave única por operación (ej. un UUID). Reintentar con la misma key replica la respuesta original.

Cuerpo CreateCheckoutSession

amountreq	Money
currencyreq	Currency
success_urlreq	string · uri	A dónde vuelve el comprador tras pagar. Debe estar en el allowlist de redirección de la organización.
cancel_urlreq	string · uri	A dónde vuelve el comprador si cancela.
allowed_methods	arraynull	Métodos a ofrecer. Si se omite, se usan los del PSP resuelto.
return_url	string · uri
customer_email	string · email
locale	string
provider	string	Forzar un PSP. Si se omite, se resuelve por routing (con `routing_hint`).
routing_hint	object	Pistas para resolver el PSP (ej. país del comprador).
appearance	object	Estilo del drop-in (colores, bordes).
metadata	object

Respuestas

201	Sesión creada (incluye `client_secret`)	CheckoutSession
400	Error	Error
401	Error	Error
409	Error	Error
422	Error	Error

Ejemplo de respuesta · 201

JSON

{
  "object": "checkout.session",
  "id": "cs_01J...",
  "status": "open",
  "amount": 5000,
  "currency": "USD",
  "client_secret": "cs_01J..._secret_aGVsbG8",
  "ui": {
    "provider": "stripe",
    "publishable_key": null,
    "methods": [
      "card"
    ]
  },
  "allowed_methods": null,
  "success_url": "string",
  "cancel_url": "string",
  "return_url": null,
  "locale": null,
  "customer_email": null,
  "metadata": {},
  "payment_id": null,
  "payment": null,
  "expires_at": "2026-06-01T12:00:00Z",
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z",
  "livemode": true
}