En esta guía
- Modos de captura
- Modos de cancelación
- Requisitos de configuración
- Ejemplos de solicitudes
- Cuándo usar cada modo
- Referencia de campos
Modos de captura
Yuno ofrece tres opciones para capturar pagos, determinadas por el campocapture y la configuración opcional delayed_capture_settings que se encuentran en la API de crear pago. La disponibilidad real de la función o los detalles específicos de implementación pueden variar según el proveedor de pago por el que enrutes tus pagos.
Captura en tiempo real
Este modo procesa el pago y transfiere los fondos sin ninguna demora, y combina de forma efectiva la autorización y la captura en una sola operación de compra. Cuandopayment_method.detail.card.capture se establece en true, la transacción se ejecuta como una compra, lo que significa que la autorización y la captura ocurren de forma simultánea.
Según la API del proveedor de pago, Yuno puede ejecutar esto como una única transacción de compra directa o como una autorización seguida inmediatamente por una llamada de captura.
Captura manual
Con esta configuración, Yuno no capturará el pago hasta que llames a la API de captura o lo captures manualmente en tu Dashboard de Yuno. Establececapture: false para autorizar el pago sin capturarlo.
Las capturas manuales ofrecen la máxima flexibilidad, ya que te dan control total sobre cuándo se realiza la captura. Sin embargo, es importante capturar lo antes posible, porque los proveedores de pago imponen límites de tiempo sobre cuánto puede permanecer una autorización sin capturar, y estos límites varían según el proveedor y la región.
Captura diferida
Configuracapture: false junto con delayed_capture_settings para programar la captura del pago para más adelante, según lo especificado en el campo delay.
simplified_modeEstablecer simplified_mode en true hará que Yuno reintente la operación de captura si ocurre un error durante el intento de captura programado.delay es obligatorio al usar operaciones de captura diferida y debe seguir el estándar ISO 8601. Por ejemplo:
"PT3H"para 3 horas"P7D"para 7 días"P1M"para 1 mes
Apple Pay y Google Pay
Los modos de captura anteriores también se aplican a los pagos con Apple Pay y Google Pay que Yuno descifra y procesa como pagos con tarjeta, que es como funcionan las integraciones directas de Apple Pay y Google Pay y las integraciones con SDK de ambas billeteras. El lugar donde envías el campocapture depende de cómo creas el pago:
- Integración directa por API (
workflow: "DIRECT"con el token de la billetera enpayment_method.detail.wallet.payment_token): envíacapturedentro depayment_method.detail.wallet, junto al token. - Integración con SDK (pago creado con el token de un solo uso devuelto por el SDK en
payment_method.token): envíacapturedentro depayment_method.detail.card, exactamente igual que en un pago con tarjeta. En este flujo,payment_method.detail.card.capturetiene prioridad sobre un valor decaptureenviado a nivel de la billetera.
Modos de cancelación
Cuando autorizas un pago sin capturarlo de inmediato, esos fondos quedan retenidos temporalmente en el método de pago del cliente. Si decides no capturar el pago, es importante cancelar la autorización para liberar esos fondos retenidos y ofrecer una mejor experiencia al cliente. Los modos de cancelación te dan control sobre cuándo y cómo se anulan estas autorizaciones.Cancelación manual
Con el modo de cancelación manual, los pagos autorizados permanecen activos hasta que los canceles de forma explícita. Yuno no anulará estas autorizaciones automáticamente, lo que te da control total sobre cuándo liberar los fondos. Puedes cancelar autorizaciones con la API de cancelación o desde la interfaz de tu Dashboard de Yuno. Es fundamental cancelar lo antes posible las autorizaciones que no vas a capturar, para liberar los fondos retenidos. La experiencia del cliente se ve muy afectada cuando las autorizaciones no se cancelan, ya que los fondos pueden permanecer reservados durante períodos variables según la región del cliente y la red de la tarjeta.Cancelación diferida
Configuradelayed_cancel_settings para establecer una demora al cancelar autorizaciones no capturadas, de forma similar a las capturas diferidas. Esta función automatiza la liberación de los fondos del cliente si decides no capturarlos dentro de un plazo especificado, y mejora significativamente la experiencia del cliente al evitar retenciones indefinidas en sus métodos de pago.
El campo delay es obligatorio al usar operaciones de cancelación diferida y debe seguir el estándar ISO 8601. Por ejemplo:
"PT3H"para 3 horas"P7D"para 7 días"P30D"para 30 días
simplified_modeEstablecer simplified_mode en true hará que Yuno reintente la operación de cancelación si ocurre un error durante el intento de cancelación programado.Configuración de captura y cancelación diferidasYuno recomienda no usar ambos
delayed_capture_settings y delayed_cancel_settings al mismo tiempo para evitar comportamientos inesperados. Usa solo uno a la vez según tus necesidades.Requisitos de configuración
delayed_capture_settingsydelayed_cancel_settingssolo son válidos cuandocapture = false- Si
capture = true, estos objetos deben omitirse o establecerse ennull - Las operaciones manuales se pueden realizar mediante los endpoints de la API o desde tu Dashboard de Yuno
Ejemplos de solicitudes
Ejemplo 1: Captura en tiempo real
Ejemplo 2: Solo captura manual
Ejemplo 3: Captura diferida
Ejemplo 4: Cancelación diferida
Ejemplo 5: Captura y cancelación diferidas combinadas con validación mejorada
Este ejemplo muestra una solicitud de pago completa con configuraciones de captura y cancelación diferidas, junto con campos de validación mejorada del cliente:NotaAunque este ejemplo muestra
delayed_capture_settings y delayed_cancel_settings configurados juntos, Yuno recomienda usar solo uno a la vez para evitar comportamientos inesperados.Revisa un pago antes de capturarlo
La captura manual también es la forma de aprobar cada pago tú mismo antes de que el dinero se mueva. El patrón:- Autoriza con
capture: false. Los fondos del cliente quedan reservados, no se cobran. - Ejecuta tus propias verificaciones: inventario, dirección de entrega, un equipo interno de fraude o una consulta a tu proveedor de riesgo. Si prefieres que Yuno retenga los pagos sospechosos por ti, agrega una lista de revisión o una regla con el resultado Review en la ruta; esos pagos se retienen antes de llegar al proveedor y los apruebas o rechazas desde la pestaña Held payments de Risk Conditions.
- Llama a Capture Authorization para cobrar los fondos, o a Cancel para liberarlos. Agrega
delayed_cancel_settingsal pago para que una autorización sobre la que nunca decidas se libere automáticamente.
Cuándo usar cada modo
Usa la captura en tiempo real cuando:
- Entregas bienes o servicios de inmediato
- No necesitas validar inventario ni realizar verificaciones de fraude después de la autorización
- Quieres el flujo de pago más simple
Usa la captura manual cuando:
- Necesitas verificar el inventario antes de finalizar el pago
- Quieres capturar un monto distinto al autorizado
- Tienes una lógica de negocio compleja que determina si capturar o cancelar
- Quieres aprobar cada pago tú mismo antes de cobrarle al cliente
- Necesitas el máximo control sobre el momento de la captura
Usa la captura diferida cuando:
- Quieres una captura automática después de un período específico
- Tienes un proceso de cumplimiento predecible
- Quieres reducir la intervención manual sin perder el control
Usa la cancelación diferida cuando:
- Quieres liberar automáticamente los fondos del cliente si no capturas dentro de un plazo
- Quieres mejorar la experiencia del cliente evitando retener fondos de forma indefinida
- Tienes un límite máximo de tiempo para tu proceso de cumplimiento