Skip to main content
El método card soporta credencial almacenada (mandato COF de las marcas): tu pagador guarda su tarjeta con consentimiento explícito en el primer pago y después puedes ofrecerle pagar sin re-digitar el número — o cobrarle tú suscripciones y cargos no programados sin que esté presente. El número de tarjeta jamás existe en tu integración ni en la plataforma: solo se guarda una referencia opaca del procesador más los datos de display (marca, últimos 4 dígitos, expiración).
1

Semilla: ofrece guardar la tarjeta en el primer pago

Crea el payin card con save_card: true y tu referencia del pagador:
La página hosted muestra el checkbox “Guardar esta tarjeta para futuros pagos”. La credencial se crea SOLO si el pagador lo marca y el pago 3-D Secure se aprueba. Al acreditarse recibes el webhook card_stored y la tarjeta aparece en tu listado.
2

Lista las tarjetas del pagador

3

Pago con tarjeta guardada (el pagador presente)

Crea el payin card con stored_card_id: la página salta la captura del número, muestra la tarjeta guardada (VISA •••• 2701) y el 3-D Secure corre igual — el pagador solo confirma con su banco. Los datos de facturación que el pagador ingresó al guardar la tarjeta también quedan en archivo: la página los aplica sola y muestra solo un resumen enmascarado (nombre, correo parcial y ciudad) con un enlace “usar otros datos” por si quiere cambiarlos — no se re-tipea nada. Este camino server-to-server no pide verificación adicional: tú ya conoces a tu cliente.¿No sabes qué tarjeta tiene guardada (o si tiene)? No pases stored_card_id: la página de pago le ofrece al pagador descubrir sus tarjetas verificando su correo con un código — ver el pagador descubre sus tarjetas.
4

Cobro recurrente / no programado (sin el pagador)

Cobra la tarjeta directamente — suscripciones (recurring: true) o cargos no programados acordados con tu cliente:
Respuesta 201 — el cobro aprobado acredita tu saldo automáticamente (webhook payin_credited, mismo camino que cualquier payin de tarjeta):
Un cobro declinado por el emisor responde 422 con el payin en failed y failure_reason. Un retry con la misma idempotency_key devuelve el payin original y jamás cobra dos veces.

​
Dirección de facturación en archivo (requerida para capturar)

Todo cobro MIT necesita una dirección de facturación completa del tarjetahabiente — el procesador la exige para capturar el cobro. La plataforma la toma automáticamente de los datos de facturación que el pagador ingresó al guardar la tarjeta (nombre, correo, dirección, ciudad, código postal, país y estado/región cuando el país lo exige — ver estado/región de facturación por país), así que no envías nada extra en el request.
  • Tarjetas guardadas con billing completo — operan sin cambios.
  • Tarjetas legacy sin billing completo — el cobro se rechaza con 422 core_rejected (dirección de facturación incompleta) sin mover plata. Pide al pagador guardar la tarjeta de nuevo con save_card: true (la página de pago captura la dirección completa, incluido el estado/región).
Para revocar una tarjeta guardada (a pedido del pagador o por sospecha): DELETE /v1/stored-cards/{stored_card_id} — los cobros dejan de funcionar al instante y recibes stored_card_revoked (422 stored_card_revoked si intentas cobrarla después).
Los cobros sin el pagador presente viajan sin 3-D Secure por definición del mandato: el riesgo de contracargo es tuyo. Cobra solo lo acordado explícitamente con tu cliente — la plataforma persiste la evidencia del consentimiento de la semilla (checkbox, IP y timestamp) para disputas.

​
El pagador descubre sus tarjetas en la página de pago

Toda página de pago con tarjeta — la payment_url de un payin card y la opción tarjeta del checkout universal — pide el correo del pagador como primer campo. Si ese correo tiene tarjetas guardadas contigo, la página le envía un código de verificación (con la marca de tu organización) y solo cuando lo ingresa correctamente le revela sus tarjetas: marca, últimos 4 dígitos y vencimiento, jamás el número completo. Al elegir una, paga con 3-D Secure sin re-digitarla; también puede elegir “usar otra tarjeta” y pagar con una nueva.
1

