Tarjetas guardadas

Cuando un cobro es aprobado, Seif puede almacenar la tarjeta para volver a cobrarla luego. Cada tarjeta se identifica con un token de Seif (tok_seif_…) y, si lo enviaste, con tu customerRef.

Listar tarjetas

GET /v1/cards

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

Parámetros de consulta

Ejemplo

curl "https://api.seif.pagosripei.com/v1/cards?customerRef=usuario_123" \
  -H "Authorization: Bearer sk_test_tu_clave"

Respuesta 200

[
  {
    "id": "c0a2...-9f",
    "seifToken": "tok_seif_Xa92...kQ",
    "brand": "visa",
    "lastFour": "4242",
    "expMonth": 8,
    "expYear": 2028,
    "holderName": null,
    "status": "active",
    "customerRef": "usuario_123",
    "createdAt": "2026-06-09T18:05:10.000Z"
  }
]

¿Cómo asocio una tarjeta a uno de mis usuarios?

Usa customerRef — es tu identificador, el que ya usas en tu sistema (un id, un correo, un uuid). El flujo:

1. Tu cliente inicia un pago → creas la sesión con "customerRef": "usuario_123".
2. El cobro se aprueba → la tarjeta se guarda etiquetada con usuario_123.
3. Más tarde recuperas sus tarjetas: GET /v1/cards?customerRef=usuario_123.

Así un mismo cliente puede tener varias tarjetas, y tú las identificas con tus propios ids — sin manejar nunca datos sensibles.

Volver a cobrar una tarjeta guardada

Este es el segundo pago: tu cliente ya pagó una vez, la tarjeta quedó guardada y ahora quieres cobrarle de nuevo sin pedirle todos los datos otra vez.

Se hace con el mismo endpoint de siempre — POST /v1/sessions — agregando el cardToken. Seif reconoce que la sesión ya tiene tarjeta y el checkout pide solo el CVV.

El flujo completo

1. Recupera las tarjetas de tu cliente

curl "https://api.seif.pagosripei.com/v1/cards?customerRef=usuario_123" \
  -H "Authorization: Bearer sk_test_tu_clave"

2. Crea la sesión con el seifToken de la tarjeta elegida

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

3. Abre el checkout con el checkoutUrl de la respuesta

Exactamente igual que en un pago normal — redirección o iframe (ver Checkout incrustado):

window.location.href = session.checkoutUrl;

El comprador ve Visa •••• 4242, escribe su CVV y confirma. El resto (webhooks, estados, reintentos) es idéntico al primer pago.

¿Por qué este flujo es 100 % PCI para ti?

En ningún momento tu servidor recibe, guarda ni reenvía datos de tarjeta: solo tokens.

Eliminar una tarjeta

DELETE /v1/cards/{seifToken}

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

Marca la tarjeta como deleted: deja de poder cobrarse de inmediato. Es un borrado lógico — el registro se conserva porque las transacciones pasadas lo referencian. La operación es idempotente: eliminar una tarjeta ya eliminada devuelve la misma tarjeta, sin volver a notificar.

Ejemplo

curl -X DELETE "https://api.seif.pagosripei.com/v1/cards/tok_seif_Xa92...kQ" \
  -H "Authorization: Bearer sk_test_tu_clave"

Respuesta 200

{
  "id": "c0a2...-9f",
  "seifToken": "tok_seif_Xa92...kQ",
  "brand": "visa",
  "lastFour": "4242",
  "status": "deleted",
  "customerRef": "usuario_123",
  "createdAt": "2026-06-09T18:05:10.000Z"
}

Al eliminarse se emite el webhook card.deleted (ver Webhooks). Requiere un rol con permiso de escritura (no disponible para usuarios de solo lectura).

Notas

• El CVV no se almacena (por diseño es de un solo uso). Por eso, al volver a cobrar una tarjeta guardada, el comprador lo reingresa en el checkout.
• Tarjetas repetidas se deduplican: si el mismo cliente paga dos veces con la misma tarjeta, se reutiliza un único registro.