Actualizar el split de una transacción pagada
Reemplaza el split_marketplace de una transacción que ya está pagada, antes de que el proveedor la liquide
Cuándo se acepta una actualización
- La transacción es una
PURCHASEcon estadoSUCCEEDED. - El proveedor aún lo permite: antes de la liquidación, y mientras no se alcance el límite de cambios de split por transacción del proveedor (cada actualización usa ese margen una vez por tramo). Ambas condiciones dependen del proveedor; cuando una falla recibes un
409conSPLIT_UPDATE_WINDOW_CLOSEDoSPLIT_UPDATE_LIMIT_REACHED, y el split no cambia. Yuno cuenta los cambios ya realizados y rechaza una actualización que superaría el límite antes de que llegue al proveedor. - El pago no tiene reembolso (parcial, total o uno en espera de reintento), ni contracargo ni reversión de transferencia. De lo contrario recibes un
409conSPLIT_UPDATE_NOT_ALLOWED. - El proveedor de la transacción lo admite. La actualización del split está disponible solo para las combinaciones de proveedor y método de pago que el proveedor admite, y Yuno habilita cada combinación por entorno; contacta a Yuno para habilitar la tuya. Para una combinación que no está habilitada, la solicitud devuelve
409SPLIT_UPDATE_NOT_ALLOWEDcon el mensaje “The split of this transaction cannot be updated: the provider and payment method of the transaction do not support it”, antes de enviar nada al proveedor.
recipient_id o provider_recipient_id, nunca ambos) y su monto. Los montos no deben sumar más que el monto de la transacción, en la moneda del pago.
Idempotencia
X-Idempotency-Key es obligatoria. Un timeout no es un fallo: la actualización puede haberse aplicado en el proveedor aunque no hayas recibido la respuesta. Repite la solicitud con la misma clave y el mismo cuerpo y obtendrás el resultado del primer intento, sin un segundo cambio en el proveedor: el mismo estado, y el pago tal como está en ese momento (después de una actualización posterior, el split que se muestra es el actual). La misma clave con un cuerpo distinto se rechaza con SPLIT_UPDATE_IDEMPOTENCY_CONFLICT. Si repites la solicitud mientras el primer intento sigue en curso (por ejemplo, justo después de tu propio timeout), la respuesta es 400 OPERATION_IN_PROCESS y no cambia nada: espera unos segundos y repítela de nuevo con la misma clave. Usa una clave nueva solo para un cambio nuevo.
Dónde leer el split
La respuesta es el pago, con la misma forma que Retrieve payment by ID. Lee el split entransactions.split_marketplace; el arreglo split_marketplace a nivel de pago no lo incluye. Lo mismo ocurre con cada GET /payments/{payment_id} posterior.
Cuando el proveedor no confirma
Si el proveedor no confirma el resultado (un timeout en el proveedor, o un fallo mientras reemplazaba las reglas), la respuesta es un502 con PROVIDER_ERROR y la actualización queda en revisión por parte de Yuno. No envíes una actualización nueva para esa transacción: se rechaza con 409 SPLIT_UPDATE_NOT_ALLOWED hasta que la revisión termine. Un reintento con la misma clave devuelve el mismo 502. Los reembolsos de ese pago también se rechazan hasta que la revisión termine (siguiente sección).
Reembolsos mientras hay una actualización abierta
Mientras una actualización de un pago está en curso o en revisión, los reembolsos de ese pago (incluido cancelar o reembolsar) se rechazan con400 OPERATION_IN_PROCESS, la misma respuesta que para cualquier otra operación en curso sobre el pago. En revisión, el mensaje lo indica. No se registra nada del reembolso rechazado: repítelo con la misma clave de idempotencia cuando la actualización termine. Los reembolsos solicitados en lote no se reintentan automáticamente; solicítalos de nuevo.
Códigos de respuesta
Autorizaciones
Encabezados
Obligatorio. Identificador único de esta actualización (MAX 64). Una solicitud que agota el tiempo de espera no es un fallo: repítela con la misma clave y obtendrás el resultado del primer intento. La misma clave con un cuerpo distinto se rechaza con SPLIT_UPDATE_IDEMPOTENCY_CONFLICT. Una repetición enviada mientras el primer intento sigue en ejecución recibe 400 OPERATION_IN_PROCESS y no cambia nada: espera unos segundos y vuelve a repetirla con la misma clave.
Parámetros de ruta
Cuerpo
Respuesta
El split fue reemplazado. La respuesta es el pago, con la misma forma que Obtener pago por ID; lee el nuevo split en transactions.split_marketplace.
El objeto de pago. Consulta El objeto de pago.