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: 5 minutos por defecto, o lo que indiques en expiresInMinutes (ver Duración de la sesión). 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"
}

Duración de la sesión

Una sesión dura 5 minutos por defecto. Si tu flujo necesita otra cosa, envía expiresInMinutes al crearla: entre 2 y 60 minutos, en minutos enteros.

{
  "amountMinor": 105000,
  "currency": "VES",
  "expiresInMinutes": 15
}

• Más tiempo sirve si tus compradores tardan en tener la tarjeta a mano.
• Menos tiempo sirve si necesitas liberar pronto lo que la sesión reserva (un cupo, una entrada).

La respuesta trae el expiresAt resultante, y todo lo demás sigue igual: la sesión se cierra sola a esa hora y se emite session.expired. Un valor fuera de rango se rechaza con 400; no se recorta.

Rellenar el formulario (prefill)

Si ya tienes los datos del comprador en tu sistema, no hace falta que los escriba otra vez. Envía prefill al crear la sesión y el checkout abre con esos campos ya puestos.

{
  "amountMinor": 105000,
  "currency": "VES",
  "prefill": {
    "cardholderName": "María Rodríguez",
    "documentType": "V",
    "documentId": "12345678"
  }
}

Campos

Qué hacemos con lo que envías

Antes de guardarlo, normalizamos los valores. Es útil conocerlo porque la respuesta te devuelve el resultado, no lo que enviaste:

• Los separadores del documento se eliminan. "12.345.678" se guarda como "12345678", y un pasaporte se guarda en mayúsculas.
• Los espacios de más se colapsan y se recorta el nombre.
• Los caracteres invisibles y de control se eliminan (saltos de línea, espacios de ancho cero, marcas de dirección de texto). Un nombre que quede vacío tras esa limpieza se rechaza con 400.
• El límite de 80 caracteres se aplica después de limpiar.

Es un prellenado, no una imposición

Esto es lo más importante de la funcionalidad:

• El comprador puede editar los tres campos. Nada queda bloqueado.
• El cobro se procesa con lo que el comprador envió, no con lo que tú prellenaste. Si lo corrige, vale su corrección.
• Si necesitas saber con qué documento se cobró finalmente, léelo de la transacción, no de la sesión.

Lo ya guardado tiene prioridad

Si la sesión usa una tarjeta guardada (cardToken) y esa tarjeta ya tiene titular o documento, lo guardado gana y tu prellenado se ignora. No es un error: la sesión se crea igual, simplemente ese campo no se prellena porque ni siquiera se le pregunta al comprador.

La regla se aplica campo por campo:

Por eso prefill rinde sobre todo en el primer cobro, cuando la tarjeta todavía no existe en Seif. A partir del segundo, la tarjeta ya trae sus datos y no hay nada que prellenar.

Errores propios de este flujo

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.

Expirar una sesión

POST /v1/sessions/{reference}/expire

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

Cierra la sesión ya, antes de que se le acabe el tiempo o los intentos. Úsalo cuando el pedido deja de existir: se agotó, el cliente pagó por otra vía o lo anulaste. Desde ese momento la sesión ya no se puede pagar: si el comprador intenta pagar, el checkout le muestra la pantalla de sesión expirada.

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

Respuesta 200

El mismo objeto de la sesión, ya cerrada:

{
  "reference": "cs_8sKd2pQ1Aa",
  "status": "expired",
  "closedReason": "merchant_request",
  "expiresAt": "2026-06-09T18:30:00.000Z",
  "...": "…"
}

• status pasa a expired y closedReason a merchant_request. expiresAt no cambia: sigue diciendo cuándo iba a vencer.
• Se emite el webhook session.expired, con el mismo formato de siempre y reason: "merchant_request".
• Si la sesión ya había vencido por tiempo, pero todavía no se había marcado, se cierra con closedReason: "expired": es lo que de verdad le pasó.

Puedes repetir la llamada sin problema. Si la sesión ya estaba cerrada (por tiempo, por intentos o por una llamada anterior), responde 200 con su estado actual y no emite otro webhook.

Cuándo no se puede

Listar sesiones

GET /v1/sessions

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

Devuelve tus sesiones, de la más reciente a la más antigua, con cuántos intentos de cobro generó cada una. Sirve para revisar qué pasó con tus cobros: cuáles se pagaron, cuáles se rechazaron y cuáles nadie llegó a intentar.

Parámetros (query)

curl "https://api.seif.pagosripei.com/v1/sessions?status=expired&page=1&pageSize=20" \
  -H "Authorization: Bearer sk_test_tu_clave"

Respuesta 200

{
  "data": [
    {
      "reference": "cs_8sKd2pQ1Aa",
      "status": "expired",
      "closedReason": "max_failures_reached",
      "amountMinor": 105000,
      "currency": "VES",
      "description": "Pedido #1042",
      "customerRef": "usuario_123",
      "createdAt": "2026-06-09T18:25:00.000Z",
      "expiresAt": "2026-06-09T18:30:00.000Z",
      "attemptCount": 1,
      "attemptsRemaining": 0,
      "lastTransaction": { "reference": "txn_…", "status": "declined" }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Estados de una sesión

El listado y el detalle devuelven siempre el mismo estado para la misma sesión.

Una sesión pasa a expired en cuanto llega expiresAt, sin que nadie tenga que volver a abrirla. La única excepción es una sesión con un cobro en curso (processing, otp_requested, otp_confirmed): vencer no corta un cobro que ya salió hacia el banco. Si ese cobro se rechaza, la sesión se cierra entonces. La misma regla aplica si la expiras tú: con un cobro en curso, la llamada responde 409.

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 puede terminar sin pagarse de tres maneras: por tiempo (expiresAt), por fallos (maxFailures) o porque la expiraste tú (POST /v1/sessions/{reference}/expire). La que ocurra primero.

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

• Su estado pasa a expired, y closedReason dice de qué manera murió.
• El checkout muestra la pantalla de sesión expirada, sin botón de reintento.
• Un nuevo intento de cobro se rechaza: 410 si venció o la expiraste tú, 409 si agotó sus intentos.
• Se emite el webhook session.expired, con el mismo formato en los tres casos. El campo reason dice de qué manera murió.

El webhook por tiempo sale al vencer la sesión, con unos segundos de margen, aunque el comprador haya cerrado la página y nadie la vuelva a abrir.

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