Banking Connectivity - Yuno API Documentation

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:

Create an entity: Register an individual or business using Create Entity.
Onboard the entity: Submit KYC/KYB documentation through Create Entity Onboarding.
Wait for onboarding approval: Monitor the onboarding status via Get Entity Onboarding Status or listen for webhook events.
Create a bank account: Once onboarding succeeds, open an account with Create Account.
Initiate transfers: Send funds using Initiate Entity Transfer.

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: 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 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:

{
  "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.

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 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:

{
  "code": "ERROR_CODE",
  "messages": ["Human-readable error message"],
  "http_code": 400
}

​Integration flow

​Entity types

​Onboarding types

​Onboarding statuses

​Transfer statuses

​Payment rails

​Account identifiers by region

​Documentation types

​Webhook events

​Entity events

​Onboarding events

​Account events

​Transfer events (outgoing)

​Transfer events (incoming)

​Error codes

Integration flow

Entity types

Onboarding types

Onboarding statuses

Transfer statuses

Payment rails

Account identifiers by region

Documentation types

Webhook events

Entity events

Onboarding events

Account events

Transfer events (outgoing)

Transfer events (incoming)

Error codes