Sesiones de Checkout

Una Sesión de Checkout crea una página de pago alojada en checkout.sangho.ga. Su cliente es redirigido a esa página, completa allí su pago y después es devuelto a su success_url. Usted nunca gestiona directamente los datos de pago: de eso se encarga Sangho.

Es la integración recomendada para los comercios electrónicos y las aplicaciones web: cero PCI DSS por su parte y personalizable con los colores de su marca desde su panel.

Ciclo de vida

open→processing→complete→expired / payment_failed

Estado	Significado
`open`	Sesión creada: página de pago accesible.
`processing`	Pago enviado, procesamiento en curso.
`complete`	Pago correcto: cliente redirigido a success_url.
`expired`	Sesión caducada sin pago (plazo superado o /expire/ invocado).
`payment_failed`	Intento de pago fallido: la sesión sigue abierta para reintentar.

Modos

Modo	Uso
`payment`	Pago único: flujo estándar. Crea una Intención de pago.
`subscription`	Suscripción recurrente. Crea una Subscription.
`setup`	Guardado de un método de pago sin cargo inmediato.

Endpoints

Méthode	Endpoint	Description
POST	`/checkout-sessions/`	Crear una sesión
GET	`/checkout-sessions/`	Listar las sesiones
GET	`/checkout-sessions/{id}/`	Recuperar una sesión
POST	`/checkout-sessions/{id}/expire/`	Hacer caducar manualmente una sesión

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto CheckoutSession

json

{
  "id": "sess_xxxxxxxxxxxx",
  "object": "checkout_session",
  "mode": "payment",
  "status": "open",
  "currency": "XAF",
  "amount_total": 25000,
  "amount_subtotal": 25000,
  "payment_intent": null,
  "customer": "cust_xxxxxxxx",
  "customer_email": "[email protected]",
  "url": "https://checkout.sangho.ga/c/sess_xxx",
  "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://boutique.com/panier",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Formation Excel Avancé",
      "quantity": 1,
      "unit_amount": 25000,
      "amount_total": 25000
    }
  ],
  "payment_method_types": ["mobile_money", "bank_card"],
  "expires_at": "2026-03-01T10:30:00Z",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-03-01T10:00:00Z"
}

Crear una Sesión de Checkout

Crea una sesión de pago y devuelve la URL de la página de pago alojada (url). Redirija de inmediato a su cliente a esa URL.

POSTCuerpo de la solicitud

success_urlRequis

stringURL HTTPSex :https://boutique.com/merci?session={CHECKOUT_SESSION_ID}

URL de redirección tras un pago correcto. Sangho sustituye automáticamente {CHECKOUT_SESSION_ID} por el ID de la sesión: utilícelo para verificar el pago en el servidor.

Verifique siempre en el servidor que la sesión está realmente en estado complete antes de entregar el producto o servicio. No se fíe nunca únicamente de la redirección: un usuario podría manipular la URL.

line_itemsRequis

array[object]

Líneas del pedido. Cada objeto contiene product (ID) o description + unit_amount, más quantity (entero, por defecto 1).

Para los Products de precio libre (price_type: free), debe indicar el unit_amount en la línea del pedido para sustituir el precio por defecto. Máximo 20 líneas por sesión.

currencyRequis

stringISO 4217

Código de moneda de la sesión. Todas las líneas se facturan en esta moneda.

modeOptionnel

stringdéfaut :payment

Modo de la sesión: payment, subscription o setup.

En modo subscription, la sesión crea un objeto Subscription y cobra al cliente según la recurrencia del plan. En modo setup, no se realiza ningún cargo: el método se guarda para un uso futuro.

customerOptionnel

stringcust_...

ID de un Customer existente que se asociará a la sesión. La página de pago se rellena previamente con sus datos.

Mutuamente excluyente con customer_email. Si no se indica ninguno de los dos, Sangho crea un Customer anónimo en el momento del pago si collect_customer_info: true.

customer_emailOptionnel

stringemail

Correo electrónico rellenado previamente en el formulario de la página de pago. Sangho crea o recupera automáticamente el Customer correspondiente.

cancel_urlOptionnel

stringURL HTTPS

URL de redirección si el comprador hace clic en «Cancelar» o cierra la página de pago.

Si no se indica, se muestra un botón de retorno genérico. Recomendado: apunte al carrito o a la página del producto para reducir el abandono.

payment_method_typesOptionnel

array[string]

Métodos de pago que se ofrecen en la página de checkout. Si se omite, están disponibles todos los métodos activos de la App.

expires_inOptionnel

integersegundosdéfaut :1800

Período de validez de la sesión en segundos a partir de su creación.

Mínimo: 300 segundos (5 min). Máximo: 86 400 segundos (24 h). Pasado ese plazo, la página de pago muestra un mensaje de caducidad y la sesión pasa a expired. Una sesión caducada no se puede reactivar: cree una nueva.

metadataOptionnel

object

Datos libres asociados a la sesión. Se devuelven en el webhook checkout.session.completed.

Verificación obligatoria en el servidor

Tras la redirección a success_url, llame siempre a GET /checkout-sessions/{id}/ en el servidor para confirmar que status === ‘complete’ antes de entregar su producto. No autorice nunca la entrega únicamente a partir de la redirección de URL.

¿Están claros los parámetros de la Sesión de Checkout?

Crear una sesión y redirigir

bash

curl -X POST https://api.sangho.ga/v1/checkout-sessions/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://boutique.com/panier",
    "currency": "XAF",
    "line_items": [
      { "product": "prod_xxx", "quantity": 1 },
      { "product": "prod_yyy", "quantity": 2 }
    ],
    "customer_email": "[email protected]",
    "expires_in": 3600
  }'

Response201 Created

La sesión está abierta. Redirija de inmediato a su cliente a session.url. La sesión caduca tras expires_in segundos.

json

{
  "id": "sess_xxxxxxxxxxxx",
  "object": "checkout_session",
  "status": "open",
  "currency": "XAF",
  "amount_total": 75000,
  "url": "https://checkout.sangho.ga/c/sess_xxx",
  "expires_at": "2026-03-01T11:00:00Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

ResponseSesión completa (verificación)

Llame a GET /checkout-sessions/{id}/ en el servidor tras la redirección para confirmar el pago. Entregue únicamente si status === complete.

json

{
  "id": "sess_xxxxxxxxxxxx",
  "status": "complete",
  "amount_total": 75000,
  "payment_intent": "pi_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "currency": "XAF",
  "updated_at": "2026-03-01T10:04:00Z"
}