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

# Crear una transferencia independiente

> Crea una transferencia independiente con una dirección inmutable

Crea una transferencia de forma independiente de un pago. El campo `direction` determina qué cuenta envía los fondos.

> [!WARNING]
>
> Las transferencias del destinatario a la plataforma no están disponibles de forma general. Usa esta dirección solo después de que Yuno confirme la habilitación de la cuenta y la compatibilidad del proveedor.

| Dirección | Movimiento |
| - | - |
| `PLATFORM_TO_RECIPIENT` | Del saldo de la plataforma al destinatario. Es el valor predeterminado cuando `direction` se omite o es `null`. |
| `RECIPIENT_TO_PLATFORM` | Del saldo del destinatario a la plataforma, por ejemplo una comisión de disputa aparte. Requiere una cuenta habilitada y compatibilidad con el proveedor `STRIPE`. La conexión de onboarding del destinatario identifica la cuenta del proveedor. |

La dirección se guarda al crear la transferencia y se devuelve en la respuesta, en [GET](https://docs.y.uno/es/reference/transfers/get-standalone-transfer.md) y en las notificaciones de la transferencia. No se puede cambiar después de la creación. Reutilizar la misma cuenta y la misma clave de idempotencia con una dirección distinta se rechaza; omitir la dirección y enviar `PLATFORM_TO_RECIPIENT` de forma explícita representan la misma dirección.

Las cadenas no válidas (incluidos los valores vacíos o con mayúsculas y minúsculas incorrectas), los objetos, los arreglos, los números y los booleanos devuelven `400 INVALID_PARAMETERS`. Una solicitud de destinatario a plataforma con un proveedor distinto de `STRIPE` devuelve `400 INVALID_PARAMETERS` antes de la verificación de habilitación. Una solicitud válida de destinatario a plataforma para una cuenta sin acceso devuelve `400 DIRECTION_NOT_ENABLED`, antes de la verificación de dirección de idempotencia.

Una transferencia de destinatario a plataforma no se puede [revertir](https://docs.y.uno/es/reference/transfers/reverse-standalone-transfer.md). Para devolver una comisión cobrada por separado, crea una nueva transferencia de plataforma a destinatario.


## OpenAPI

````yaml openapi/es/transfers/create-standalone-transfer.json POST /split-marketplace/transfers
openapi: 3.1.0
info:
  title: Transfer Flow API
  version: 1.0.0
  description: >-
    API for managing standalone forward and reverse transfers within the
    Marketplace.
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - public_api_key: []
    private_secret_key: []
paths:
  /split-marketplace/transfers:
    post:
      tags:
        - Transfers
      summary: Create Standalone Transfer
      description: >-
        Crea una transferencia independiente. La dirección es inmutable; si se
        omite o es null, la dirección por defecto es PLATFORM_TO_RECIPIENT.
        RECIPIENT_TO_PLATFORM no está disponible de forma general. Úsalo solo
        después de que Yuno confirme la habilitación de la cuenta y la
        compatibilidad del proveedor. RECIPIENT_TO_PLATFORM con un proveedor
        distinto de STRIPE devuelve INVALID_PARAMETERS antes de la verificación
        de habilitación. Reutilizar la misma cuenta y clave de idempotencia con
        una dirección normalizada diferente devuelve INVALID_PARAMETERS cuando
        la dirección solicitada está habilitada; de lo contrario, la protección
        de disponibilidad devuelve primero DIRECTION_NOT_ENABLED.
      operationId: create-standalone-transfer
      parameters:
        - name: X-Account-Code
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            El account_id que se encuentra en el Dashboard de Yuno. La API lee
            la cuenta de este encabezado.
        - name: X-Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: Clave única para la idempotencia de la solicitud.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipient_id
                - provider_id
                - amount
              properties:
                account_id:
                  type: string
                  deprecated: true
                  description: >-
                    No se usa. La API toma la cuenta del encabezado
                    `X-Account-Code`, por lo que puedes omitir este campo.
                recipient_id:
                  type: string
                  format: uuid
                  description: >-
                    El identificador del destinatario objetivo. El destinatario
                    debe tener un onboarding para `provider_id` en estado
                    PENDING o SUCCEEDED.
                provider_id:
                  type: string
                  description: >-
                    El código del proveedor de pago que se usará (por ejemplo,
                    adyen, stripe).
                amount:
                  $ref: '#/components/schemas/Amount'
                description:
                  type: string
                  description: >-
                    Una descripción legible de la transferencia (3-255
                    caracteres). Se envía al proveedor.
                merchant_reference:
                  type: string
                  description: >-
                    Identificador único del comercio para la idempotencia y el
                    seguimiento.
                metadata:
                  $ref: '#/components/schemas/Metadata'
                direction:
                  type:
                    - string
                    - 'null'
                  enum:
                    - PLATFORM_TO_RECIPIENT
                    - RECIPIENT_TO_PLATFORM
                    - null
                  default: PLATFORM_TO_RECIPIENT
                  description: >-
                    Dirección de la transferencia. Si se omite o es null, el
                    valor por defecto es PLATFORM_TO_RECIPIENT.
                    RECIPIENT_TO_PLATFORM solo se admite para cuentas STRIPE
                    elegibles. RECIPIENT_TO_PLATFORM no está disponible de forma
                    general. Úsalo solo después de que Yuno confirme la
                    habilitación de la cuenta y la compatibilidad del proveedor.
            examples:
              Platform to recipient:
                value:
                  recipient_id: 5a37f0c0-7689-4065-8348-4b5ff5bf9cc7
                  provider_id: STRIPE
                  amount:
                    value: 150
                    currency: USD
                  description: Marketplace payout
                  merchant_reference: MR-TRANSFER-001
                  direction: PLATFORM_TO_RECIPIENT
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
              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
                        provider_response_message: null
                        provider_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'
                    direction: PLATFORM_TO_RECIPIENT
                Error:
                  value:
                    id: 9778f631-504d-448f-b2c1-f7b903781df7
                    recipient_id: 82b12c8c-7d3d-4a21-a3c6-165cc04ca741
                    amount:
                      currency: USD
                      value: 50000
                    status: ERROR
                    description: test transfer
                    merchant_reference: cb18df20-21ae-4fed-8da9-fb81cfd56797
                    metadata: []
                    provider: null
                    transactions:
                      - code: 9eee65d1-6c3a-4076-9ef9-fa4bff73d597
                        type: SPLIT_TRANSFER
                        status: ERROR
                        provider_transfer_id: tr_1T9PTLIiMnPsFcbbFKyh1Nds
                        provider_response_message: |-
                          {
                            "id": "tr_1T9PTLIiMnPsFcbbFKyh1Nds",
                            "object": "transfer",
                            "amount": 10000,
                            "amount_reversed": 0,
                            "balance_transaction": "txn_1T9PTMIiMnPsFcbbxRKvaZ3G",
                            "created": 1773145996,
                            "currency": "usd",
                            "description": "test transfer"
                          }
                        provider_raw_response: '{.... }'
                        created_at: '2026-03-10T13:39:19.342902Z'
                        updated_at: '2026-03-10T13:39:19.342914Z'
                    created_at: '2026-03-10T13:39:19.241990247Z'
                    updated_at: '2026-03-10T13:39:19.242012664Z'
                    direction: PLATFORM_TO_RECIPIENT
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                PROVIDER_NOT_FOUND:
                  summary: Provider not found
                  value:
                    code: PROVIDER_NOT_FOUND
                    messages:
                      - The specified provider was not found.
                ONBOARDING_NOT_VALID:
                  summary: Onboarding not valid
                  value:
                    code: ONBOARDING_NOT_VALID
                    messages:
                      - >-
                        The recipient onboarding is not valid for this
                        operation.
                CURRENCY_NOT_SUPPORTED:
                  summary: Currency not supported
                  value:
                    code: CURRENCY_NOT_SUPPORTED
                    messages:
                      - The specified currency is not supported.
                INVALID_AMOUNT:
                  summary: Invalid amount
                  value:
                    code: INVALID_AMOUNT
                    messages:
                      - The transfer amount is invalid.
                INSUFFICIENT_BALANCE:
                  summary: Insufficient balance
                  value:
                    code: INSUFFICIENT_BALANCE
                    messages:
                      - Insufficient balance to complete the transfer.
                INVALID_DIRECTION_VALUE:
                  summary: Invalid direction value
                  description: >-
                    An empty, unknown or incorrectly cased string returns
                    INVALID_PARAMETERS. Null uses the default direction.
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The field 'direction' has an invalid value.
                INVALID_DIRECTION_TYPE:
                  summary: Direction is not a string
                  description: >-
                    A JSON object, array, number or boolean in direction is
                    rejected while decoding the body, before any other
                    validation.
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The field 'direction' must be a string.
                DIRECTION_UNSUPPORTED_PROVIDER:
                  summary: Recipient-to-platform with a provider other than STRIPE
                  description: >-
                    Rejected before the account enablement check. Match on code;
                    the message text can differ between releases.
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - Invalid transfer parameters
                DIRECTION_NOT_ENABLED:
                  summary: Direction not enabled for this account
                  value:
                    code: DIRECTION_NOT_ENABLED
                    messages:
                      - Transfer direction is not enabled for this account
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                RECIPIENT_NOT_FOUND:
                  summary: Recipient not found
                  value:
                    code: RECIPIENT_NOT_FOUND
                    messages:
                      - The specified recipient was not found.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                PROVIDER_INTERNAL_ERROR:
                  summary: Provider internal error
                  value:
                    code: PROVIDER_INTERNAL_ERROR
                    messages:
                      - The payment provider encountered an internal error.
components:
  schemas:
    Amount:
      type: object
      required:
        - value
        - currency
      properties:
        value:
          type: number
          example: 150
        currency:
          type: string
          example: USD
    Metadata:
      type: array
      items:
        type: object
        properties:
          key:
            type: string
          value:
            type: string
    Transfer:
      type: object
      properties:
        id:
          type: string
          example: TRF_7kB2mQ9xPnL4vR
        direction:
          type: string
          enum:
            - PLATFORM_TO_RECIPIENT
            - RECIPIENT_TO_PLATFORM
          description: >-
            La dirección inmutable guardada cuando se creó la transferencia. Las
            transferencias existentes devuelven PLATFORM_TO_RECIPIENT. No se
            puede cambiar después de la creación.
          example: PLATFORM_TO_RECIPIENT
        recipient_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        amount:
          $ref: '#/components/schemas/Amount'
        status:
          type: string
          example: SUCCEEDED
        reason:
          type: string
          example: ORDER_CANCELLED
        description:
          type: string
          example: Weekly marketplace earnings
        merchant_reference:
          type: string
          example: TRANSFER-2026-02-15-001
        metadata:
          $ref: '#/components/schemas/Metadata'
        provider_data:
          $ref: '#/components/schemas/ProviderData'
        created_at:
          type: string
          format: date-time
          example: '2026-02-16T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-02-16T10:30:15Z'
        completed_at:
          type: string
          format: date-time
          example: '2026-02-16T10:30:15Z'
        provider:
          type:
            - string
            - 'null'
          example: null
        transactions:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: 9eee65d1-6c3a-4076-9ef9-fa4bff73d597
              type:
                type: string
                example: SPLIT_TRANSFER
              status:
                type: string
                example: ERROR
              provider_transfer_id:
                type: string
                example: tr_1T9PTLIiMnPsFcbbFKyh1Nds
              provider_response_message:
                type: string
                example: ...
              provider_raw_response:
                type: string
                example: '{.... }'
              parent_transaction_code:
                type: string
                description: >-
                  Código de la transacción original que revierte una transacción
                  SPLIT_TRANSFER_REVERSE. Está ausente en la transacción
                  original.
                example: cb5fd244-90fd-49b0-a160-a9d9f764eb9e
              reason:
                type: string
                description: >-
                  Motivo indicado en la solicitud de reversión. Está presente en
                  las transacciones SPLIT_TRANSFER_REVERSE.
                example: ORDER_CANCELLED
              created_at:
                type: string
                format: date-time
                example: '2026-03-10T13:39:19.342902Z'
              updated_at:
                type: string
                format: date-time
                example: '2026-03-10T13:39:19.342914Z'
    ProviderData:
      type: object
      properties:
        id:
          type: string
          example: adyen
        recipient_id:
          type: string
          example: SE322KT223222B5CM82WL9TB
        transfer_id:
          type: string
          example: TRF_8535296827453920
        response_code:
          type: string
          example: '000'
        response_message:
          type: string
          example: Transfer completed
  securitySchemes:
    public_api_key:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
    private_secret_key:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY

````

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