> ## Documentation Index > Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt > Use this file to discover all available pages before exploring further. # Link a bank account > Save a bank beneficiary under a UPA using its country-specific fields. Read [bank account requirements](/api-reference/bank-accounts/get-bank-account-requirements) first for each country's fields and current availability. Linking is implemented for the United States, the Philippines and Vietnam; the other country variants in the request schema describe planned inputs and stay unavailable. An individual UPA needs approved KYC. A business UPA can link a US/USD bank after hosted KYB and provider approval. Both require an enabled linked-bank route. A linked bank is a saved beneficiary and can belong to a supplier, contractor or the UPA subject. Linking does not prove ownership by the UPA subject. | Country | On link | | - | - | | US | Provisioned with the provider. Routing, account type and address fields are part of the encrypted payload. | | PH | Stays pending verification. Bank directory membership never verifies account ownership. | | VN | The beneficiary is verified with the provider. | All normalized bank details are stored with KMS-backed envelope encryption. Raw bank details and encrypted storage metadata are never returned. Linking does not enable payout or settlement execution. `Idempotency-Key` is required and must contain 1–256 characters after trimming surrounding whitespace. Preserve the original body and key after an uncertain response; changed input conflicts. See [Off-ramps](/payments/off-ramps). ## OpenAPI ````yaml openapi.json POST /v2/accounts/{accountId}/bank-accounts openapi: 3.1.0 info: title: Stableyard Partner API version: 2.0.0-staging x-stableyard-api-version: '2026-09-09' x-stableyard-supported-api-versions: - '2026-09-09' summary: Backend API for UPAs, Payments, activity, and optional financial products. description: > Use this API from a trusted partner backend with an app ID and app secret. ## Recommended integration 1. Call `GET /v2/partners/config` to verify credentials and discover enabled capabilities. 2. Create a UPA only when your product needs a persistent Stableyard account. 3. Create a receive or send Payment with `POST /v2/payments`. 4. Redirect a payer to the returned `paymentUrl` or pass the Payment credentials to an official Stableyard interface SDK. 5. Process signed webhooks and fetch the Payment by ID for reconciliation. Checkout execution and account-bound browser endpoints are intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner servers: - url: https://prod-api.stableyard.fi description: Production - url: https://staging-api-v2.stableyard.fi description: Staging - url: http://localhost:3001 description: Local security: [] tags: - name: Authentication x-displayName: API authentication description: Verify your app ID and app secret before calling UPA APIs. - name: Accounts x-displayName: UPA Accounts description: Create Universal Payment Accounts and manage account settings. - name: Deposit Addresses description: Create reusable receive addresses and verify inbound deposits. - name: Identity & KYC description: >- Verify the UPA email and run provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac controlled stablecoin vaults and manage policy updates for accounts. - name: Payments description: >- Create escrow-first payments, issue partner-authenticated send instructions or executions, power public checkout, and reconcile collection through final account settlement. - name: Balances & Transactions description: >- Read Stableyard-posted financial activity. Balances are ledger projections of activity Stableyard processed; they are not live balances of externally controlled wallets. paths: /v2/accounts/{accountId}/bank-accounts: post: tags: - Accounts summary: Link a bank account using its country-specific fields description: >- Read bank-account-requirements for country-specific fields and availability. US, Philippines and Vietnam linking implementations are supported; other profiles describe planned inputs and remain unavailable. An individual UPA needs approved KYC; a business UPA can link a US/USD bank after hosted KYB and provider approval. Both require an enabled linked-bank route. A linked bank is a saved beneficiary, including a supplier, contractor or the UPA subject's own bank; linking does not prove ownership by the UPA subject. All US/PH/VN normalized bank details are stored with KMS-backed envelope encryption; US additionally uses provider provisioning. US routing, account-type and address fields are included in the encrypted payload. Philippines links stay pending verification; directory membership never verifies account ownership. Vietnam uses provider beneficiary verification. Linking does not enable payout or settlement execution. Raw bank details and encrypted storage metadata are never returned. Reuse the same Idempotency-Key with identical normalized input; changed input conflicts. operationId: createBankAccountByAccountId parameters: - name: accountId in: path required: true schema: type: string example: acct_123 description: Canonical account id returned by the Accounts API. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 256 example: bank-beneficiary-supplier-123 description: >- Required retry key for linking a bank account or rail identifier: 1-256 characters after trimming surrounding whitespace. Retry the identical request with the same key; changed input returns a conflict. - name: Stableyard-Version in: header required: false schema: type: string enum: - '2026-09-09' description: >- Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBankAccountRequest' examples: usdBankAccount: summary: US checking account value: accountHolderName: Alice Doe beneficiaryType: individual country: US currency: USD bankName: Example Bank accountNumber: '000123456789' accountType: checking routing: type: aba routingNumber: '021000021' rail: ach beneficiaryAddress: street1: 1 Market Street city: San Francisco region: CA postalCode: '94105' country: US bankAddress: street1: 270 Park Avenue city: New York region: NY postalCode: '10017' country: US philippinesBankAccount: summary: Philippines account saved pending verification description: >- Synthetic bank values. Replace bankCode and bankName with a matching pair from the account-scoped linked-bank directory. value: country: PH currency: PHP accountHolderName: Test Person beneficiaryType: individual bankName: Test Bank bankCode: directory_code accountNumber: '0000123456' rail: bank_transfer vietnamBankAccount: summary: Vietnam account with standalone beneficiary verification description: >- Synthetic bank values. Use a Vietnam directory entry and the registered beneficiary name. Requires an enabled production bank route. value: country: VN currency: VND accountHolderName: TEST PERSON beneficiaryType: individual bankName: Test Bank bankCode: directory_code accountNumber: '0000123456' rail: bank_transfer responses: '201': description: Linked bank account headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/CreateBankAccountResponse' examples: linkedBankAccount: summary: Provider linked; settlement execution not yet enabled value: bankAccount: id: bank_account_123 accountId: acct_123 accountHolderName: Alice Doe country: US currency: USD bankName: Example Bank accountNumberLast4: '1234' rail: ach status: active verification: version: 1 verifiedAt: '2026-09-01T10:00:00.000Z' disabledAt: null createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' settlementDestination: id: destination_123 accountId: acct_123 type: bank_account status: restricted preferred: false capabilities: directions: - receive settlementSupported: false unavailableReason: linked_bank_receive_settlement_not_enabled country: US currency: USD rail: ach resource: type: bank_account bankAccount: id: bank_account_123 accountId: acct_123 accountHolderName: Alice Doe country: US currency: USD bankName: Example Bank accountNumberLast4: '1234' rail: ach status: active verification: version: 1 verifiedAt: '2026-09-01T10:00:00.000Z' disabledAt: null createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' disabledAt: null createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' provisioning: providerProvisioningCompleted: true settlementReady: false nextAction: type: none '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '424': $ref: '#/components/responses/FailedDependency' '429': $ref: '#/components/responses/TooManyRequests' security: - partnerBasicAuth: [] components: schemas: CreateBankAccountRequest: description: >- Country-specific bank inputs. Planned country profiles remain unavailable until their compatible provider adapter and route are enabled. Shortcut identifiers require separate rail integration. oneOf: - type: object additionalProperties: false properties: country: type: string const: US currency: type: string const: USD accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankName: type: string title: Bank name minLength: 1 maxLength: 160 accountNumber: type: string title: Account number minLength: 4 maxLength: 17 pattern: ^[0-9]{4,17}$ writeOnly: true x-normalize: digits accountType: type: string title: Account type enum: - checking - savings routing: type: object additionalProperties: false properties: type: type: string const: aba routingNumber: type: string title: ABA routing number minLength: 9 maxLength: 9 pattern: ^[0-9]{9,9}$ writeOnly: true x-normalize: digits description: >- Use the routing number for the selected ACH, Fedwire, or FedNow rail. required: - type - routingNumber rail: type: string title: Rail enum: - ach - fedwire - fednow default: ach beneficiaryAddress: type: object additionalProperties: false properties: street1: type: string title: Street minLength: 1 maxLength: 160 street2: type: string title: Street 2 minLength: 1 maxLength: 160 city: type: string title: City minLength: 1 maxLength: 100 region: type: string title: State / region minLength: 1 maxLength: 100 postalCode: type: string title: Postal code minLength: 1 maxLength: 24 country: type: string title: Country code minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ x-normalize: uppercase required: - street1 - city - region - postalCode - country title: Beneficiary address bankAddress: type: object additionalProperties: false properties: street1: type: string title: Street minLength: 1 maxLength: 160 street2: type: string title: Street 2 minLength: 1 maxLength: 160 city: type: string title: City minLength: 1 maxLength: 100 region: type: string title: State / region minLength: 1 maxLength: 100 postalCode: type: string title: Postal code minLength: 1 maxLength: 24 country: type: string title: Country code minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ x-normalize: uppercase required: - street1 - city - region - postalCode - country title: Bank address required: - country - currency - accountHolderName - bankName - accountNumber - accountType - routing - beneficiaryAddress - bankAddress title: United States bank account - type: object additionalProperties: false properties: country: type: string const: PH currency: type: string const: PHP accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankName: type: string title: Bank name minLength: 1 maxLength: 160 bankCode: type: string title: Bank code minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ x-bank-directory: true accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits rail: type: string const: bank_transfer default: bank_transfer required: - country - currency - accountHolderName - bankName - bankCode - accountNumber title: Philippines bank account - type: object additionalProperties: false properties: country: type: string const: VN currency: type: string const: VND accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 x-normalize: vietnam_name beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankName: type: string title: Bank name minLength: 1 maxLength: 160 bankCode: type: string title: Bank code minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ x-bank-directory: true accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits rail: type: string const: bank_transfer default: bank_transfer required: - country - currency - accountHolderName - bankName - bankCode - accountNumber title: Vietnam bank account - type: object additionalProperties: false properties: country: type: string const: AR currency: type: string const: ARS accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual cbu: type: string title: CBU minLength: 22 maxLength: 22 pattern: ^[0-9]{22,22}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - cbu title: Argentina bank account - type: object additionalProperties: false properties: country: type: string const: AU currency: type: string const: AUD accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bsb: type: string title: BSB minLength: 6 maxLength: 6 pattern: ^[0-9]{6,6}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bsb - accountNumber title: Australia bank account - type: object additionalProperties: false properties: country: type: string const: BR currency: type: string const: BRL accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankCode: type: string title: Bank code minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits branchCode: type: string title: Agência minLength: 4 maxLength: 4 pattern: ^[0-9]{4,4}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Conta minLength: 1 maxLength: 34 writeOnly: true taxId: type: string title: CPF / CNPJ minLength: 11 maxLength: 14 pattern: ^(?:[0-9]{11}|[0-9]{14})$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bankCode - branchCode - accountNumber - taxId title: Brazil bank account - type: object additionalProperties: false properties: country: type: string const: CA currency: type: string const: CAD accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual institutionNumber: type: string title: Institution number minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits transitNumber: type: string title: Transit number minLength: 5 maxLength: 5 pattern: ^[0-9]{5,5}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - institutionNumber - transitNumber - accountNumber title: Canada bank account - type: object additionalProperties: false properties: country: type: string const: CN currency: type: string const: CNY accountHolderName: type: string title: Recipient name in Chinese minLength: 1 maxLength: 160 description: Match the bank-registered Chinese name; do not transliterate. beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits bankName: type: string title: Bank name minLength: 1 maxLength: 160 branchName: type: string title: Branch name minLength: 1 maxLength: 160 cnaps: type: string title: CNAPS interbank code minLength: 12 maxLength: 12 pattern: ^[0-9]{12,12}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - accountNumber - bankName - branchName - cnaps title: China bank account - type: object additionalProperties: false properties: country: type: string const: FR currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 27 maxLength: 27 pattern: ^FR[0-9]{2}[A-Z0-9]{23}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: France bank account - type: object additionalProperties: false properties: country: type: string const: DE currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 22 maxLength: 22 pattern: ^DE[0-9]{2}[A-Z0-9]{18}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Germany bank account - type: object additionalProperties: false properties: country: type: string const: IT currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 27 maxLength: 27 pattern: ^IT[0-9]{2}[A-Z0-9]{23}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Italy bank account - type: object additionalProperties: false properties: country: type: string const: IN currency: type: string const: INR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits ifsc: type: string title: IFSC minLength: 1 maxLength: 11 pattern: ^[A-Z]{4}0[A-Z0-9]{6}$ x-normalize: uppercase required: - country - currency - accountHolderName - accountNumber - ifsc title: India bank account - type: object additionalProperties: false properties: country: type: string const: ID currency: type: string const: IDR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankCode: type: string title: Bank code minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bankCode - accountNumber title: Indonesia bank account - type: object additionalProperties: false properties: country: type: string const: JP currency: type: string const: JPY accountHolderName: type: string title: Recipient name in katakana minLength: 1 maxLength: 160 description: >- Match the bank-registered katakana name exactly; do not normalize or transliterate. beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankCode: type: string title: Bank code minLength: 4 maxLength: 4 pattern: ^[0-9]{4,4}$ writeOnly: true x-normalize: digits branchCode: type: string title: Branch code minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits accountType: type: string title: Account type enum: - futsu - toza accountNumber: type: string title: Account number minLength: 7 maxLength: 7 pattern: ^[0-9]{7,7}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bankCode - branchCode - accountType - accountNumber title: Japan bank account - type: object additionalProperties: false properties: country: type: string const: MX currency: type: string const: MXN accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual clabe: type: string title: CLABE minLength: 18 maxLength: 18 pattern: ^[0-9]{18,18}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - clabe title: Mexico bank account - type: object additionalProperties: false properties: country: type: string const: RU currency: type: string const: RUB accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: Account number minLength: 20 maxLength: 20 pattern: ^[0-9]{20,20}$ writeOnly: true x-normalize: digits bik: type: string title: BIK minLength: 9 maxLength: 9 pattern: ^[0-9]{9,9}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - accountNumber - bik title: Russia bank account - type: object additionalProperties: false properties: country: type: string const: SA currency: type: string const: SAR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^SA[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Saudi Arabia bank account - type: object additionalProperties: false properties: country: type: string const: ZA currency: type: string const: ZAR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits branchCode: type: string title: Branch code minLength: 6 maxLength: 6 pattern: ^[0-9]{6,6}$ writeOnly: true x-normalize: digits accountType: type: string title: Account type enum: - checking - savings - transmission required: - country - currency - accountHolderName - accountNumber - branchCode - accountType title: South Africa bank account - type: object additionalProperties: false properties: country: type: string const: KR currency: type: string const: KRW accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 description: Match the bank-registered name exactly. beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankCode: type: string title: Bank code minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bankCode - accountNumber title: South Korea bank account - type: object additionalProperties: false properties: country: type: string const: TR currency: type: string const: TRY accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 26 maxLength: 26 pattern: ^TR[0-9]{2}[A-Z0-9]{22}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Turkey bank account - type: object additionalProperties: false properties: country: type: string const: GB currency: type: string const: GBP accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual sortCode: type: string title: Sort code minLength: 6 maxLength: 6 pattern: ^[0-9]{6,6}$ writeOnly: true x-normalize: digits accountNumber: type: string title: Account number minLength: 8 maxLength: 8 pattern: ^[0-9]{8,8}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - sortCode - accountNumber title: United Kingdom bank account - type: object additionalProperties: false properties: country: type: string const: SG currency: type: string const: SGD accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual bankName: type: string title: Bank name minLength: 1 maxLength: 160 accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits rail: type: string title: Rail enum: - fast - giro default: fast bankCode: type: string title: Bank code minLength: 4 maxLength: 4 pattern: ^[0-9]{4,4}$ writeOnly: true x-normalize: digits description: The provider may resolve this from the selected bank. branchCode: type: string title: Branch code minLength: 3 maxLength: 3 pattern: ^[0-9]{3,3}$ writeOnly: true x-normalize: digits required: - country - currency - accountHolderName - bankName - accountNumber title: Singapore bank account - type: object additionalProperties: false properties: country: type: string const: NG currency: type: string const: NGN accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: NUBAN minLength: 10 maxLength: 10 pattern: ^[0-9]{10,10}$ writeOnly: true x-normalize: digits bankName: type: string title: Bank name minLength: 1 maxLength: 160 bankCode: type: string title: Bank code minLength: 1 maxLength: 64 required: - country - currency - accountHolderName - accountNumber - bankName - bankCode title: Nigeria bank account - type: object additionalProperties: false properties: country: type: string const: KE currency: type: string const: KES accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual accountNumber: type: string title: Account number minLength: 4 maxLength: 34 pattern: ^[0-9]{4,34}$ writeOnly: true x-normalize: digits bankName: type: string title: Bank name minLength: 1 maxLength: 160 bankCode: type: string title: Bank code minLength: 1 maxLength: 64 branchCode: type: string title: Branch code minLength: 1 maxLength: 64 required: - country - currency - accountHolderName - accountNumber - bankName - bankCode - branchCode title: Kenya bank account - type: object additionalProperties: false properties: country: type: string const: EG currency: type: string const: EGP accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 29 maxLength: 29 pattern: ^EG[0-9]{2}[A-Z0-9]{25}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Egypt bank account - type: object additionalProperties: false properties: country: type: string const: MU currency: type: string const: MUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 30 maxLength: 30 pattern: ^MU[0-9]{2}[A-Z0-9]{26}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Mauritius bank account - type: object additionalProperties: false properties: country: type: string const: AT currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 20 maxLength: 20 pattern: ^AT[0-9]{2}[A-Z0-9]{16}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Austria bank account - type: object additionalProperties: false properties: country: type: string const: BE currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 16 maxLength: 16 pattern: ^BE[0-9]{2}[A-Z0-9]{12}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Belgium bank account - type: object additionalProperties: false properties: country: type: string const: BG currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 22 maxLength: 22 pattern: ^BG[0-9]{2}[A-Z0-9]{18}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Bulgaria bank account - type: object additionalProperties: false properties: country: type: string const: HR currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 21 maxLength: 21 pattern: ^HR[0-9]{2}[A-Z0-9]{17}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Croatia bank account - type: object additionalProperties: false properties: country: type: string const: CY currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 28 maxLength: 28 pattern: ^CY[0-9]{2}[A-Z0-9]{24}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Cyprus bank account - type: object additionalProperties: false properties: country: type: string const: CZ currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^CZ[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Czechia bank account - type: object additionalProperties: false properties: country: type: string const: DK currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 18 maxLength: 18 pattern: ^DK[0-9]{2}[A-Z0-9]{14}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Denmark bank account - type: object additionalProperties: false properties: country: type: string const: EE currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 20 maxLength: 20 pattern: ^EE[0-9]{2}[A-Z0-9]{16}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Estonia bank account - type: object additionalProperties: false properties: country: type: string const: FI currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 18 maxLength: 18 pattern: ^FI[0-9]{2}[A-Z0-9]{14}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Finland bank account - type: object additionalProperties: false properties: country: type: string const: GR currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 27 maxLength: 27 pattern: ^GR[0-9]{2}[A-Z0-9]{23}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Greece bank account - type: object additionalProperties: false properties: country: type: string const: HU currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 28 maxLength: 28 pattern: ^HU[0-9]{2}[A-Z0-9]{24}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Hungary bank account - type: object additionalProperties: false properties: country: type: string const: IE currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 22 maxLength: 22 pattern: ^IE[0-9]{2}[A-Z0-9]{18}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Ireland bank account - type: object additionalProperties: false properties: country: type: string const: LV currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 21 maxLength: 21 pattern: ^LV[0-9]{2}[A-Z0-9]{17}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Latvia bank account - type: object additionalProperties: false properties: country: type: string const: LT currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 20 maxLength: 20 pattern: ^LT[0-9]{2}[A-Z0-9]{16}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Lithuania bank account - type: object additionalProperties: false properties: country: type: string const: LU currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 20 maxLength: 20 pattern: ^LU[0-9]{2}[A-Z0-9]{16}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Luxembourg bank account - type: object additionalProperties: false properties: country: type: string const: MT currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 31 maxLength: 31 pattern: ^MT[0-9]{2}[A-Z0-9]{27}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Malta bank account - type: object additionalProperties: false properties: country: type: string const: NL currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 18 maxLength: 18 pattern: ^NL[0-9]{2}[A-Z0-9]{14}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Netherlands bank account - type: object additionalProperties: false properties: country: type: string const: PL currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 28 maxLength: 28 pattern: ^PL[0-9]{2}[A-Z0-9]{24}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Poland bank account - type: object additionalProperties: false properties: country: type: string const: PT currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 25 maxLength: 25 pattern: ^PT[0-9]{2}[A-Z0-9]{21}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Portugal bank account - type: object additionalProperties: false properties: country: type: string const: RO currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^RO[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Romania bank account - type: object additionalProperties: false properties: country: type: string const: SK currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^SK[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Slovakia bank account - type: object additionalProperties: false properties: country: type: string const: SI currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 19 maxLength: 19 pattern: ^SI[0-9]{2}[A-Z0-9]{15}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Slovenia bank account - type: object additionalProperties: false properties: country: type: string const: ES currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^ES[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Spain bank account - type: object additionalProperties: false properties: country: type: string const: SE currency: type: string const: EUR accountHolderName: type: string title: Recipient name minLength: 1 maxLength: 160 beneficiaryType: type: string title: Beneficiary type enum: - individual - business default: individual iban: type: string title: IBAN minLength: 24 maxLength: 24 pattern: ^SE[0-9]{2}[A-Z0-9]{20}$ writeOnly: true x-normalize: iban required: - country - currency - accountHolderName - iban title: Sweden bank account discriminator: propertyName: country CreateBankAccountResponse: type: object additionalProperties: false required: - bankAccount - settlementDestination - provisioning properties: bankAccount: $ref: '#/components/schemas/BankAccount' settlementDestination: $ref: '#/components/schemas/SettlementDestination' provisioning: type: object additionalProperties: false required: - providerProvisioningCompleted - settlementReady - nextAction properties: providerProvisioningCompleted: type: boolean description: >- True after the provider customer and bank destination are durably linked. settlementReady: type: boolean description: >- True only when Stableyard can execute and reconcile payouts to this destination. nextAction: type: object additionalProperties: true required: - type properties: type: type: string enum: - none - complete_provider_onboarding - contact_support url: type: string format: uri description: >- Short-lived provider-hosted onboarding URL. Returned only in the current response when action is required. expiresAt: type: - string - 'null' format: date-time BankAccount: type: object additionalProperties: false required: - id - accountId - accountHolderName - country - currency - bankName - accountNumberLast4 - rail - status - verification - disabledAt - createdAt - updatedAt properties: id: type: string example: bank_account_123 accountId: type: string example: acct_123 accountHolderName: type: string example: Alice Doe country: type: string pattern: ^[A-Z]{2}$ example: US currency: type: string pattern: ^[A-Z]{3}$ example: USD bankName: type: string example: Example Bank bankCode: type: string maxLength: 64 description: >- Public country-directory bank code when supplied for a local bank link. accountNumberLast4: type: string example: '1234' rail: type: - string - 'null' example: ach status: type: string enum: - pending_verification - active - restricted - disabled verification: type: object additionalProperties: false required: - version - verifiedAt properties: version: type: integer minimum: 0 verifiedAt: type: - string - 'null' format: date-time disabledAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time SettlementDestination: type: object additionalProperties: false required: - id - accountId - type - status - preferred - capabilities - resource - disabledAt - createdAt - updatedAt properties: id: type: string example: destination_123 accountId: type: string example: acct_123 type: type: string enum: - crypto_wallet - bank_account - payment_rail_identifier example: crypto_wallet status: type: string enum: - pending_verification - active - restricted - disabled example: active preferred: type: boolean capabilities: type: object additionalProperties: true description: >- Immutable-at-selection capability projection. `settlementSupported` must be true before this destination can be selected. example: directions: - receive settlementSupported: true unavailableReason: null network: code: base chainId: 8453 chainFamily: evm assets: - symbol: USDC tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' decimals: 6 resource: type: object additionalProperties: true description: >- Privacy-safe projection of the linked wallet, bank account, or rail identifier. Provider tokens are never returned. example: type: crypto_wallet connectedWalletId: wallet_123 chainId: 8453 address: '0x1111111111111111111111111111111111111111' walletKind: external label: Primary wallet ownershipVerificationStatus: unverified disabledAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string minLength: 1 maxLength: 128 example: bad_request message: type: string minLength: 1 maxLength: 1000 example: The request is invalid details: {} responses: BadRequest: description: Bad request headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: BadRequest response value: error: code: bad_request message: The request is invalid details: example Unauthorized: description: Unauthorized headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Unauthorized response value: error: code: bad_request message: The request is invalid details: example Forbidden: description: The app secret does not include the required scope headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Forbidden response value: error: code: bad_request message: The request is invalid details: example NotFound: description: Not found headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: NotFound response value: error: code: bad_request message: The request is invalid details: example Conflict: description: Conflict headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Conflict response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' Retry-After: description: Seconds until the caller should retry. schema: type: integer minimum: 1 RateLimit-Limit: description: Quota for the most constrained policy. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requests remaining in that policy window. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until that policy window resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example securitySchemes: partnerBasicAuth: type: http scheme: basic description: >- HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.