External accounts

External accounts represent payout destinations for a connected account.

These are typically bank accounts where funds are transferred.

Usage

External accounts are used to:

Receive payouts
Define settlement destinations

Flow

Collect bank details from the user

Collect required payout information such as IBAN, account holder name, and country.

Create an external account

Submit the payout details to the API to create an external account resource.

Attach it to the connected account

Associate the external account with the connected account so it can receive payouts.

Create an external account

Create a payout destination for a connected account.

POST /v1/accounts/{account_id}/external_accounts

{
  "type": "bank_account",
  "iban": "BG80BNBG96611020345678"
}

Response

{
  "id": "01KMQ9MWSYN5WV6WN58YCKTQWW",
  "object": "external_account",
  "type": "bank_account",
  "currency": "EUR",
  "country": "BG",
  "last4": "5678",
  "status": "verified"
}

Default payout account

If multiple external accounts are attached, one can be used as the default for a given currency.

The default account is used automatically for payouts unless specified otherwise.

Updating external accounts

Some external account fields can be updated after creation, such as:

Account holder name
Metadata

However, core banking details (such as IBAN) are typically immutable.

To change them, create a new external account and replace the existing one.

Verification

External accounts may require verification depending on:

Country
Currency
Regulatory requirements

Verification may include:

Bank account validation
Micro-deposits
Document verification

If verification fails, the account will appear in requirements and must be corrected.

Failure handling

Payouts can fail due to:

Invalid bank details
Closed or restricted accounts
Currency mismatches

Overview