> ## Documentation Index > Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Register a payout bank account > Allow-list a beneficiary bank account as a pay-out destination for a party. **Requires scope:** `manage:pay-outs` — see [Required scopes](/getting-started/authentication#required-scopes-finance-api). Allow-lists a beneficiary bank account so it can receive pay-outs. The owning party comes from the path, never the body. This is the **only** endpoint that accepts raw rail credentials. The account number is KMS-encrypted at rest immediately on persistence and is never returned — this response and every read path expose only `accountNumberLast4`. The ABA routing number is a public bank identifier and is returned in full. `bankAddress` is the **beneficiary bank's** postal address, not the recipient's. All components are required, and `country` must be a valid ISO 3166-1 alpha-2 code. The initial supported rail is `US_ACH`, which requires `fiatCurrency: USD`. A new account starts `PENDING` and becomes `ACTIVE` once activated for pay-outs. Next: pair it with a deposit asset by [creating a payout route](/api-reference/Finance-API/payout-routes/create-a-payout-route). ## Errors The codes this endpoint can return, in addition to the [standard errors](/guides/finance/errors#standard-errors). Branch on `code`, never the message. | HTTP | `code` | When | | ----- | ------------------------ | --------------------------------------------------------------------------------------- | | `400` | `invalid-rail` | unsupported rail | | `400` | `invalid-currency` | currency is inconsistent with the rail (`US_ACH` requires `USD`) | | `400` | `missing-field` | a required field is absent | | `400` | `invalid-account-number` | the account number is not 4–17 digits | | `400` | `invalid-routing-number` | the ABA routing number failed its checksum | | `400` | `invalid-account-type` | `accountType` is not `CHECKING` or `SAVINGS` | | `400` | `invalid-bank-address` | a bank-address component is missing or `country` is not a valid ISO 3166-1 alpha-2 code | ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml POST /parties/{partyId}/payout-bank-accounts openapi: 3.1.0 info: title: Venly Finance API description: > REST API for the Venly Finance platform: - Party management (Individuals & Organisations) - Identity verification — hosted KYC/KYB links and Sumsub share-token forwarding - Account management with party association - Wallet balances & token allowances on supported chains - Virtual bank accounts for global pay-in (EUR SEPA, USD ACH/WIRE/RTP/SWIFT) - Fiat-to-crypto payment sessions (pay-in) - Bank pay-outs — beneficiary allow-listing, routes, and PULL/PUSH pay-outs - Account-to-account fiat & crypto transfers - EIP-2612 permits and allowances - Webhook registration for asynchronous event delivery ## Authentication All endpoints use OAuth2 client credentials. Obtain a token first, then include it in every request: **Step 1 — Get a token:** ```bash curl -X POST https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}" ``` **Step 2 — Use the token:** ``` Authorization: Bearer {access_token} ``` Tokens expire after **5 minutes**. Implement refresh logic in your client. version: 1.5.0 contact: name: Venly Support email: support@venly.io url: https://docs.venlyfinance.com license: name: Proprietary x-logo: url: https://venlyfinance.com/logo.png x-security-contact: security@venly.io servers: - url: https://api.venlyfinance.com/v1 description: Production - url: https://api-staging.venlyfinance.com/v1 description: Staging security: - OAuth2: [] tags: - name: Parties description: Party management (Individuals & Organisations) - name: Accounts description: Account management, party-role associations - name: Wallets description: Blockchain wallet balances - name: Virtual Bank Accounts description: Virtual bank account payment references for global payments - name: Fiat-to-crypto Payment Sessions description: Fiat-to-crypto payment session creation - name: Payout Bank Accounts description: Allow-listing beneficiary bank accounts as pay-out destinations - name: Payout Routes description: >- Account-scoped routes pairing a beneficiary bank account with a crypto deposit asset - name: Payouts description: Crypto-to-fiat pay-outs over a registered route - name: Transfers description: Fiat and crypto transfer operations between accounts - name: Permits description: EIP-712 permit signature management for token approvals - name: Supported Assets description: >- Discover which chains and assets your tenant can settle in, and whether an account can use them yet. - name: Allowances description: Token allowance management for wallets - name: Webhooks description: Webhook registration and delivery testing paths: /parties/{partyId}/payout-bank-accounts: post: tags: - Payout Bank Accounts summary: Register a payout bank account description: > **Requires scope:** `manage:pay-outs` Allow-lists a beneficiary bank account as a pay-out destination for the recipient party. This is the **only** endpoint that accepts raw rail credentials. The account number is KMS-encrypted at rest immediately on persistence and is never returned — this response and every read path expose only `accountNumberLast4`. The ABA routing number is a public bank identifier and is returned in full. The owning party comes from the path, never the body. The initial supported rail is `US_ACH`, which requires `fiatCurrency: USD`. A newly registered account starts `PENDING` and becomes `ACTIVE` once activated for pay-outs. operationId: registerPayoutBankAccount parameters: - $ref: '#/components/parameters/PartyId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterPayoutBankAccountRequest' example: rail: US_ACH fiatCurrency: USD label: Jane's checking account accountHolderName: Jane Doe railDetails: accountNumber: '123456789012' abaRoutingNumber: '021000021' accountType: CHECKING bankName: Example National Bank bankAddress: street1: 270 Park Avenue city: New York region: NY postalCode: '10017' country: US responses: '201': description: Bank account registered (masked) content: application/json: schema: $ref: '#/components/schemas/SinglePayoutBankAccountResponse' example: success: true result: id: a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071 partyId: 7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22 rail: US_ACH fiatCurrency: USD label: Jane's checking account accountHolderName: Jane Doe details: accountNumberLast4: '9012' abaRoutingNumber: '021000021' accountType: CHECKING bankName: Example National Bank bankAddress: street1: 270 Park Avenue city: New York region: NY postalCode: '10017' country: US status: PENDING createdAt: '2026-07-14T09:12:44Z' updatedAt: '2026-07-14T09:12:44Z' '400': description: > Invalid request. Possible error codes: - `invalid-rail` — unsupported rail - `invalid-currency` — currency is inconsistent with the rail (`US_ACH` requires `USD`) - `missing-field` — a required field is absent - `invalid-account-number` — the account number is not 4–17 digits - `invalid-routing-number` — the ABA routing number failed its checksum - `invalid-account-type` — `accountType` is not `CHECKING` or `SAVINGS` - `invalid-bank-address` — a bank-address component is missing or `country` is not a valid ISO 3166-1 alpha-2 code content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Forbidden — the caller lacks the `manage:pay-outs` role. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Party not found. Also returned for a party belonging to another company. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: PartyId: name: partyId in: path required: true description: Unique party identifier schema: type: string format: uuid example: 7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22 schemas: RegisterPayoutBankAccountRequest: type: object description: > Allow-lists a beneficiary bank account as a pay-out destination. The owning party comes from the path, never the body. required: - rail - fiatCurrency - label - accountHolderName - railDetails - bankName - bankAddress properties: rail: $ref: '#/components/schemas/PayoutRail' fiatCurrency: type: string maxLength: 3 description: >- ISO 4217 currency. Must be consistent with the rail — `US_ACH` requires `USD`. example: USD label: type: string maxLength: 255 description: Human-readable label for this destination accountHolderName: type: string maxLength: 255 description: Name on the beneficiary bank account railDetails: $ref: '#/components/schemas/UsAchRailDetailsInput' bankName: type: string maxLength: 255 bankAddress: $ref: '#/components/schemas/BankAddress' beneficiaryEmail: type: string format: email maxLength: 255 description: > Beneficiary contact email, forwarded to the payment provider as part of the Travel-Rule record. Optional for providers that do not require it, but some destinations are refused without both a beneficiary email and phone number, so supply both on every bank account you register. When the email is omitted the beneficiary party's email is used as a fallback; the phone number has no such fallback and must be supplied on the bank account itself. A bank account cannot be edited after registration, so if the resolved email or the phone is missing, the route fails terminally with `beneficiary-data-incomplete` and the beneficiary has to be registered again. example: finance@acme.com beneficiaryPhoneNumber: type: string maxLength: 16 pattern: ^\+[1-9][0-9]{7,14}$ description: > Beneficiary contact phone in E.164 form (leading `+`, no spaces or punctuation). Same applicability as `beneficiaryEmail`. Forwarded to the payment provider verbatim and not normalised, so a non-E.164 number is rejected here rather than failing the route registration later. example: '+12125550123' SinglePayoutBankAccountResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: $ref: '#/components/schemas/PayoutBankAccount' ErrorResponse: type: object description: Error response wrapper properties: success: type: boolean description: Always false for error responses example: false errors: type: array description: List of errors that occurred items: $ref: '#/components/schemas/ErrorBody' result: type: object nullable: true description: Null or omitted when success is false PayoutRail: type: string description: | The fiat rail a payout bank account settles over. - `US_ACH` — US ACH transfer. Requires `fiatCurrency: USD`. enum: - US_ACH UsAchRailDetailsInput: type: object description: >- Raw US-ACH rail credentials. Accepted only when registering a payout bank account. required: - accountNumber - abaRoutingNumber - accountType properties: accountNumber: type: string writeOnly: true description: > Bank account number, 4–17 digits. KMS-encrypted at rest immediately on persistence and **never returned** — read paths expose only `accountNumberLast4`. abaRoutingNumber: type: string description: >- 9-digit ABA routing number, validated by checksum. A public bank identifier, returned in full. example: '021000021' accountType: $ref: '#/components/schemas/AchAccountType' BankAddress: type: object description: > Structured postal address of the **beneficiary's bank** — not the recipient's own address. All components are required on registration, and `country` must be a valid ISO 3166-1 alpha-2 code; anything missing or invalid yields `400 invalid-bank-address`. required: - street1 - city - region - postalCode - country properties: street1: type: string maxLength: 255 city: type: string maxLength: 100 region: type: string maxLength: 100 description: State, province or region postalCode: type: string maxLength: 20 country: type: string maxLength: 2 description: ISO 3166-1 alpha-2 country code example: US BaseResponse: type: object properties: success: type: boolean description: Indicates whether the request was successful PayoutBankAccount: type: object description: Masked view of an allow-listed payout bank account. properties: id: type: string format: uuid partyId: type: string format: uuid rail: $ref: '#/components/schemas/PayoutRail' fiatCurrency: type: string label: type: string accountHolderName: type: string details: $ref: '#/components/schemas/MaskedRailDetails' bankName: type: string bankAddress: $ref: '#/components/schemas/BankAddress' status: $ref: '#/components/schemas/PayoutBankAccountStatus' createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorBody: type: object description: Individual error details properties: code: type: string description: Machine-readable error code example: invalid-request message: type: string description: Human-readable error message example: The request contains invalid parameters. AchAccountType: type: string description: >- Type of US-ACH bank account, supplied when registering a payout bank account. enum: - CHECKING - SAVINGS MaskedRailDetails: type: object description: Masked rail credentials, returned on every read path. properties: accountNumberLast4: type: string description: >- Last 4 digits of the account number. The full number is never returned. example: '9012' abaRoutingNumber: type: string description: ABA routing number, returned in full (a public bank identifier). example: '021000021' accountType: $ref: '#/components/schemas/AchAccountType' PayoutBankAccountStatus: type: string description: | Lifecycle status of a payout bank account. - `PENDING` — registered, not yet activated for pay-outs - `ACTIVE` — usable as a pay-out destination - `DISABLED` — no longer usable enum: - PENDING - ACTIVE - DISABLED responses: Unauthorized: description: Authentication required or failed (401) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: unauthenticated message: Please authenticate to perform this action. securitySchemes: OAuth2: type: oauth2 description: > OAuth2 client credentials flow. Token endpoints: - Staging: https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token - Production: https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token flows: clientCredentials: tokenUrl: >- https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token scopes: {} ````