Skip to main content
A bank account is an existing bank beneficiary saved under a Stableyard account as a payout destination. It can belong to a supplier, contractor or the account holder; linking does not prove ownership by the UPA subject. Stableyard does not open it. In the API it is a BankAccount, with an id prefixed bank_account_.

When to use it

Use it for repeated payouts to a saved beneficiary or withdrawals to the customer’s own bank. US payouts require a verified linked bank; one-time US external_bank transfers are not supported. Philippine and Vietnamese payouts use a one-time beneficiary with destination.type: "external_bank" instead. See Sending payments.

Coverage

Other countries return available: false unless Stableyard has enabled linking for your app. A linked bank is a payout destination, not a settlement destination. See Supported regions and currencies.

What linking needs

A payout to the bank needs more: the bank active, and an active linked_bank capability on the account. See Capability activation.

Read the fields for each country

Each entry carries a strict JSON Schema for that country’s fields, shared with server validation. Render your form from schema, and offer a country only when available is true. Each entry also carries alternatives. It is reserved: ignore it.
Stableyard registers the bank with a banking partner. When that completes, the bank is active. If the partner needs the customer to act first, provisioning.nextAction.type is complete_provider_onboarding with a short-lived url, returned only in that response.
  • Raw details never come back. Only the last four digits. Stableyard stores the full details encrypted.
  • settlementReady is false. Linking makes a payout destination, not a settlement destination.
  • Retry with the same key. Idempotency-Key is required and must contain 1–256 characters after trimming surrounding whitespace. The same key with identical input returns the original link, and changed input conflicts.

Statuses

List an account’s banks with GET /v2/accounts/{accountId}/bank-accounts, filtered by status and paged with limit (up to 100, default 20) and cursor. Read one with GET /v2/accounts/{accountId}/bank-accounts/{bankAccountId}.

Disable a bank

Disabling stops future use and keeps the financial history and masked identity. Stableyard deletes the stored details after its retention period. Disabling twice keeps the first date.

Errors

Webhooks

There is no bank-account event. account.updated fires when a bank is linked, verified or disabled; read the bank account for its status.

Next: Wallets and handles

Connected wallets, payment handles and public payment acceptance.