> ## 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.

# Solicitar una transferencia

> Revierte una transferencia dividida entre destinatarios para una transacción de pago específica

Permite a los marketplaces que usan Yuno Split Payments solicitar una transferencia a partir de un pago existente. Solicita una transferencia por un monto determinado a uno de los destinatarios que participan en la división.

La transacción debe incluir destinatarios `split_marketplace`, porque la transferencia se envía a ellos. Si la transacción no tiene ninguno, la API devuelve 400 con "Payment has no recipient". El monto debe ser menor o igual al monto de la transacción y estar en la moneda del pago.


## OpenAPI

````yaml openapi/es/recipients-for-marketplace/request-a-transfer.json POST /payments/{payment_id}/transactions/{transaction_id}/split-marketplace/transfer-reversal
openapi: 3.1.0
info:
  title: Recipients API
  version: 1.0.0
  description: >-
    API for managing recipients in split payment scenarios. This feature enables
    merchants to split payments among multiple recipients, which is particularly
    beneficial for marketplace models where transactions need to be divided
    among different sellers or stakeholders.
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/transfer-reversal:
    post:
      operationId: >-
        post_payments-payment-id-transactions-transaction-id-split-marketplace-transfer-reversal
      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 (MAX 64; MIN 36).
        - in: header
          name: X-Idempotency-Key
          schema:
            type: string
          description: >-
            Identificador único que se usa en los encabezados HTTP para
            garantizar que una solicitud se procese una sola vez, aunque se
            reintente por problemas de red o timeouts.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: object
                  properties:
                    currency:
                      type: string
                      description: >-
                        Moneda de la transacción. Visita la [referencia de
                        países](/es/reference/country-reference) para ver la
                        lista completa de monedas admitidas.
                    value:
                      type: number
                      description: Monto de la transacción.
                  description: El monto del pago (múltiplo de 0.0001).
                  required:
                    - currency
                    - value
                description:
                  type: string
                  description: Identificador único de la transacción (MAX 256; MIN 3).
              required:
                - amount
            examples:
              Request a transfer:
                value:
                  amount:
                    currency: USD
                    value: 100
                  description: test transfer
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Identificador único de la transferencia.
                  recipient_id:
                    type: string
                    description: El identificador único del destinatario.
                  amount:
                    type: object
                    properties:
                      currency:
                        type: string
                      value:
                        type: number
                  status:
                    type: string
                    description: Estado de la transferencia.
                  description:
                    type: string
                  merchant_reference:
                    type: string
                  metadata:
                    type: array
                    items: {}
                  provider:
                    type:
                      - object
                      - 'null'
                  transactions:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        type:
                          type: string
                        status:
                          type: string
                        provider_transfer_id:
                          type: string
                        raw_response:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
                  completed_at:
                    type: string
                    format: date-time
              examples:
                Success:
                  value:
                    id: 94036ceb-5cca-4384-b144-e2a5a908af77
                    recipient_id: e56c3329-f3d9-48e5-a677-284b147abf95
                    amount:
                      currency: USD
                      value: 100
                    status: SUCCEEDED
                    description: test transfer
                    merchant_reference: c19e858a-ffd6-4635-8a31-4f60c5becf4d
                    metadata: []
                    provider: null
                    transactions:
                      - code: 7ac2c5f3-7c79-4e99-b45e-aa5952620188
                        type: SPLIT_TRANSFER
                        status: SUCCEEDED
                        provider_transfer_id: tr_1T9eKVIiMnPsFcbbRTb8ObsZ
                        raw_response: |-
                          {
                            "id": "tr_1T9eKVIiMnPsFcbbRTb8ObsZ",
                            "object": "transfer",
                            "amount": 10000,
                            "amount_reversed": 0,
                            "balance_transaction": "txn_1T9eKVIiMnPsFcbbOPnvz3xM",
                            "created": 1773203107,
                            "currency": "usd",
                            "description": "test transfer",
                            "destination": "acct_1T9PSQIZEg1WWTvj",
                            "destination_payment": "py_1T9eKVIZEg1WWTvjbVjmnzFK",
                            "livemode": false,
                            "metadata": {},
                            "reversals": {
                              "object": "list",
                              "data": [],
                              "has_more": false,
                              "total_count": 0,
                              "url": "/v1/transfers/tr_1T9eKVIiMnPsFcbbRTb8ObsZ/reversals"
                            },
                            "reversed": false,
                            "source_transaction": null,
                            "source_type": "card",
                            "transfer_group": null
                          }
                        created_at: '2026-03-11T04:25:06.229027Z'
                        updated_at: '2026-03-11T04:25:07.917364Z'
                    created_at: '2026-03-11T04:25:06.208761Z'
                    updated_at: '2026-03-11T04:25:07.928000342Z'
                    completed_at: '2026-03-11T04:25:07.927971142Z'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Transfer Error:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - 'Invalid parameters: list - [Payment has no recipient]'
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.