> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# 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

Los marketplaces que redistribuyen una orden después del pago (otro vendedor la entrega, se cambia un artículo) pueden reemplazar el split de una transacción pagada en lugar de reembolsar y cobrar de nuevo. La actualización reemplaza el split **completo**: los tramos que envías pasan a ser el split, y los tramos que no envías se eliminan. El pago y la transacción conservan su estado, y no se crea ninguna transacción nueva.

## Cuándo se acepta una actualización

* La transacción es una `PURCHASE` con estado `SUCCEEDED`.
* 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 `409` con `SPLIT_UPDATE_WINDOW_CLOSED` o `SPLIT_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 `409` con `SPLIT_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 `409` `SPLIT_UPDATE_NOT_ALLOWED` con 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.

Cada tramo debe indicar su destinatario (`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](https://docs.y.uno/es/reference/payments/retrieve-payment-by-id). Lee el split en `transactions.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 un `502` 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 con `400` `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

| HTTP | `code` | Significado |
| - | - | - |
| 200 | — | El split fue reemplazado. La respuesta es el pago. |
| 400 | `INVALID_PARAMETERS` | Falta un campo o es inválido: no hay clave de idempotencia, el split está vacío, un tramo sin destinatario o monto, ambos ids de destinatario en un tramo, montos superiores al monto de la transacción, otra moneda, una descripción de menos de 3 o más de 255 caracteres. |
| 400 | `PAYMENT_NOT_FOUND`, `TRANSACTION_NOT_FOUND` | No se encuentra el pago, o la transacción de ese pago, para tu cuenta. |
| 400 | `OPERATION_IN_PROCESS` | Ya hay otra operación en curso sobre el pago. Inténtalo de nuevo en unos segundos con la misma clave. |
| 404 | `RECIPIENT_NOT_FOUND` | Un `recipient_id` es desconocido, o el destinatario no tiene onboarding con el proveedor de la transacción. |
| 409 | `SPLIT_UPDATE_NOT_ALLOWED` | La transacción no es una compra exitosa, el proveedor no está habilitado, el pago tiene un reembolso (incluido uno en espera de reintento), contracargo o reversión de transferencia, o hay una actualización previa en revisión. |
| 409 | `SPLIT_UPDATE_WINDOW_CLOSED` | El proveedor ya no acepta cambios para esta transacción. El split no cambió. |
| 409 | `SPLIT_UPDATE_LIMIT_REACHED` | Se alcanzó el límite de cambios de split del proveedor para esta transacción. El split no cambió. |
| 409 | `SPLIT_UPDATE_IN_PROGRESS` | Hay otra actualización de esta transacción en curso. Inténtalo de nuevo en unos segundos. |
| 409 | `SPLIT_UPDATE_IDEMPOTENCY_CONFLICT` | La clave de idempotencia ya se usó con un cuerpo distinto. |
| 502 | `PROVIDER_ERROR` | El proveedor no confirmó el resultado; la actualización está en revisión. |


## OpenAPI

````yaml openapi/es/recipients-for-marketplace/update-split-marketplace.json PUT /payments/{payment_id}/transactions/{transaction_id}/split-marketplace
openapi: 3.1.0
info:
  title: Recipients API
  version: 1.0.0
  description: >-
    Replace the split_marketplace of a transaction that is already paid, before
    the provider settles it.
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/split-marketplace:
    put:
      summary: Actualizar el split de una transacción pagada
      description: >-
        Reemplaza todo el `split_marketplace` de una transacción de compra
        exitosa en el proveedor y en Yuno. Los tramos enviados pasan a ser el
        split; los tramos que no se envían se eliminan. El pago y la transacción
        conservan su estado; no se crea ninguna transacción nueva.


        La actualización solo se acepta mientras el proveedor todavía la
        permita: antes de la liquidación, y mientras el pago no tenga un
        reembolso (incluido uno en espera de reintento), contracargo ni
        reversión de transferencia. Mientras una actualización está en curso o
        en revisión, los reembolsos del pago se rechazan con `400`
        `OPERATION_IN_PROCESS`. La disponibilidad depende del proveedor;
        contacta a Yuno para habilitarla en tu conexión.
      operationId: update-split-marketplace
      parameters:
        - in: path
          name: payment_id
          schema:
            type: string
          required: true
          description: El identificador único del pago (MAX 64; MIN 36).
        - in: path
          name: transaction_id
          schema:
            type: string
          required: true
          description: >-
            Identificador único de la transacción de compra cuyo split se
            reemplaza (MAX 64; MIN 36).
        - in: header
          name: X-Idempotency-Key
          schema:
            type: string
          required: true
          description: >-
            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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - split_marketplace
              properties:
                split_marketplace:
                  type: array
                  minItems: 1
                  description: >-
                    El nuevo split: todos los tramos que debe tener la
                    transacción después de la actualización.
                  items:
                    properties:
                      recipient_id:
                        type: string
                        description: >-
                          Identificador único del destinatario en el sistema de
                          Yuno. Cada tramo debe indicar su destinatario con el
                          [`recipient_id`](/es/reference/recipients-for-marketplace/create-recipient-1)
                          (generado por Yuno) o con el `provider_recipient_id`
                          (ID del proveedor externo), nunca con ambos.
                      provider_recipient_id:
                        type: string
                        description: >-
                          ID del destinatario proporcionado por el proveedor de
                          pago externo. Cada tramo debe indicar su destinatario
                          con el `provider_recipient_id` o con el
                          [`recipient_id`](/es/reference/recipients-for-marketplace/create-recipient-1)
                          (generado por Yuno), nunca con ambos.
                      description:
                        type: string
                        description: Descripción del split. (MAX 255; MIN 3).
                      type:
                        type: string
                        description: >-
                          El tipo de split. `recipient_id` es obligatorio para
                          `PURCHASE` y `MARKETPLACE`.
                        enum:
                          - PURCHASE
                          - PAYMENTFEE
                          - VAT
                          - COMMISSION
                          - MARKETPLACE
                          - SHIPPING
                      merchant_reference:
                        type: string
                        description: >-
                          Identificador único opcional de la transacción de
                          split (MAX 255; MIN 3).
                      recipient_type:
                        type: string
                        description: El tipo de destinatario para el proveedor.
                        enum:
                          - MEAL
                          - FOOD
                          - MULTI_BENEFITS
                          - FLEET
                        example: MEAL
                      amount:
                        type: object
                        description: >-
                          Monto del tramo. Obligatorio en una actualización: el
                          monto de la transacción original no forma parte de
                          esta solicitud, por lo que no se calcula nada a partir
                          de una `split_configuration`.
                        required:
                          - value
                          - currency
                        properties:
                          value:
                            type: number
                            description: El monto del split (múltiplo de 0.0001).
                            format: float
                          currency:
                            type: string
                            description: >-
                              Moneda del pago (MAX 3; MIN 3; ISO 4217).
                              Opcional; cuando se omite, se usa la moneda del
                              pago. Cualquier otra moneda se rechaza.
                      liability:
                        type: object
                        description: >-
                          Información opcional sobre la responsabilidad del
                          destinatario por cargos y contracargos.
                        properties:
                          processing_fee:
                            type: string
                            description: >-
                              Indica a quién se le cobra el cargo de la
                              transacción.
                            enum:
                              - MERCHANT
                              - RECIPIENT
                              - SHARED
                          chargebacks:
                            type: boolean
                            description: >-
                              El destinatario es responsable en caso de un
                              contracargo.
                    required:
                      - type
                      - amount
                    type: object
                description:
                  type: string
                  description: Descripción de la actualización (MAX 255; MIN 3).
                metadata:
                  type: array
                  description: >-
                    Pares clave-valor personalizados almacenados con la
                    actualización.
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
            examples:
              Replace the split with one recipient:
                value:
                  split_marketplace:
                    - provider_recipient_id: 4c036fbdd2a44786815c331e9c011367
                      type: MARKETPLACE
                      amount:
                        value: 6
                        currency: BRL
                  description: Same-day split replacement
                  metadata:
                    - key: reason
                      value: same-day redistribution
      responses:
        '200':
          description: >-
            El split fue reemplazado. La respuesta es el pago, con la misma
            forma que [Obtener pago por
            ID](/es/reference/payments/retrieve-payment-by-id); lee el nuevo
            split en `transactions.split_marketplace`.
          content:
            application/json:
              schema:
                type: object
                description: >-
                  El objeto de pago. Consulta [El objeto de
                  pago](/es/reference/payments/the-payment-object).
              examples:
                Split replaced:
                  value:
                    id: d49f0691-55de-4045-a668-c17f338cd1a3
                    idempotency_key: 496E09AE-D453-491C-9179-9FC1EDEDAD02
                    origin: YUNO
                    account_code: 4be68036-738e-4841-8eb5-7a5927591a1b
                    account_id: 4be68036-738e-4841-8eb5-7a5927591a1b
                    description: pay-test purchase
                    country: BR
                    status: SUCCEEDED
                    sub_status: APPROVED
                    merchant_order_id: pt-1789681395403
                    created_at: '2026-09-17T21:43:16.119879Z'
                    updated_at: '2026-09-17T21:43:18.860706Z'
                    amount:
                      captured: 0
                      currency: BRL
                      currency_conversion: null
                      refunded: 0
                      value: 10
                    checkout:
                      session: ''
                      sdk_action_required: false
                    customer_payer: null
                    additional_data:
                      airline: null
                      transportations: null
                      lodgings: null
                      order: null
                      seller_details: null
                      device: null
                      payer_risk_data: null
                    taxes: null
                    transactions:
                      - id: 77b11fef-5c38-4ecf-9607-015594ee0bc4
                        type: PURCHASE
                        status: SUCCEEDED
                        category: CARD
                        amount: 10
                        provider_id: ZOOP
                        payment_method:
                          vaulted_token: ''
                          type: CARD
                          vault_on_success: false
                          vault_on_decline: false
                          token: ''
                          parent_payment_method_type: null
                          otp:
                            length: 0
                            retries: {}
                          detail:
                            card:
                              verify: false
                              capture: true
                              installments: 1
                              installments_plan_id: null
                              first_installment_deferral: 0
                              installments_type: ''
                              installment_amount: null
                              installments_total_amount: null
                              soft_descriptor: ''
                              authorization_code: '133937'
                              retrieval_reference_number: '20180510122911535'
                              voucher: null
                              card_data:
                                holder_name: YUNO TESTER
                                iin: '42424242'
                                lfd: '4242'
                                number_length: 16
                                security_code_length: 3
                                brand: VISA
                                scheme: VISA
                                issuer_name: STRIPE PAYMENTS UK
                                issuer_code: null
                                country_code: GB
                                category: CLASSIC
                                type: CREDIT
                                three_d_secure:
                                  version: null
                                  electronic_commerce_indicator: null
                                  cryptogram: null
                                  transaction_id: null
                                  directory_server_transaction_id: null
                                  pares_status: null
                                  acs_id: null
                                fingerprint: 4a4c0ff4-6e9e-455d-a104-3e771579a536
                                expiration_month: 3
                                expiration_year: 30
                              stored_credentials: null
                              verification_services:
                                address_line_1_check: UNCHECKED
                                zip_code_check: UNCHECKED
                                card_holder_name_check: UNCHECKED
                                card_security_code_check: UNCHECKED
                        response_code: SUCCEEDED
                        response_message: Transaction successful
                        reason: null
                        description: pay-test purchase
                        merchant_reference: pt-1789681395403
                        provider_data:
                          id: ZOOP
                          transaction_id: af8fd4e75b614591a03b2125b53907a4
                          account_id: ''
                          status: succeeded
                          sub_status: ''
                          status_detail: ''
                          response_message: null
                          response_code: '00'
                          raw_request: >-
                            "{\"payment_type\":\"credit\",\"source\":{\"card\":{\"card_number\":\"a198286a-f433-4603-842b-e7dfc2ec0801\",\"security_code\":\"e2056811-39fc-444a-a355-41aa514c277f\",\"holder_name\":\"YUNO
                            TESTER\",\"expiration_month\":\"3\",\"expiration_year\":\"2030\"},\"usage\":\"single_use\",\"amount\":1000,\"currency\":\"BRL\",\"type\":\"card\"},\"on_behalf_of\":\"4a8418ddc83f4b4fbd6f442902a4e3b3\",\"capture\":true,\"description\":\"pay-test
                            purchase\",\"reference_id\":\"77b11fef-5c38-4ecf-9607-015594ee0bc4\",\"split_rules\":[{\"recipient\":\"3258673725454c5cafaec0210674eb8d\",\"liable\":false,\"charge_processing_fee\":false,\"amount\":600}]}"
                          raw_request_details:
                            headers:
                              Authorization:
                                - '[REDACTED]'
                              X-Account-Integration-Code:
                                - '[REDACTED]'
                              X-Dynamic-Mtls:
                                - '[REDACTED]'
                              x-api-key:
                                - '[REDACTED]'
                            method: POST
                            url: >-
                              /v1/marketplaces/7fcca632f35f4efa8143238d28a89cd9/transactions
                          raw_response_details:
                            http_status_code: 201
                          third_party_transaction_id: ''
                          third_party_account_id: ''
                          iso8583_response_code: null
                          iso8583_response_message: null
                          retrieval_reference_number: null
                          merchant_advice_code: null
                          merchant_advice_code_message: null
                          reason_code: null
                          reason_description: null
                        connection_data:
                          id: 99d88722-2c77-4281-ad92-f74df11bc8b9
                          name: zoop
                        created_at: '2026-09-17T21:43:16.232391Z'
                        updated_at: '2026-09-17T21:43:18.778608Z'
                        split_marketplace:
                          - recipient_id: null
                            recipient_type: null
                            provider_recipient_id: 4c036fbdd2a44786815c331e9c011367
                            type: MARKETPLACE
                            merchant_reference: null
                            amount:
                              value: 6
                              currency: BRL
                            liability: null
                            description: null
                        merchant_advice_code: null
                        merchant_advice_code_message: null
                    split_marketplace: []
                    workflow: DIRECT
                    fraud_screening: null
                    metadata: []
                    shipping: null
                    payment_link_code: ''
                    routing_rules:
                      smart_routing: false
                      monitors: false
                      condition:
                        id: 279053
                        name: null
                        description: null
        '400':
          description: >-
            La solicitud no es válida, el pago o la transacción no se encuentra
            para tu cuenta, o todavía hay otra operación del pago en ejecución
            (`OPERATION_IN_PROCESS`, reintenta en unos segundos con la misma
            clave).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Legs above the transaction amount:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        Invalid parameters: list - [The split_marketplace
                        amounts add up to more than the transaction amount.]
                Missing idempotency key:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The header 'x-idempotency-key' is required.
                Transaction not found:
                  value:
                    code: TRANSACTION_NOT_FOUND
                    messages:
                      - Transaction of a payment not found.
                Payment not found:
                  value:
                    code: PAYMENT_NOT_FOUND
                    messages:
                      - Payment not found.
                Operation in process:
                  value:
                    code: OPERATION_IN_PROCESS
                    messages:
                      - >-
                        Operation over the same payment is already in process.
                        Try again in a few seconds.
        '404':
          description: >-
            Un `recipient_id` de la solicitud es desconocido, o no tiene
            onboarding con el proveedor de la transacción.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Recipient not found:
                  value:
                    code: RECIPIENT_NOT_FOUND
                    messages:
                      - >-
                        Recipient not found or not ready for the provider of the
                        transaction: Recipient IDs not found:
                        '11111111-2222-4333-8444-555555555555'
        '409':
          description: >-
            La actualización no es posible para esta transacción, o entra en
            conflicto con otra actualización.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Not allowed:
                  value:
                    code: SPLIT_UPDATE_NOT_ALLOWED
                    messages:
                      - >-
                        The split of this transaction cannot be updated: the
                        payment has a refund
                Window closed:
                  value:
                    code: SPLIT_UPDATE_WINDOW_CLOSED
                    messages:
                      - >-
                        The provider no longer accepts split changes for this
                        transaction. The split was not changed.
                Limit reached:
                  value:
                    code: SPLIT_UPDATE_LIMIT_REACHED
                    messages:
                      - >-
                        The provider limit of split changes for this transaction
                        was reached. The split was not changed.
                Update in progress:
                  value:
                    code: SPLIT_UPDATE_IN_PROGRESS
                    messages:
                      - >-
                        Another split update of this transaction is in progress.
                        Try again in a few seconds.
                Idempotency conflict:
                  value:
                    code: SPLIT_UPDATE_IDEMPOTENCY_CONFLICT
                    messages:
                      - >-
                        The idempotency key was already used with a different
                        split update request.
                Under review:
                  value:
                    code: SPLIT_UPDATE_NOT_ALLOWED
                    messages:
                      - >-
                        The split of this transaction cannot be updated: a
                        previous split update of this transaction is under
                        review
        '502':
          description: >-
            El proveedor no confirmó el resultado. Yuno está revisando el split;
            no reintentes con una clave nueva. Un reintento con la misma clave
            devuelve esta misma respuesta hasta que termine la revisión.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Provider error:
                  value:
                    code: PROVIDER_ERROR
                    messages:
                      - >-
                        The split update failed at the provider: the split could
                        not be confirmed and is under review
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INVALID_REQUEST
        messages:
          type: array
          items:
            type: string
            example: Invalid request
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.