Saltar al contenido principal
Un pago dividido permite que el comprador financie un pedido con dos tarjetas. Cada tarjeta paga su propia parte del total, tú creas un pago y recibes un resultado. El método es start en todas las plataformas. Para un pago dividido recibe un arreglo de métodos de pago en lugar de uno. El SDK crea un token compuesto, lo entrega a createPayment, ejecuta el 3DS de cada tarjeta e informa el resultado en onStatus. Para dividir un pago entre destinatarios de un marketplace, consulta en su lugar Pagos divididos para marketplace.

Disponibilidad

Antes de comenzar

  • Pide a Yuno que lo habilite. El pago dividido se habilita por cuenta. Sin esto, la solicitud del token falla con SPLIT_NOT_ENABLED.
  • Crea la sesión de checkout con el monto total. Usa el total del pedido y el workflow SDK_CHECKOUT por defecto.
  • Sobrescribe createPayment. Tú creas el pago desde tu backend. Consulta Crear el pago.
  • Recopila los datos de la tarjeta en tu propia UI. Pásalos en el objeto. El flujo no monta un formulario del SDK ni una lista de métodos de pago para las tarjetas.
  • Pasa cada monto con los decimales de su moneda. El SDK envía value tal como lo das, y el backend rechaza los decimales adicionales con AMOUNT_PRECISION.

Construir el objeto

Construyes el mismo objeto de método de pago que usa un pago con una tarjeta, una vez por tarjeta, y pasas los dos a start como un arreglo. Cada uno agrega el amount que paga esa tarjeta.

Reglas para los elementos

  • Número de elementos: dos, uno por tarjeta.
  • Orden: el primer elemento se cobra y se autentica primero, luego el segundo.
  • amount: obligatorio en cada elemento, con currency y value.
  • Datos de la tarjeta: cada elemento lleva una tarjeta o un vaulted token. El backend rechaza un elemento que no tenga ninguno o que tenga ambos.
  • La misma tarjeta dos veces: no se permite. El SDK compara los números de tarjeta y los vaulted tokens.
  • Moneda: la misma en cada elemento y la moneda de la sesión de checkout. El SDK verifica los elementos entre sí y el backend los verifica contra la sesión.
  • Suma de los montos: debe ser igual al monto de la sesión de checkout. El backend lo valida.

Ejemplo completo

Construye el objeto, inicia el pago, créalo en createPayment y recibe el resultado en onStatus. Este ejemplo divide una sesión de checkout de 300 BRL en 200 BRL con una tarjeta nueva y 100 BRL con una tarjeta guardada.

Crear el pago

El token que recibes en createPayment es un token compuesto para ambas tarjetas. Contiene token, checkout_session y expires_at. Léelo de la clave token. Desde tu backend, envíalo a POST /v2/payments con workflow: "SDK_CHECKOUT", como payment_method.token.
POST /v1/payments rechaza un token compuesto. Usa POST /v2/payments.
La solicitud, sus campos y la respuesta están en Pagar con dos tarjetas, en el ejemplo de SDK_CHECKOUT, y en la referencia Create Payment (two cards).

Recibir el resultado

Recibes el resultado en onStatus, a nivel de pago. No hay un callback por tarjeta. El SDK procesa la tarjeta 1 y luego la tarjeta 2. Si la tarjeta 1 falla, la tarjeta 2 no se inicia y onStatus informa el estado del pago. Si la tarjeta 2 falla después de que la tarjeta 1 fue autorizada, lo que ocurre con la tarjeta 1 se gestiona en el backend. La respuesta del pago en tu servidor muestra el estado final de cada tarjeta: consulta Pagar con dos tarjetas. En iOS, y también desde React Native, onStatus puede informar primero un PENDING no final, como en cualquier pago. Consulta onStatus y confirma el resultado en tu servidor antes de cumplir el pedido.

Errores

Validaciones del SDK

El SDK verifica la forma del arreglo antes de solicitar el token, por lo que un arreglo inválido no envía ninguna solicitud. El código es INVALID_SPLIT_PAYMENT y el mensaje está en inglés. El mensaje es para tus desarrolladores: no se lo muestres al comprador. El SDK verifica, en este orden, que:
  • El arreglo tenga dos elementos.
  • Cada elemento tenga un amount con un value mayor que 0 y un currency.
  • Cada elemento tenga la misma moneda que el primero.
  • Ninguna tarjeta ni vaulted token aparezca dos veces.
El mensaje nombra el elemento que falló. Todo lo demás, como el tipo de método de pago, un elemento sin tarjeta ni vaulted token, la suma de los montos y la moneda de la sesión, lo valida el backend con los códigos de Errores del backend.

Dónde no está disponible el arreglo

El arreglo es para transacciones de pago. En una transacción de inscripción (customerSession):

Errores del backend

El backend valida la solicitud del token compuesto. Cuando rechaza la solicitud, onStatus recibe status: "INTERNAL_ERROR" con message.source backend y ningún token llega a createPayment.