Saltar al contenido principal
Un pago con dos tarjetas es un pago financiado por exactamente dos tarjetas. Cada tarjeta paga su propia parte del monto, y las dos partes suman el monto del pago. Tu cliente paga un pedido y tú concilias un solo pago. Úsalo cuando un cliente quiera dividir un pedido entre dos tarjetas, por ejemplo porque una tarjeta no tiene límite suficiente para todo el pedido.

Límites

  • Exactamente dos tarjetas, ambas con type: CARD.
  • Una sola moneda: los montos de ambas tarjetas usan la moneda del pago.
  • split_marketplace, external_subscription y amount.currency_conversion no están permitidos, y no se aceptan cotizaciones de promociones (consulta Promociones).
  • Todo o nada: ambas tarjetas son exitosas o el pago falla. Consulta Todo o nada.
  • payment_method.capture es compartido por ambas tarjetas.

Habilitación

En producción, los pagos con dos tarjetas se habilitan por organización. Hasta que Yuno los habilite, POST /v2/payments responde:
con el código de estado HTTP 403. Contacta a tu Key Account Manager para habilitarlo. En sandbox, los pagos con dos tarjetas están habilitados para todas las organizaciones.

Crear el pago

Envía POST /v2/payments (https://api-sandbox.y.uno/v2/payments en sandbox, https://api.y.uno/v2/payments en producción) con los mismos encabezados public-api-key y private-secret-key que los endpoints v1. El encabezado X-Idempotency-Key es obligatorio en esta solicitud y en cada operación v2; sin él, la solicitud se rechaza con 400 y el mensaje The header 'x-idempotency-key' is required.
En la ruta del SDK, crea el token compuesto con generateToken en el SDK Web headless. El token incluye ambas tarjetas y sus montos. En el Yuno SDK, pasa un arreglo a start(): consulta Divide un pago entre dos tarjetas. Consulta la referencia completa en Create Payment (two cards).

Leer la respuesta

La solicitud de creación y Retrieve Payment (two cards) devuelven la misma estructura:
  • split_payment_methods es true y payment_methods_count es 2.
  • payment_method.payment_methods tiene una entrada por tarjeta, con su sequence (1 o 2), type, amount (currency y value) y transactions.
  • Una tarjeta no tiene estado propio. Lee el resultado de cada tarjeta en sus transactions: la última transacción de la tarjeta y su status indican qué ocurrió con esa tarjeta. Una tarjeta que pasó por 3DS muestra THREE_D_SECURE seguido de PURCHASE (o AUTHORIZE cuando capture es false).
  • Lee el resultado del pago en el status y el sub_status a nivel de pago. Cuando sdk_action_required es true, el SDK tiene que continuar el pago, por ejemplo para ejecutar un desafío 3DS.

Estados

Yuno resume ambas tarjetas en el status y el sub_status del pago. Gana la primera regla que coincide: Consulta Estado del pago para ver todos los estados y subestados.

Todo o nada

Ambas tarjetas son exitosas o el pago falla. Si una tarjeta falla (rechazada, con error o por fraude), Yuno revierte la otra tarjeta antes de responder a la solicitud de creación, de modo que la respuesta ya muestra el resultado final:
  • Una tarjeta que fue cobrada (PURCHASE, o capturada) se reembolsa.
  • Una tarjeta que solo fue autorizada se cancela.
  • Una tarjeta a la espera de 3DS es cerrada por Yuno, sin llamar al proveedor.
Si una reversión falla, el pago permanece en DECLINED con el subestado REFUND_RETRY_IN_PROCESS o CANCEL_RETRY_IN_PROCESS, y Yuno reintenta la reversión automáticamente. Mientras el pago esté en uno de estos subestados, la captura y la cancelación se rechazan.
No pidas a tu cliente que continúe con la tarjeta restante después de un fallo. Inicia un nuevo pago en su lugar.

Filtro de fraude

  • El rechazo de una tarjeta antes de la autorización rechaza el pago (DECLINED / FRAUD_DECLINED), y Yuno cierra la otra tarjeta.
  • Un rechazo después de la autorización revierte ambas tarjetas.

Operaciones

La captura, la cancelación y el reembolso se hacen por tarjeta: envía el id de la transacción de la tarjeta, que está en payment_method.payment_methods[].transactions. Cada operación responde 201 con el pago en la misma estructura v2 y requiere un X-Idempotency-Key.
  • Un reembolso en una tarjeta está limitado al monto de esa tarjeta menos lo que ya se reembolsó en ella.
  • El cancel-or-refund a nivel de pago acepta un amount opcional. Yuno lo reparte entre las tarjetas, empezando por la tarjeta con el mayor monto reembolsable. Un amount superior al total reembolsable se rechaza.
  • Mientras una tarjeta tenga un contracargo abierto, los reembolsos se rechazan con INVALID_STATUS.

Webhook

El webhook del pago tiene el mismo payload que para los pagos v1, más:
  • split_payment_methods y payment_methods_count.
  • payment_method.capture.
  • payment_method.payment_methods[], con sequence, type, amount y transactions para cada tarjeta.
Tampoco hay un estado por tarjeta en el webhook: lee el resultado de cada tarjeta en sus transacciones. Consulta Configurar webhooks.

Errores

Los errores son 400 INVALID_PARAMETERS salvo que se indique otra cosa. El arreglo messages lista cada problema encontrado en la solicitud.