Conceptos

Comercio (merchant)

Tu cuenta en Seif. Está aislada del resto: tus tarjetas y transacciones viven en su propio espacio y ninguna otra cuenta puede verlas. Toda clave de API pertenece a un único comercio.

Sesión de pago (charge session)

Un objeto de corta duración que representa una intención de cobro: un monto, una moneda y, opcionalmente, tu referencia de cliente. La creas en tu servidor (POST /v1/sessions) y obtienes un checkoutUrl que abres en el navegador del comprador.

Su referencia pública empieza con cs_.
Expira a los 30 minutos. Una sesión expirada no se puede pagar — genera una nueva.

Transacción

El movimiento de dinero real. Cuando el comprador paga una sesión, se crea una transacción (referencia txn_) con el resultado del cobro.

Estados de una transacción

Estado	Significado
`pending`	Creada, aún procesándose.
`approved`	Aprobada por el banco emisor.
`declined`	Rechazada por el banco/tarjeta (fondos, CVV, vencida, etc.).
`failed`	No se pudo procesar (configuración, red o falla del procesador).
`refunded`	Reembolsada.

Un rechazo del banco (declined) llega con un mensaje limpio en español listo para mostrarle al comprador, y con el código/detalle técnico para tu depuración. Ver Errores.

Tarjeta guardada

Cuando un cobro es aprobado, Seif puede almacenar la tarjeta para volver a cobrarla luego. Guardamos únicamente:

El token de Seif (tok_seif_…) — lo único que tú manejas.
La marca (visa, mastercard, …) y los últimos 4 dígitos, para mostrar.
El vencimiento.

Nunca se almacena el PAN completo ni el CVV.

`customerRef`: identifica la tarjeta con TU id de cliente

customerRef es tu propio identificador de cliente (un id, un correo, lo que uses internamente). Lo envías al crear la sesión y la tarjeta guardada queda etiquetada con él. Así puedes recuperar las tarjetas de un cliente con tu propio id:


GET /v1/cards?customerRef=usuario_123

Token de Seif vs. tarjeta real

Tú siempre trabajas con el token de Seif (tok_seif_…). El número real de la tarjeta lo custodia el vault (VGS); Seif mantiene el mapeo internamente. Por eso nunca verás un PAN ni un identificador del vault en una respuesta de la API.

Idempotencia

Para evitar cobros duplicados (p. ej. si el comprador reintenta), cada cobro lleva una Idempotency-Key única. Si llega una segunda vez la misma clave, Seif devuelve el resultado ya guardado sin volver a cobrar. Las claves de idempotencia se conservan 24 horas.

Montos y monedas

Los montos se expresan en unidades menores (céntimos). amountMinor: 1050 = 10,50.
Moneda en formato ISO: VES o USD.

Los cobros con tarjeta se liquidan hoy en VES. Crea las sesiones de cobro en esa moneda.

Webhooks

Notificaciones en tiempo real que Seif envía a tu servidor cuando algo ocurre (un cobro aprobado, una tarjeta guardada, etc.). Ver Webhooks.