Beneficiary Requirements

Every bank payout requires the beneficiary's core account details: account_holder_name, bank_name, bank_country, currency, and either an account_number or an iban.

Some payout currencies additionally require beneficiary identity details to meet the compliance requirements of our banking partners. Providing these at transfer creation avoids rejected requests.

Enhanced beneficiary detailsCopy Anchor Link

The following applies to payouts in AED, CAD, EUR, GBP, MXN and USD (both local and SWIFT payment methods):

Additional notes:

• CAD (local): the beneficiary address must be in Canada, and bank_code, branch_code and account_type are required.
• USD (local): the beneficiary address must be in the United States, and aba_code and account_type are required.
• These fields are accepted on every currency and ignored where they are not needed, so you can safely collect and submit them for all payouts.

ExampleCopy Anchor Link

{
  "quote_id": "your-quote-id",
  "customer_id": "your-customer-id",
  "destination": {
    "type": "bank",
    "recipient_type": "individual",
    "date_of_birth": "1990-01-15",
    "account_holder_name": "Maria Fischer",
    "iban": "DE89370400440532013000",
    "bank_name": "Deutsche Bank",
    "bank_country": "DE",
    "currency": "EUR",
    "address": {
      "street": "Hauptstrasse 12",
      "city": "Berlin",
      "state": "BE",
      "postal_code": "10115",
      "country": "de"
    }
  }
}

Asian currenciesCopy Anchor Link

Payouts in HKD, IDR, PHP, SGD, THB and VND need a few bank details beyond the core fields. Pick the rail with destination.network on the quote: bank for the local rail, swift for SWIFT.

On the SWIFT rail, every one of these currencies needs swift_code and a full address (street, city, state, postal_code, country). bank_country must be the currency's own country on the local rail.

recipient_type, date_of_birth, phone and identity numbers are not required for these currencies. You can still send them.

Supported bank namesCopy Anchor Link

For IDR, PHP, THB and VND, bank_name must exactly match one of the bank names Stables supports for that currency. There is no bank list endpoint yet. To see the accepted names, validate a destination (below): when the name is not recognised, the error for bank_name lists every accepted name for that currency. Store the list in your product and let customers pick from it.

SWIFT codes and local bank codes are not provided by the API. Collect them from the beneficiary.

Validating a beneficiaryCopy Anchor Link

To check beneficiary details before creating a transfer, use the validation endpoint. It applies the same bank detail rules as transfer creation. Pass the same network as the quote (bank or swift):

POST /api/v1/payment-methods/validate

{
  "network": "bank",
  "destination": {
    "type": "bank",
    "account_holder_name": "Maria Santos",
    "account_number": "1234567890",
    "bank_name": "Banco De Oro Unibank, Inc.",
    "bank_country": "PH",
    "currency": "PHP",
    "swift_code": "BNORPHMM"
  }
}

The response says whether the destination is valid and, if not, which fields to fix.

ErrorsCopy Anchor Link

Missing or invalid bank details return 400 Bad Request with the code TRANSFER_DESTINATION_INVALID and one entry per field in fields:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "The destination is missing or has invalid fields: ...",
  "code": "TRANSFER_DESTINATION_INVALID",
  "fields": [
    { "field": "swift_code", "message": "..." }
  ]
}

Missing enhanced beneficiary details (recipient_type, date_of_birth or address for AED, CAD, EUR, GBP, MXN and USD) return 422 Unprocessable Entity with a message naming the missing field, for example:

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "EUR payouts to individual beneficiaries require destination.date_of_birth (YYYY-MM-DD)"
}