El pagador escribe su correo

Si ya lo enviaste en customer.email (o un payer_reference con correo), la página lo muestra pre-llenado. Si el correo no tiene tarjetas guardadas, el formulario de tarjeta nueva sigue su curso — no se revela nada.
2

Lo verifica con el código (una vez por dispositivo)

Con tarjetas encontradas, la página envía un código al correo y pide ingresarlo. El checkbox “Recordar este dispositivo” (marcado por defecto) deja el dispositivo confiable por 30 días: los pagos siguientes con ese correo en ese navegador muestran las tarjetas sin pedir código.
3

Elige la tarjeta y paga

Con el correo verificado, el pagador ve sus tarjetas enmascaradas, elige una y completa solo el 3-D Secure. El correo verificado queda como la identidad del pagador del cobro — gana sobre cualquier correo declarado en el formulario.
La confianza es por dispositivo y dura 30 días; cada pagador puede tener hasta 10 dispositivos recordados (al superar el tope se olvida el más antiguo). Si un pagador pierde un dispositivo, soporte puede revocar sus dispositivos recordados y volverá a recibir el código en su próximo pago.

​
Suscripciones (cobros recurrentes agendados)

Si en vez de cobrar tú manualmente cada mes quieres que la plataforma lleve el calendario, crea una suscripción sobre la tarjeta guardada: el primer período se cobra al crearla (salvo start_at futuro) y los siguientes se disparan solos según el interval.
Respuesta 201 (el first_charge aparece cuando se cobró el primer período al crear):
  • interval: daily, weekly, monthly o yearly. El día del mes se conserva y se ajusta al último día en meses cortos (un plan del 31 cobra el 28/29 de febrero y vuelve al 31 en marzo).
  • start_at (opcional, RFC3339 futuro): difiere el primer cobro (trial / fecha de inicio); sin él, cobra al crear.
  • Dunning: si el emisor declina, la plataforma reintenta cada 24 h hasta 3 veces; agotados, la suscripción pasa a past_due y recibes el webhook subscription_status_changed. resume la reactiva con un intento fresco.
  • Cada cobro exitoso acredita tu saldo como cualquier payin de tarjeta (webhook payin_credited, con subscription_id para enlazarlo al plan).
Gestión del ciclo de vida:
Revocar la tarjeta guardada (DELETE /v1/stored-cards/{id}) cancela automáticamente sus suscripciones (cancel_reason: card_revoked).

​
Estados de la suscripción

​
Errores

El catálogo general de errores vive en Errores.

​
FAQ

Jamás. Guardar una tarjeta almacena un token de red opaco — el PAN nunca toca la plataforma. Revocar la credencial invalida el token.
Las transacciones iniciadas por el comercio (MIT) corren sin 3DS por mandato de las marcas: el pagador se autenticó con 3DS en el pago inicial consentido, y cada MIT referencia esa transacción.
Se cancelan automáticamente (card_revoked). El pagador debe guardar la tarjeta de nuevo y tú creas una suscripción nueva.
No — no hay catch-up: los períodos transcurridos en pausa avanzan el contador sin cobrarse. Al reanudar se cobra solo desde el siguiente período.
El scheduler reintenta hasta 3 veces, cada 24 h. Si todas fallan el plan pasa a past_due y recibes subscription_status_changed — no hay más cobros hasta que hagas resume.
Síncrono en la creación, salvo que pases un start_at futuro (trial): ahí el primer cobro espera esa fecha.
Para mostrarle sus tarjetas guardadas sin que cualquiera que sepa su correo pueda verlas: la lista solo se revela tras verificar el correo con el código (o en un dispositivo ya recordado). Si el correo no tiene tarjetas, la página sigue directo al formulario de tarjeta nueva.
No: con “Recordar este dispositivo” (marcado por defecto) el navegador queda confiable por 30 días y los pagos siguientes con ese correo muestran las tarjetas sin código. Pasado el plazo — o en otro dispositivo — se verifica de nuevo.
Última modificación el 19 de agosto de 2026