Link a bank account

Save a bank beneficiary under a UPA using its country-specific fields.

POST /v2/accounts/{accountId}/bank-accounts

cURL

usdBankAccount

curl --request POST \ --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/bank-accounts \ --header 'Authorization: Basic <encoded-value>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: <idempotency-key>' \ --data ' { "accountHolderName": "Alice Doe", "beneficiaryType": "individual", "country": "US", "currency": "USD", "bankName": "Example Bank", "accountNumber": "000123456789", "accountType": "checking", "routing": { "type": "aba", "routingNumber": "123456780" }, "rail": "ach", "beneficiaryAddress": { "street1": "1 Market Street", "city": "San Francisco", "region": "CA", "postalCode": "94105", "country": "US" }, "bankAddress": { "street1": "1 Example Plaza", "city": "Springfield", "region": "IL", "postalCode": "62701", "country": "US" } } '

201

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

Read bank account requirements first for each country’s fields and current availability. Linking is available for the United States, the Philippines and Vietnam, and must be enabled for your app. An individual UPA needs approved KYC. A business UPA can link a US/USD bank once its hosted business verification (KYB) is approved.

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	Set up for payouts. Follow provisioning.nextAction; the bank becomes active once provisioning.providerProvisioningCompleted is true.
PH	Stays pending_verification. Choosing a bank from the directory does not verify the account.
VN	The beneficiary is verified when it is linked, and the bank is returned active.

Only a US linked bank can be paid. Once it is active, create a send Payment with destination.type: "bank_account"; see Off-ramps. A linked bank cannot receive settlement.

Full bank details are never returned; responses show accountNumberLast4. 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.

Authorizations

Authorization · string · header · required

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.

Headers

Idempotency-Key · string · required

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.

Required string length: 1 - 256

Example:

"bank-beneficiary-supplier-123"

Stableyard-Version · enum<string>

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.

Available options: 2026-09-09

Path Parameters

accountId · string · required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json

United States bank account

Philippines bank account

Vietnam bank account

Country-specific bank inputs.

country · string · required

Allowed value: "US"

currency · string · required

Allowed value: "USD"

accountHolderName · string · required

Required string length: 1 - 160

bankName · string · required

Required string length: 1 - 160

accountNumber · string · required · write-only

Required string length: 4 - 17

Pattern: ^[0-9]{4,17}$

accountType · enum<string> · required

Available options: checking, savings

routing · object · required

Show child attributes

beneficiaryAddress · Beneficiary address · object · required

Show child attributes

bankAddress · Bank address · object · required

Show child attributes

beneficiaryType · enum<string> · default: individual

Available options: individual, business

rail · enum<string> · default: ach

Available options: ach, fedwire, fednow

Response

201

application/json

Linked bank account

bankAccount · object · required

Show child attributes

settlementDestination · object · required

Show child attributes

provisioning · object · required

Show child attributes