Managing bank accounts and debit cards

Managing bank accounts and debit cards on your Custom connected accounts.

Bank account formats by country

When attaching bank accounts to Custom accounts, your platform needs to provide an account_number and, in some countries, a routing_number. Every country has a slightly different format for these numbers, and entering them incorrectly causes subsequent payouts to fail.

Stripe recommends creating validations in your bank account entry forms that enforce the required formats based on the country of the Custom account’s bank. In some countries, separate pieces of information—for example, the bank code and branch codes—must be combined to create a routing number.

Bank account information	Example data
BSB	123456 (6 characters)
Account number	12345678 (5–9 characters)

Managing bank accounts and debit cards

Express and Custom accounts have an external_accounts property: a list of all bank accounts and debit cards associated with the Stripe account. Any external account is a possible destination for funds.

Platforms can view the external accounts for its connected Express accounts. Platforms can update the external accounts for its Custom accounts.

{
  ...
  "external_accounts": {
    "object": "list",
    "has_more": false,
    "url": "/v1/accounts/acct_14qyt6Alijdnw0EA/external_accounts",
    "data": [
      {
        "id": "ba_18u1IUJ6m0aiknMBHFQaTWOj",
        "object": "bank_account",
        "account": "acct_18rsqhJ6m0aiknMB",
        "account_holder_name": "Jane Austen",
        "account_holder_type": "individual",
        "bank_name": "STRIPE TEST BANK",
        "country": "US",
        "currency": "usd",
        "default_for_currency": false,
        "fingerprint": "sSZ2yLp0EZTH17cF",
        "last4": "6789",
        "metadata": {
        },
        "routing_number": "110000000",
        "status": "new"
      },
      {...},
      {...},
    ],
  ...
}

Destination accounts are added via the external_accounts parameter when creating or updating Custom accounts. The value should be a bank account or debit card token returned from Stripe.js. Alternatively, you can provide a hash of the bank account details, but using Stripe.js is preferred as it prevents sensitive data from hitting your server.

When using debit cards as a payout destination, the following restrictions apply:

Must be a non-prepaid U.S. Visa, Mastercard, or Discover
Limited to 9,999 USD per payout on Instant Payouts
Generally limited to 3,000 USD per payout otherwise

Also, Stripe can’t perform a negative payout against a debit card to correct a negative Stripe account balance.

Managing multiple bank and debit accounts

By default, providing a new value for external_accounts while updating a Custom account replaces the existing account with the new one. To add additional bank accounts or debit cards to a connected account, use the Bank Account and Card creation API endpoints.

Terminal

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}}/external_accounts \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "external_account"="btok_9CUINZPUJnubtQ"

When working with multiple currencies, Stripe automatically sends payouts to an associated bank account or debit card for its currency to avoid exchange fees. When there are multiple accounts available for a given currency, Stripe uses the one set as default_for_currency.