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

# Banking Connectivity

> Unified API to create bank accounts, run transfers, and onboard entities across multiple banking providers

Yuno Banking Connectivity provides a unified API to create bank accounts, process transfers, and manage entity onboarding across multiple banking providers. A single integration gives you access to providers across the US, UK, Australia, and EU.

## Integration flow

Follow these steps to go from entity creation to fund transfers:

1. **Create an entity**: Register an individual or business using [Create Entity](https://docs.y.uno/reference/create-entity.md).
2. **Onboard the entity**: Submit KYC/KYB documentation through [Create Entity Onboarding](https://docs.y.uno/reference/create-entity-onboarding.md).
3. **Wait for onboarding approval**: Monitor the onboarding status via [Get Entity Onboarding Status](https://docs.y.uno/reference/get-entity-onboarding-status.md) or listen for webhook events.
4. **Create a bank account**: Once onboarding succeeds, open an account with [Create Account](https://docs.y.uno/reference/create-account-banking.md).
5. **Initiate transfers**: Send funds using [Initiate Entity Transfer](https://docs.y.uno/reference/initiate-entity-transfer.md).

## Entity types

The `entity_type` field determines the entity structure:

| Value | Description | Required detail |
| - | - | - |
| `INDIVIDUAL` | A natural person | `entity_detail.individual` with name, DOB, tax info, and identity document |
| `BUSINESS` | A business or organization | `entity_detail.business` with business name, type, tax info, and beneficial owners |

## Onboarding types

| Type | Behavior |
| - | - |
| `ONE_STEP` | Submits all information, compliance declarations, risk assessment, and documents at once. The provider processes immediately. |
| `PREVIOUSLY_ONBOARDED` | Generates an internal Yuno onboarding ID without contacting the provider. Use when the entity has already been onboarded externally. |

## Onboarding statuses

| Status | Description | Terminal |
| - | - | - |
| `CREATED` | Onboarding record created | No |
| `PENDING` | Submitted to provider, awaiting review | No |
| `PENDING_ADDITIONAL_DOCUMENTATION` | Provider requires more documents | No |
| `UNDER_REVIEW` | Provider is reviewing the submission | No |
| `SUCCEEDED` | Onboarding approved: entity can open accounts | Yes |
| `FAILED` | Onboarding failed due to errors | Yes |
| `DECLINED` | Provider declined the entity | Yes |
| `CANCELLED` | Onboarding cancelled by merchant (not available yet) | Yes |
| `EXPIRED` | Onboarding expired before completion | Yes |

## Transfer statuses

| Status | Description | Terminal |
| - | - | - |
| `PENDING` | Transfer created, awaiting processing | No |
| `PROCESSING` | Transfer submitted to the payment network | No |
| `COMPLETED` | Funds successfully delivered | Yes |
| `FAILED` | Transfer failed | Yes |
| `CANCELLED` | Transfer cancelled before processing | Yes |
| `REVERSED` | Completed transfer was reversed (e.g., ACH return) | Yes |

> [!NOTE]
>
> **Note:** Instant payment rails (RTP) skip the `PROCESSING` state and go directly from `PENDING` to `COMPLETED` or `FAILED`.

## Payment rails

Available payment rails depend on the provider's region. The `payment_rail` field accepts only the values below, plus `BOOK` (with `transfer_type: BOOK`) and `PUSH_TO_CARD`:

| Region | Rail | Speed |
| - | - | - |
| **US** | `ACH_STANDARD` | 1–3 business days |
| **US** | `ACH_SAME_DAY` | Same day |
| **US** | `WIRE` | Same day |
| **US** | `RTP` | Instant |

## Account identifiers by region

Responses from [Create Account](https://docs.y.uno/reference/create-account-banking.md) include region-specific banking identifiers:

| Region | Fields returned |
| - | - |
| US | `account_number`, `routing_number` |
| UK | `account_number`, `sort_code`, `iban` |
| Australia | `account_number`, `bsb` |
| EU | `iban`, `swift` |

## Documentation types

When creating or updating an onboarding, the `documentation` array accepts items with a required `document_type` field. Populate the sub-object named after the type, in lower case (for example `bank_statement` for `BANK_STATEMENT`):

| `document_type` | Sub-object | Description |
| - | - | - |
| `IDENTITY_DOCUMENT` | `identity_document` | Passport, driver's license, national ID, or state ID with front/back images |
| `PROOF_OF_ADDRESS` | `proof_of_address` | Utility bill, bank statement, lease, mortgage, or tax document |
| `BANK_STATEMENT` | `bank_statement` | Bank statement with period and account details |
| `BUSINESS_DOCUMENT` | `business_document` | Articles of incorporation, business license, EIN confirmation, operating agreement, or certificate of good standing |
| `TAX_INFORMATION` | `tax_information` | W9, 1099, tax return, SSN card, ITIN letter, EIN confirmation, or VAT certificate |
| `FINANCIAL_DOCUMENT` | `financial_document` | Balance sheet, P\&L statement, cash flow statement, or financial audit |
| `BIOMETRIC_VERIFICATION` | `biometric_verification` | Facial recognition, fingerprint, voice, or iris scan with liveness check |
| `EMPLOYMENT_INFORMATION` | `employment_information` | Employment status, employer details, occupation, and income |

Each sub-object carries its documents in a `files` array (for example `bank_statement.files`, `identity_document.files`), except `tax_information`, which takes `tax_records`. Each file uses base64 encoding with `file_name`, `content_type`, and `content` fields. An example item:

```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>"
      }
    ]
  }
}
```

## Webhook events

Yuno sends webhook notifications to your configured endpoint for the following events. For general webhook setup, delivery behavior, and retry logic, see [Events and Triggers](https://docs.y.uno/docs/webhooks/events.md#banking-connectivity).

### Entity events

* `banking.entity.created`: Entity created
* `banking.entity.updated`: Entity updated
* `banking.entity.deleted`: Entity deleted

### Onboarding events

* `banking.onboarding.created`: Onboarding created
* `banking.onboarding.pending`: Submitted, awaiting review
* `banking.onboarding.pending_additional_documentation`: More documents required
* `banking.onboarding.succeeded`: Onboarding approved
* `banking.onboarding.failed`: Onboarding failed
* `banking.onboarding.declined`: Provider declined
* `banking.onboarding.cancelled`: Merchant cancelled (not available yet)
* `banking.onboarding.expired`: Onboarding expired

### Account events

* `banking.account.created`: Account created
* `banking.account.updated`: Account updated
* `banking.account.activated`: Account activated
* `banking.account.closed`: Account closed

### Transfer events (outgoing)

* `banking.transfer.pending`: Transfer pending
* `banking.transfer.processing`: Transfer processing
* `banking.transfer.completed`: Transfer completed
* `banking.transfer.failed`: Transfer failed
* `banking.transfer.cancelled`: Transfer cancelled
* `banking.transfer.reversed`: Transfer reversed

### Transfer events (incoming)

* `banking.transfer.incoming.pending`: Incoming transfer pending settlement
* `banking.transfer.incoming.completed`: Incoming transfer settled

Incoming transfer notifications are sent to your endpoint at `{merchant_base_URL}/v1/banking/transfers`. See [Webhook Notifications](https://docs.y.uno/reference/banking-connectivity/webhooks/webhook-notifications-banking.md) for the payload structure.

## Error codes

| Code | HTTP Status | Description |
| - | - | - |
| `NOT_AUTHENTICATED` | 401 | Missing or invalid API keys |
| `AuthenticationFail` | 401 | Authentication failed |
| `BadRequest` | 400 | Malformed request |
| `VALIDATION_ERROR` | 400 | Request validation failed |
| `DUPLICATE_ENTITY` | 409 | Entity with this `merchant_entity_id` already exists |
| `ENTITY_NOT_FOUND` | 404 | Entity not found |
| `ONBOARDING_NOT_FOUND` | 404 | Onboarding not found |
| `ACCOUNT_NOT_FOUND` | 404 | Account not found |
| `INSUFFICIENT_BALANCE` | 422 | Insufficient funds for transfer |
| `CURRENCY_MISMATCH` | 422 | Transfer currency does not match account currency |
| `PROVIDER_ERROR` | 502 | Error from the banking provider |
| `PROVIDER_TIMEOUT` | 504 | Provider did not respond in time |
| `InternalError` | 500 | Internal server error |
| `TooManyRequests` | 429 | Rate limit exceeded |

Error responses follow this format:

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