Sesiones de pago

Una sesión de pago representa una intención de cobro. La creas en tu servidor y obtienes un checkoutUrl para cobrar al comprador. Referencia pública: cs_…. Expira a los 30 minutos.

Crear una sesión


POST /v1/sessions

Autenticación: clave secreta (Authorization: Bearer sk_…).

Cuerpo

Campo	Tipo	Requerido	Descripción
`amountMinor`	entero	Sí	Monto en unidades menores (céntimos). Mínimo `1`.
`currency`	string	Sí	`VES` o `USD`. Hoy el cobro con tarjeta se liquida en `VES`.
`customerRef`	string	No	Tu id de cliente. La tarjeta guardada quedará asociada a él. Máx. 120.
`returnUrl`	string (URL)	No	A dónde redirigir al comprador tras un cobro aprobado.
`description`	string	No	Texto corto mostrado en el checkout. Máx. 140.

Ejemplo


curl -X POST https://api.seif.pagosripei.com/v1/sessions \
  -H "Authorization: Bearer sk_test_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "amountMinor": 105000,
    "currency": "VES",
    "customerRef": "usuario_123",
    "description": "Pedido #1042",
    "returnUrl": "https://mitienda.com/gracias"
  }'

Respuesta `201`


{
  "id": "9f0c1f2a-...-e3",
  "reference": "cs_8sKd2pQ1Aa",
  "status": "created",
  "amountMinor": 105000,
  "currency": "VES",
  "expiresAt": "2026-06-09T18:30:00.000Z",
  "checkoutUrl": "https://checkout.seif.pagosripei.com/checkout?session=cs_8sKd2pQ1Aa",
  "description": "Pedido #1042"
}

Campo	Descripción
`reference`	Referencia pública de la sesión (`cs_…`).
`status`	Estado de la sesión (ver abajo).
`checkoutUrl`	URL para abrir el checkout incrustado.
`expiresAt`	Cuándo expira (ISO-8601).

Consultar una sesión


GET /v1/sessions/{reference}


curl https://api.seif.pagosripei.com/v1/sessions/cs_8sKd2pQ1Aa \
  -H "Authorization: Bearer sk_test_tu_clave"

Devuelve el mismo objeto, con el status actualizado.

Estados de una sesión

Estado	Significado
`created`	Lista para cobrar.
`processing`	El comprador inició el pago.
`completed`	Pagada con éxito.
`failed`	El cobro falló o fue rechazado.
`expired`	Pasaron los 30 minutos sin pagarse.
`canceled`	Cancelada.

Errores

HTTP	Causa	Solución
`400`	Falta `amountMinor`/`currency`, o `amountMinor < 1`, o `returnUrl` no es una URL válida.	Revisa el cuerpo según la tabla de campos.
`401`	Clave secreta inválida o ausente.	Verifica el header `Authorization`.
`404`	La sesión consultada no existe.	Revisa la `reference`.
`409`	El comercio aún no está aprovisionado.	Contacta a soporte para activar tu comercio.

La sesión es de un solo uso. Una vez completed (o expired), genera una nueva para un nuevo cobro.