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_…. Es de corta duración (actualmente ~5 minutos): créala justo antes de cobrar y usa expiresAt para el momento exacto de expiración.

Crear una sesión

POST /v1/sessions

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

Cuerpo

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"
}

Cobrar una tarjeta guardada (solo CVV)

Cuando tu cliente ya tiene una tarjeta guardada, no vuelvas a pedirle el número. Crea la sesión con el cardToken de esa tarjeta y el checkout mostrará únicamente:

• la tarjeta con la que va a pagar (marca y últimos 4 dígitos),
• el campo CVV,
• su documento de identidad.

El número y el vencimiento salen de la bóveda del lado de Seif. Tu servidor nunca toca datos de tarjeta, así que el flujo es 100 % PCI para ti.

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",
    "cardToken": "tok_seif_Xa92...kQ",
    "description": "Pedido #1043"
  }'

La respuesta es idéntica a la de cualquier sesión: abre el checkoutUrl (o móntalo con seif-js) y el comprador solo confirma su CVV.

Errores propios de este flujo

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

failed significa que un cobro falló pero la sesión sigue viva y se puede reintentar. Una sesión cerrada —por tiempo o por agotar sus intentos— siempre se reporta como expired.

Limitar los intentos

Por defecto una sesión se puede reintentar libremente hasta que expire. Si un cobro es rechazado, el comprador puede corregir los datos o probar otra tarjeta. Eso funciona bien para la mayoría, pero no para todos: hay integraciones que necesitan un número fijo de intentos y una respuesta definitiva, para que su propio sistema deje de esperar.

Para eso está maxFailures.

{
  "amountMinor": 105000,
  "currency": "VES",
  "maxFailures": 0
}

Qué significa el número

maxFailures es cuántos fallos tolera la sesión, no cuántos intentos concede. El intento que rompe el límite también cuenta, así que el total de intentos es maxFailures + 1.

Qué cuenta como fallo

Cualquier intento que termine en error. No distinguimos entre un rechazo del banco y un dato mal escrito: si el cobro no salió, gastó un intento.

• Rechazado por el banco emisor — cuenta.
• Fallido en el procesador — cuenta.
• Datos inválidos (400: falta el documento, falta el nombre del titular) — cuenta.

No consumen intentos las peticiones que nunca llegaron a ser un intento:

• Una sesión ya cerrada, expirada o con un cobro en curso (409 / 410).
• Los OTP incorrectos, que tienen su propio límite independiente.

Cómo se cierra

Una sesión ahora puede terminar de dos maneras: por tiempo (expiresAt) o por fallos (maxFailures). La que ocurra primero.

Se cierre como se cierre, el resultado es el mismo:

• Su estado pasa a expired y attemptsRemaining queda en 0.
• El checkout muestra la pantalla de sesión expirada, sin botón de reintento.
• Un nuevo intento de cobro devuelve 409.
• Se emite el webhook session.expired, con el mismo formato en ambos casos. El campo reason dice de qué manera murió.

{
  "event": "session.expired",
  "data": {
    "sessionReference": "cs_8sKd2pQ1Aa",
    "reason": "max_failures_reached",
    "failureCount": 1,
    "maxFailures": 0
  }
}

En el checkout

Al comprador se le avisa cuando le queda un solo intento, para que no lo gaste reintentando la misma tarjeta. Antes de eso no se le dice nada: mostrar un contador desde el principio agrega presión sin cambiar nada.

Cerrar y volver a cobrar

Una sesión cerrada no se reabre. Si quieres darle otra oportunidad al comprador, crea una sesión nueva. Es deliberado: el sentido de maxFailures es que la decisión de reintentar sea tuya y explícita, no del comprador.

Errores