External Bank Accounts

BETA: This endpoint is subject to change without notice.

An external bank account is a payout destination — the bank account where funds are sent when a payout is created. Each account must register at least one external bank account before it can pay out.

Supported bank detail schemes

Scheme	Fields	Typical usage
GB	Sort code (6 digits) + account number (8 digits)	UK domestic, GBP
IBAN	IBAN (up to 34 characters)	SEPA/EUR and other IBAN-adopting countries
US	ABA routing number (9 digits) + account number (4–17 digits)	US domestic, USD

Creating an external bank account

API reference

UK (GB) example

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/external-bank-accounts \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_bank_account": {
      "country": "GB",
      "currency": "GBP",
      "account_holder_name": "Example Ltd",
      "account_holder_type": "BUSINESS",
      "gb_bank_details": {
        "sort_code": "040004",
        "account_number": "12345678"
      }
    }
  }'

Response

Verification runs during creation. If it passes (e.g. Confirmation of Payee succeeds for a UK account), the external bank account is returned as ACTIVE:

{
  "name": "accounts/acct_YOUR_ACCOUNT/external-bank-accounts/ba_BANK_ACCOUNT_ID",
  "state": "ACTIVE",
  "country": "GB",
  "currency": "GBP",
  "account_holder_name": "Example Ltd",
  "account_holder_type": "BUSINESS",
  "bank_details_type": "GB",
  "gb_bank_details": {
    "sort_code": "040004",
    "account_number": "12345678"
  },
  "verification": {
    "state": "VERIFIED",
    "gb_cop": {
      "state": "VERIFIED"
    }
  },
  "create_time": "2026-01-15T10:30:00Z",
  "update_time": "2026-01-15T10:30:00Z"
}

If verification fails, the state will be REQUIRES_VERIFICATION with verification.state of ASSERTED. See the Verification section below for details.

IBAN example

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/external-bank-accounts \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_bank_account": {
      "country": "DE",
      "currency": "EUR",
      "account_holder_name": "Beispiel GmbH",
      "account_holder_type": "BUSINESS",
      "iban_bank_details": {
        "iban": "DE89370400440532013000"
      }
    }
  }'

Key fields

Field	Description
`country`	ISO 3166-1 alpha-2 country code (required)
`currency`	ISO 4217 currency code (required)
`account_holder_name`	Name of the account holder
`account_holder_type`	`PERSON` or `BUSINESS`
`bank_details_type`	Which bank detail scheme is set: `GB`, `IBAN`, or `US` (output only)
`metadata`	Key-value pairs for your own use (max 50 keys, key max 40 chars, value max 500 chars)

Verification lifecycle

Verification runs automatically when you create an external bank account. For UK accounts, this includes a Confirmation of Payee check.

EBA state	Verification state	CoP state (UK only)	What happens next
`REQUIRES_VERIFICATION`	`ASSERTED`	`FAILED`	CoP failed — create a new EBA with corrected details
`ACTIVE`	`VERIFIED`	`VERIFIED`	Ready to receive payouts
`ACTIVE`	`VERIFIED`	`UNAVAILABLE`	CoP not applicable — verified by other means

Verification typically completes inline during creation, so the response usually shows ACTIVE directly. If verification fails, the EBA remains in REQUIRES_VERIFICATION — it cannot receive payouts.

Once an external bank account reaches ACTIVE, it is immutable — you cannot update its details. If the details are incorrect, create a new external bank account.

UK Confirmation of Payee

For GB/GBP accounts, Synapto performs a Confirmation of Payee (CoP) check to verify that the account holder name matches the bank's records. If CoP fails, the verification.gb_cop.suggested_account_holder_name field may contain the correct name to use.

Listing external bank accounts

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/external-bank-accounts:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Webhooks

When an external bank account is created, an account.external_bank_account.created event is sent to your webhook endpoints. See Webhooks for setup instructions.