> ## 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. # Update the split of a paid transaction > Replace the split_marketplace of a transaction that is already paid, before the provider settles it Marketplaces that redistribute an order after payment (a different seller delivers, an item is swapped) can replace the split of a paid transaction instead of refunding and charging again. The update replaces the **whole** split: the legs you send become the split, and legs you do not send are removed. The payment and the transaction keep their status, and no new transaction is created. ## When an update is accepted * The transaction is a `PURCHASE` with status `SUCCEEDED`. * The provider still allows it: before settlement, and while the provider's limit of split changes per transaction is not reached (each update uses that allowance once per leg). Both conditions belong to the provider; when one fails you get a `409` with `SPLIT_UPDATE_WINDOW_CLOSED` or `SPLIT_UPDATE_LIMIT_REACHED`, and the split is not changed. Yuno counts the changes already made and refuses an update that would pass the limit before it reaches the provider. * The payment has no refund (partial, total, or one waiting to be retried), no chargeback and no transfer reversal. Otherwise you get a `409` with `SPLIT_UPDATE_NOT_ALLOWED`. * The provider of the transaction supports it. Availability is enabled per connection; contact Yuno to enable it for yours. Every leg must name its recipient (`recipient_id` or `provider_recipient_id`, never both) and its amount. The amounts must not add up to more than the transaction amount, in the currency of the payment. ## Idempotency `X-Idempotency-Key` is required. **A timeout is not a failure**: the update may have been applied at the provider even if you did not get the answer. Repeat the request with the **same key and the same body** and you get the outcome of the first attempt, without a second change at the provider: the same status, and the payment as it is at that moment (after a later update, the split shown is the current one). The same key with a different body is refused with `SPLIT_UPDATE_IDEMPOTENCY_CONFLICT`. If you repeat the request while the first attempt is still running (for example right after your own timeout), the answer is `400` `OPERATION_IN_PROCESS` and nothing changes: wait a few seconds and repeat it again with the same key. Use a new key only for a new change. ## Where to read the split The answer is the payment, in the same shape as [Retrieve payment by ID](/reference/retrieve-payment-by-id). Read the split on `transactions.split_marketplace`; the payment-level `split_marketplace` array does not carry it. The same is true of every later `GET /payments/{payment_id}`. ## When the provider does not confirm If the provider does not confirm the outcome (a timeout at the provider, or a failure while it replaced the rules), the answer is a `502` with `PROVIDER_ERROR` and the update stays **under review** by Yuno. Do not send a new update for that transaction: it is refused with `409` `SPLIT_UPDATE_NOT_ALLOWED` until the review is complete. A retry with the same key returns the same `502`. Refunds of that payment are refused until the review is complete too (next section). ## Refunds while an update is open While an update of a payment is in progress or under review, refunds of that payment (including cancel-or-refund) are refused with `400` `OPERATION_IN_PROCESS`, the same answer as for any other operation running on the payment. Under review, the message says so. Nothing is recorded for the refused refund: repeat it with the **same idempotency key** once the update finishes. Refunds requested in bulk are not retried automatically; request them again. ## Response codes | HTTP | `code` | Meaning | | - | - | - | | 200 | — | The split was replaced. The answer is the payment. | | 400 | `INVALID_PARAMETERS` | A field is missing or invalid: no idempotency key, an empty split, a leg without recipient or amount, both recipient ids in one leg, amounts above the transaction amount, another currency, a description shorter than 3 or longer than 255 characters. | | 400 | `PAYMENT_NOT_FOUND`, `TRANSACTION_NOT_FOUND` | The payment, or the transaction of that payment, is not found for your account. | | 400 | `OPERATION_IN_PROCESS` | Another operation on the payment is already running. Try again in a few seconds with the same key. | | 404 | `RECIPIENT_NOT_FOUND` | A `recipient_id` is unknown, or the recipient is not onboarded with the provider of the transaction. | | 409 | `SPLIT_UPDATE_NOT_ALLOWED` | The transaction is not a succeeded purchase, the provider is not enabled, the payment has a refund (including one waiting to be retried), chargeback or transfer reversal, or a previous update is under review. | | 409 | `SPLIT_UPDATE_WINDOW_CLOSED` | The provider no longer accepts changes for this transaction. The split was not changed. | | 409 | `SPLIT_UPDATE_LIMIT_REACHED` | The provider's limit of split changes for this transaction was reached. The split was not changed. | | 409 | `SPLIT_UPDATE_IN_PROGRESS` | Another update of this transaction is in progress. Try again in a few seconds. | | 409 | `SPLIT_UPDATE_IDEMPOTENCY_CONFLICT` | The idempotency key was already used with a different body. | | 502 | `PROVIDER_ERROR` | The provider did not confirm the outcome; the update is under review. | ## OpenAPI ````yaml openapi/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) - url: https://api.eu.y.uno/v1 description: Production (EMEA) security: - sec0: [] sec1: [] paths: /payments/{payment_id}/transactions/{transaction_id}/split-marketplace: put: summary: Update the split of a paid transaction description: >- Replaces the whole `split_marketplace` of a succeeded purchase transaction at the provider and in Yuno. The legs sent become the split; legs that are not sent are removed. The payment and the transaction keep their status; no new transaction is created. The update is accepted only while the provider still allows it: before settlement, and while the payment has no refund (including one waiting to be retried), chargeback or transfer reversal. While an update is in progress or under review, refunds of the payment are refused with `400` `OPERATION_IN_PROCESS`. Availability depends on the provider; contact Yuno to enable it for your connection. operationId: update-split-marketplace parameters: - in: path name: payment_id schema: type: string required: true description: The unique identifier of the payment (MAX 64; MIN 36). - in: path name: transaction_id schema: type: string required: true description: >- The unique identifier of the purchase transaction whose split is replaced (MAX 64; MIN 36). - in: header name: X-Idempotency-Key schema: type: string required: true description: >- Required. Unique identifier of this update (MAX 64). A request that times out is not a failure: repeat it with the same key and you get the outcome of the first attempt. The same key with a different body is refused with `SPLIT_UPDATE_IDEMPOTENCY_CONFLICT`. A repeat sent while the first attempt is still running is answered `400` `OPERATION_IN_PROCESS` and changes nothing: wait a few seconds and repeat it again with the same key. requestBody: required: true content: application/json: schema: type: object required: - split_marketplace properties: split_marketplace: type: array minItems: 1 description: >- The new split: every leg the transaction must have after the update. items: properties: recipient_id: type: string description: >- The unique identifier of the recipient in the Yuno system. Every leg must name its recipient with the [`recipient_id`](/reference/create-recipient-1) (Yuno-generated) or the `provider_recipient_id` (external provider's ID), never both. provider_recipient_id: type: string description: >- The recipient ID provided by the external payment provider. Every leg must name its recipient with the `provider_recipient_id` or the [`recipient_id`](/reference/create-recipient-1) (Yuno-generated), never both. description: type: string description: Description for the split. (MAX 255; MIN 3). type: type: string description: >- The type of split. `recipient_id` is mandatory for `PURCHASE` and `MARKETPLACE`. enum: - PURCHASE - PAYMENTFEE - VAT - COMMISSION - MARKETPLACE - SHIPPING merchant_reference: type: string description: >- Optional unique identifier for the split transaction (MAX 255; MIN 3). recipient_type: type: string description: The type of recipient for the provider. enum: - MEAL - FOOD - MULTI_BENEFITS - FLEET example: MEAL amount: type: object description: >- The amount of the leg. Required on an update: the amount of the original transaction is not part of this request, so nothing is calculated from a `split_configuration`. required: - value - currency properties: value: type: number description: The split amount (multiple of 0.0001). format: float currency: type: string description: >- The currency of the payment (MAX 3; MIN 3; ISO 4217). Optional; when omitted the payment currency is used. Another currency is refused. liability: type: object description: >- Optional information regarding the recipient's liability for fees and chargebacks. properties: processing_fee: type: string description: Indicates who will be charged the transaction fee. enum: - MERCHANT - RECIPIENT - SHARED chargebacks: type: boolean description: >- The recipient is responsible in case of a chargeback. required: - type - amount type: object description: type: string description: Description of the update (MAX 255; MIN 3). metadata: type: array description: Custom key-value pairs stored with the update. 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: >- The split was replaced. The answer is the payment, in the same shape as [Retrieve payment by ID](/reference/retrieve-payment-by-id); read the new split on `transactions.split_marketplace`. content: application/json: schema: type: object description: >- The payment object. See [The payment object](/reference/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: >- The request is invalid, the payment or transaction is not found for your account, or another operation of the payment is still running (`OPERATION_IN_PROCESS`, retry in a few seconds with the same key). 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: >- A `recipient_id` of the request is unknown, or not onboarded with the provider of the transaction. 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: >- The update is not possible for this transaction, or it conflicts with another update. 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: >- The provider did not confirm the outcome. The split is under review by Yuno; do not retry with a new key. A retry with the same key returns this same answer until the review is complete. 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: sec1: type: apiKey in: header name: private-secret-key x-default: ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.