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

# Conectividad bancaria

> API unificada para crear cuentas bancarias, ejecutar transferencias y hacer el onboarding de entidades en múltiples proveedores bancarios

Yuno Banking Connectivity ofrece una API unificada para crear cuentas bancarias, procesar transferencias y gestionar el onboarding de entidades en múltiples proveedores bancarios. Una sola integración te da acceso a proveedores en EE. UU., Reino Unido, Australia y la UE.

## Flujo de integración

Sigue estos pasos para ir de la creación de la entidad a las transferencias de fondos:

1. **Crea una entidad**: registra a una persona o un negocio con [Create Entity](https://docs.y.uno/es/reference/banking-connectivity/entities-banking-connectivity/create-entity.md).
2. **Haz el onboarding de la entidad**: envía la documentación de KYC/KYB mediante [Create Entity Onboarding](https://docs.y.uno/es/reference/banking-connectivity/entity-onboarding-banking-connectivity/create-entity-onboarding.md).
3. **Espera la aprobación del onboarding**: monitorea el estado del onboarding con [Get Entity Onboarding Status](https://docs.y.uno/es/reference/banking-connectivity/entity-onboarding-banking-connectivity/get-entity-onboarding-status.md) o escucha los eventos de webhook.
4. **Crea una cuenta bancaria**: cuando el onboarding sea exitoso, abre una cuenta con [Create Account](https://docs.y.uno/es/reference/banking-connectivity/accounts/create-account-banking.md).
5. **Inicia transferencias**: envía fondos con [Initiate Entity Transfer](https://docs.y.uno/es/reference/banking-connectivity/entity-transfers-banking-connectivity/initiate-entity-transfer.md).

## Tipos de entidad

El campo `entity_type` determina la estructura de la entidad:

| Valor | Descripción | Detalle requerido |
| - | - | - |
| `INDIVIDUAL` | Una persona física | `entity_detail.individual` con nombre, fecha de nacimiento, información fiscal y documento de identidad |
| `BUSINESS` | Un negocio u organización | `entity_detail.business` con nombre del negocio, tipo, información fiscal y beneficiarios finales |

## Tipos de onboarding

| Tipo | Comportamiento |
| - | - |
| `ONE_STEP` | Envía toda la información, las declaraciones de cumplimiento, la evaluación de riesgo y los documentos de una vez. El proveedor procesa de inmediato. |
| `PREVIOUSLY_ONBOARDED` | Genera un ID de onboarding interno de Yuno sin contactar al proveedor. Úsalo cuando la entidad ya haya hecho el onboarding externamente. |

## Estados del onboarding

| Estado | Descripción | Terminal |
| - | - | - |
| `CREATED` | Registro de onboarding creado | No |
| `PENDING` | Enviado al proveedor, pendiente de revisión | No |
| `PENDING_ADDITIONAL_DOCUMENTATION` | El proveedor requiere más documentos | No |
| `UNDER_REVIEW` | El proveedor está revisando el envío | No |
| `SUCCEEDED` | Onboarding aprobado: la entidad puede abrir cuentas | Sí |
| `FAILED` | El onboarding falló por errores | Sí |
| `DECLINED` | El proveedor rechazó la entidad | Sí |
| `CANCELLED` | Onboarding cancelado por el comercio (aún no disponible) | Sí |
| `EXPIRED` | El onboarding expiró antes de completarse | Sí |

## Estados de la transferencia

| Estado | Descripción | Terminal |
| - | - | - |
| `PENDING` | Transferencia creada, pendiente de procesamiento | No |
| `PROCESSING` | Transferencia enviada a la red de pagos | No |
| `COMPLETED` | Fondos entregados correctamente | Sí |
| `FAILED` | La transferencia falló | Sí |
| `CANCELLED` | Transferencia cancelada antes de procesarse | Sí |
| `REVERSED` | Una transferencia completada fue revertida (p. ej., devolución ACH) | Sí |

> [!NOTE]
>
> **Nota:** Los canales de pago instantáneo (RTP) omiten el estado `PROCESSING` y pasan directamente de `PENDING` a `COMPLETED` o `FAILED`.

## Canales de pago

Los canales de pago disponibles dependen de la región del proveedor. El campo `payment_rail` acepta solo los valores siguientes, además de `BOOK` (con `transfer_type: BOOK`) y `PUSH_TO_CARD`:

| Región | Canal | Velocidad |
| - | - | - |
| **US** | `ACH_STANDARD` | 1–3 días hábiles |
| **US** | `ACH_SAME_DAY` | El mismo día |
| **US** | `WIRE` | El mismo día |
| **US** | `RTP` | Instantáneo |

## Identificadores de cuenta por región

Las respuestas de [Create Account](https://docs.y.uno/es/reference/banking-connectivity/accounts/create-account-banking.md) incluyen identificadores bancarios específicos de cada región:

| Región | Campos devueltos |
| - | - |
| US | `account_number`, `routing_number` |
| UK | `account_number`, `sort_code`, `iban` |
| Australia | `account_number`, `bsb` |
| EU | `iban`, `swift` |

## Tipos de documentación

Al crear o actualizar un onboarding, el arreglo `documentation` acepta elementos con un campo `document_type` obligatorio. Completa el subobjeto con el nombre del tipo, en minúsculas (por ejemplo, `bank_statement` para `BANK_STATEMENT`):

| `document_type` | Subobjeto | Descripción |
| - | - | - |
| `IDENTITY_DOCUMENT` | `identity_document` | Pasaporte, licencia de conducir, documento nacional de identidad o identificación estatal con imágenes del anverso y reverso |
| `PROOF_OF_ADDRESS` | `proof_of_address` | Factura de servicios, estado de cuenta bancario, contrato de arrendamiento, hipoteca o documento fiscal |
| `BANK_STATEMENT` | `bank_statement` | Estado de cuenta bancario con período y datos de la cuenta |
| `BUSINESS_DOCUMENT` | `business_document` | Acta constitutiva, licencia comercial, confirmación de EIN, acuerdo operativo o certificado de buena reputación |
| `TAX_INFORMATION` | `tax_information` | W9, 1099, declaración de impuestos, tarjeta SSN, carta ITIN, confirmación de EIN o certificado de VAT |
| `FINANCIAL_DOCUMENT` | `financial_document` | Balance general, estado de pérdidas y ganancias, estado de flujo de efectivo o auditoría financiera |
| `BIOMETRIC_VERIFICATION` | `biometric_verification` | Reconocimiento facial, huella dactilar, voz o escaneo de iris con verificación de vida |
| `EMPLOYMENT_INFORMATION` | `employment_information` | Situación laboral, datos del empleador, ocupación e ingresos |

Cada subobjeto incluye sus documentos en un arreglo `files` (por ejemplo, `bank_statement.files`, `identity_document.files`), excepto `tax_information`, que usa `tax_records`. Cada archivo usa codificación base64 con los campos `file_name`, `content_type` y `content`. Un ejemplo de elemento:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "document_type": "BANK_STATEMENT",
  "bank_statement": {
    "files": [
      {
        "file_name": "bank_statement_dec_2025.pdf",
        "content_type": "application/pdf",
        "content": "<base64>"
      }
    ]
  }
}
```

## Eventos de webhook

Yuno envía notificaciones de webhook a tu endpoint configurado para los siguientes eventos. Para la configuración general de webhooks, el comportamiento de entrega y la lógica de reintentos, consulta [Eventos y disparadores](https://docs.y.uno/es/docs/webhooks/events.md#banking-connectivity).

### Eventos de entidad

* `banking.entity.created`: entidad creada
* `banking.entity.updated`: entidad actualizada
* `banking.entity.deleted`: entidad eliminada

### Eventos de onboarding

* `banking.onboarding.created`: onboarding creado
* `banking.onboarding.pending`: enviado, pendiente de revisión
* `banking.onboarding.pending_additional_documentation`: se requieren más documentos
* `banking.onboarding.succeeded`: onboarding aprobado
* `banking.onboarding.failed`: el onboarding falló
* `banking.onboarding.declined`: rechazado por el proveedor
* `banking.onboarding.cancelled`: cancelado por el comercio (aún no disponible)
* `banking.onboarding.expired`: el onboarding expiró

### Eventos de cuenta

* `banking.account.created`: cuenta creada
* `banking.account.updated`: cuenta actualizada
* `banking.account.activated`: cuenta activada
* `banking.account.closed`: cuenta cerrada

### Eventos de transferencia (salientes)

* `banking.transfer.pending`: transferencia pendiente
* `banking.transfer.processing`: transferencia en procesamiento
* `banking.transfer.completed`: transferencia completada
* `banking.transfer.failed`: la transferencia falló
* `banking.transfer.cancelled`: transferencia cancelada
* `banking.transfer.reversed`: transferencia revertida

### Eventos de transferencia (entrantes)

* `banking.transfer.incoming.pending`: transferencia entrante pendiente de liquidación
* `banking.transfer.incoming.completed`: transferencia entrante liquidada

Las notificaciones de transferencias entrantes se envían a tu endpoint en `{merchant_base_URL}/v1/banking/transfers`. Consulta [Notificaciones de webhook](https://docs.y.uno/es/reference/banking-connectivity/webhooks/webhook-notifications-banking.md) para ver la estructura del payload.

## Códigos de error

| Código | Estado HTTP | Descripción |
| - | - | - |
| `NOT_AUTHENTICATED` | 401 | Claves de API faltantes o no válidas |
| `AuthenticationFail` | 401 | La autenticación falló |
| `BadRequest` | 400 | Solicitud con formato incorrecto |
| `VALIDATION_ERROR` | 400 | La validación de la solicitud falló |
| `DUPLICATE_ENTITY` | 409 | Ya existe una entidad con este `merchant_entity_id` |
| `ENTITY_NOT_FOUND` | 404 | Entidad no encontrada |
| `ONBOARDING_NOT_FOUND` | 404 | Onboarding no encontrado |
| `ACCOUNT_NOT_FOUND` | 404 | Cuenta no encontrada |
| `INSUFFICIENT_BALANCE` | 422 | Fondos insuficientes para la transferencia |
| `CURRENCY_MISMATCH` | 422 | La moneda de la transferencia no coincide con la moneda de la cuenta |
| `PROVIDER_ERROR` | 502 | Error del proveedor bancario |
| `PROVIDER_TIMEOUT` | 504 | El proveedor no respondió a tiempo |
| `InternalError` | 500 | Error interno del servidor |
| `TooManyRequests` | 429 | Límite de solicitudes excedido |

Las respuestas de error siguen este formato:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "ERROR_CODE",
  "messages": ["Human-readable error message"],
  "http_code": 400
}
```


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