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

# Iniciar transferencia de entidad (Banking Connectivity)

> Inicia una transferencia saliente o interna entre cuentas desde una cuenta de banking connectivity

Inicia una transferencia desde una cuenta de Banking Connectivity. `transfer_type` es obligatorio: `OUTGOING` para transferencias externas (proporciona los datos bancarios de `destination_account`), `BOOK` para transferencias internas entre cuentas del mismo proveedor (define `destination_account.account_id` con la cuenta de destino) e `INCOMING` para transferencias entrantes.

Los campos obligatorios en `destination_account` dependen de la región. Consulta [Payment rails](https://docs.y.uno/es/reference/banking-connectivity.md#payment-rails) y [Account identifiers by region](https://docs.y.uno/es/reference/banking-connectivity.md#account-identifiers-by-region) para más detalles.

La respuesta devuelve `202 Accepted` con un estado `PENDING`. Supervisa el progreso mediante [Get Entity Transfer Status](https://docs.y.uno/es/reference/banking-connectivity/entity-transfers-banking-connectivity/get-entity-transfer-status.md) o eventos de webhook. Consulta [Transfer statuses](https://docs.y.uno/es/reference/banking-connectivity.md#transfer-statuses) para el ciclo de vida completo de los estados.


## OpenAPI

````yaml openapi/es/banking-connectivity/entity-transfers-banking-connectivity/initiate-entity-transfer.json POST /banking/transfers
openapi: 3.0.0
info:
  version: 1.0.0
  title: Banking Connectivity
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:
  /banking/transfers:
    post:
      tags:
        - Entity Transfers (Banking Connectivity)
      summary: Initiate Entity Transfer (Banking Connectivity)
      operationId: post_v1-banking-connectivity-transfers
      parameters:
        - in: header
          name: x-idempotency-key
          schema:
            type: string
          description: >-
            Identificador único que se usa en los encabezados HTTP para asegurar
            que una solicitud se procese una sola vez, aunque se reintente por
            problemas de red o tiempos de espera agotados. Consulta
            [autenticación](/es/reference/getting-started/authentication#idempotency)
            para ver los detalles (UUID).
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - source_account_id
                - transfer_type
                - amount
                - payment_rail
              properties:
                account_id:
                  type: string
                  description: >-
                    El identificador único de la cuenta de Yuno del comercio
                    (UUID, 36 caracteres).
                  example: 550e8400-e29b-41d4-a716-446655440000
                source_account_id:
                  type: string
                  description: >-
                    El `id` de la cuenta de origen de Banking Connectivity
                    obtenido de [Create
                    Account](/es/reference/banking-connectivity/accounts/create-account-banking)
                    (UUID, 36 caracteres).
                  example: aa0e8400-e29b-41d4-a716-446655440000
                transfer_type:
                  type: string
                  description: >-
                    El tipo de transferencia. `OUTGOING` envía fondos a una
                    cuenta externa (define `destination_account` con los datos
                    bancarios). `BOOK` mueve fondos a otra cuenta de Banking
                    Connectivity (define `destination_account.account_id`).
                    `INCOMING` es una transferencia entrante.
                  example: OUTGOING
                  enum:
                    - OUTGOING
                    - BOOK
                    - INCOMING
                amount:
                  type: object
                  description: >-
                    El monto de la transferencia. La moneda debe coincidir con
                    la moneda de la cuenta de origen.
                  required:
                    - value
                    - currency
                  properties:
                    value:
                      type: number
                      description: >-
                        El monto de la transferencia (hasta 4 decimales, máximo
                        9,999,999,999).
                      example: 1000
                    currency:
                      type: string
                      description: >-
                        La moneda ([ISO
                        4217](https://en.wikipedia.org/wiki/ISO_4217)). Debe
                        coincidir con la moneda de la cuenta de origen.
                      example: USD
                payment_rail:
                  type: string
                  description: >-
                    El rail de pago que se usará para la transferencia. Usa
                    `BOOK` con `transfer_type: BOOK`. Los rails disponibles
                    dependen de la región del proveedor.
                  enum:
                    - ACH_STANDARD
                    - ACH_SAME_DAY
                    - WIRE
                    - RTP
                    - BOOK
                    - PUSH_TO_CARD
                  example: ACH_STANDARD
                description:
                  type: string
                  description: Una descripción de la transferencia.
                  example: Payment to vendor
                merchant_transfer_id:
                  type: string
                  description: >-
                    El ID de referencia propio del comercio para la
                    conciliación.
                  example: merchant_txn_12345
                destination_account:
                  type: object
                  description: >-
                    El destino. Para transferencias `OUTGOING`, envía los datos
                    bancarios externos; los campos obligatorios dependen de la
                    región: EE. UU. requiere `account_number` y
                    `routing_number`; Reino Unido requiere `iban` o
                    `account_number` con `sort_code`; Australia requiere
                    `account_number` con `bsb`. Para transferencias `BOOK`,
                    envía solo `account_id` con el `id` de la cuenta de Banking
                    Connectivity de destino.
                  properties:
                    account_id:
                      type: string
                      description: >-
                        El `id` de la cuenta de Banking Connectivity de destino
                        para transferencias `BOOK` (UUID, 36 caracteres).
                      example: bb0e8400-e29b-41d4-a716-446655440000
                    account_number:
                      type: string
                      description: El número de cuenta bancaria de destino.
                      example: '9876543210'
                    routing_number:
                      type: string
                      nullable: true
                      description: >-
                        El routing number de EE. UU. Obligatorio para destinos
                        en EE. UU.
                      example: '987654321'
                    iban:
                      type: string
                      nullable: true
                      description: >-
                        El IBAN. Obligatorio para destinos en Reino Unido y
                        SEPA.
                      example: null
                    bsb:
                      type: string
                      nullable: true
                      description: >-
                        El número BSB de Australia. Obligatorio para destinos en
                        Australia.
                      example: null
                    swift:
                      type: string
                      nullable: true
                      description: >-
                        El código SWIFT/BIC. Obligatorio para transferencias
                        internacionales y SEPA.
                      example: null
                    sort_code:
                      type: string
                      nullable: true
                      description: >-
                        El sort code de Reino Unido. Obligatorio para destinos
                        en Reino Unido.
                      example: null
                    account_name:
                      type: string
                      description: El nombre del titular de la cuenta de destino.
                      example: Jane Smith
                    bank_name:
                      type: string
                      description: El nombre del banco de destino.
                      example: Chase Bank
            examples:
              Outgoing Transfer:
                summary: Outgoing Transfer
                value:
                  account_id: 550e8400-e29b-41d4-a716-446655440000
                  source_account_id: aa0e8400-e29b-41d4-a716-446655440000
                  transfer_type: OUTGOING
                  amount:
                    value: 1000
                    currency: USD
                  payment_rail: ACH_STANDARD
                  description: Payment to vendor
                  merchant_transfer_id: merchant_txn_12345
                  destination_account:
                    account_number: '9876543210'
                    routing_number: '987654321'
                    account_name: Jane Smith
                    bank_name: Chase Bank
              Book Transfer (Internal):
                summary: Book Transfer (Internal)
                value:
                  account_id: 550e8400-e29b-41d4-a716-446655440000
                  source_account_id: aa0e8400-e29b-41d4-a716-446655440000
                  transfer_type: BOOK
                  amount:
                    value: 500
                    currency: USD
                  payment_rail: BOOK
                  description: Internal transfer between accounts
                  merchant_transfer_id: merchant_book_67890
                  destination_account:
                    account_id: bb0e8400-e29b-41d4-a716-446655440000
      responses:
        '202':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: bb0e8400-e29b-41d4-a716-446655440000
                  source_account_id:
                    type: string
                    example: aa0e8400-e29b-41d4-a716-446655440000
                  destination_account_id: {}
                  account_id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
                  merchant_transfer_id:
                    type: string
                    example: merchant_txn_12345
                  provider:
                    type: object
                    properties:
                      account_id:
                        type: string
                        example: col_bank_account_789
                      transfer_id:
                        type: string
                        example: col_transfer_xyz123
                  status:
                    type: string
                    example: PENDING
                  transfer_type:
                    type: string
                    example: OUTGOING
                  destination_account:
                    type: object
                    properties:
                      account_number_last_4:
                        type: string
                        example: '3210'
                      routing_number:
                        type: string
                        example: '987654321'
                      iban: {}
                      bsb: {}
                      swift: {}
                      sort_code: {}
                      account_name:
                        type: string
                        example: Jane Smith
                      bank_name:
                        type: string
                        example: Chase Bank
                  amount:
                    type: object
                    properties:
                      value:
                        type: integer
                        example: 1000
                        default: 0
                      currency:
                        type: string
                        example: USD
                  payment_rail:
                    type: string
                    example: ACH_STANDARD
                  description:
                    type: string
                    example: Payment to vendor
                  created_at:
                    type: string
                    example: '2026-02-01T10:15:00Z'
                  updated_at:
                    type: string
                    example: '2026-02-01T10:15:00Z'
              examples:
                Accepted (Outgoing):
                  summary: Accepted (Outgoing)
                  value:
                    id: bb0e8400-e29b-41d4-a716-446655440000
                    source_account_id: aa0e8400-e29b-41d4-a716-446655440000
                    destination_account_id: null
                    account_id: 550e8400-e29b-41d4-a716-446655440000
                    merchant_transfer_id: merchant_txn_12345
                    provider:
                      account_id: col_bank_account_789
                      transfer_id: col_transfer_xyz123
                    status: PENDING
                    transfer_type: OUTGOING
                    destination_account:
                      account_number_last_4: '3210'
                      routing_number: '987654321'
                      iban: null
                      bsb: null
                      swift: null
                      sort_code: null
                      account_name: Jane Smith
                      bank_name: Chase Bank
                    amount:
                      value: 1000
                      currency: USD
                    payment_rail: ACH_STANDARD
                    description: Payment to vendor
                    created_at: '2026-02-01T10:15:00Z'
                    updated_at: '2026-02-01T10:15:00Z'
          description: Aceptado
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_PARAMETERS
                  messages:
                    type: array
                    items:
                      type: string
                      example: The field 'transfer_type' is required.
                  http_code:
                    type: integer
                    example: 400
                    default: 0
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The field 'transfer_type' is required.
                    http_code: 400
          description: Solicitud incorrecta
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ACCOUNT_NOT_FOUND
                  messages:
                    type: array
                    items:
                      type: string
                      example: Account not found
                  http_code:
                    type: integer
                    example: 404
                    default: 0
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: ACCOUNT_NOT_FOUND
                    messages:
                      - Account not found
                    http_code: 404
          description: No encontrado
components:
  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.