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_subscriptionyamount.currency_conversionno 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.capturees 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:
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íaPOST /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.
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_methodsestrueypayment_methods_countes2.payment_method.payment_methodstiene una entrada por tarjeta, con susequence(1o2),type,amount(currencyyvalue) ytransactions.- Una tarjeta no tiene estado propio. Lee el resultado de cada tarjeta en sus
transactions: la última transacción de la tarjeta y sustatusindican qué ocurrió con esa tarjeta. Una tarjeta que pasó por 3DS muestraTHREE_D_SECUREseguido dePURCHASE(oAUTHORIZEcuandocaptureesfalse). - Lee el resultado del pago en el
statusy elsub_statusa nivel de pago. Cuandosdk_action_requiredestrue, el SDK tiene que continuar el pago, por ejemplo para ejecutar un desafío 3DS.
Estados
Yuno resume ambas tarjetas en elstatus 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.
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.
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 elid 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-refunda nivel de pago acepta unamountopcional. Yuno lo reparte entre las tarjetas, empezando por la tarjeta con el mayor monto reembolsable. Unamountsuperior 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_methodsypayment_methods_count.payment_method.capture.payment_method.payment_methods[], consequence,type,amountytransactionspara cada tarjeta.
Errores
Los errores son400 INVALID_PARAMETERS salvo que se indique otra cosa. El arreglo messages lista cada problema encontrado en la solicitud.