External bank payouts

Send same-currency fiat from a customer account to an outside bank beneficiary (not another Element Pay ledger account).

Flow	Destination
Book transfers	Same-currency account under this API key
Currency conversions	Different-currency account on the same `pcus_*`
Payout	External beneficiary bank
Stablecoin sends	Crypto wallet

Prerequisite: Customers quickstart. Banking gate: products.deposit_account.status=ready. Source account must be status=active for the payout currency.

Preview requires available balance (available >= amount). Confirm on live moves money. Sandbox often cannot complete a full bank push - use discovery + insufficient-balance checks first.

Auth

export BASE="https://sandbox.elementpay.net/api/v1"   # or live / staging base
export API_KEY="is_test_…"                            # or is_live_…
export CUSTOMER_ID="pcus_…"
export ACCOUNT_ID="…"   # fiat account in the payout currency

X-API-Key: <API_KEY>
Content-Type: application/json

Integrator flow (recommended order)

Do not hardcode bank field lists from this guide alone - call discovery first.

Resolve source account

GET …/accounts → pick fiat account_id with status=active and enough balance.available

Discover schemes

GET …/payout-methods → methods[].scheme, required_fields, require_one_of, aliases, default

Discover banks (local rails)

For NGN / GHS / CAD local rails: GET …/payout-banks → pick bank_code (and bank_name)

Preview

POST …/payouts/preview with amount, beneficiary, bank → preview_token

Confirm

POST …/payouts with preview_token + idempotency_key

Poll

GET …/payouts/{payout_id} until terminal status

Use Try it under API Reference for the same paths (search payout-methods, payout-banks, then payouts/preview). After this docs PR deploys, those operations show success/error response examples in the panel.

1. Discover schemes

curl -sS "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payout-methods" \
  -H "X-API-Key: $API_KEY" | jq '.data'

Typical data:

Field	Meaning
`currency`	Account currency
`methods[].scheme`	Value to send as `bank.scheme` (or omit when `default`)
`methods[].required_fields`	Always required on `bank` / beneficiary for that scheme
`methods[].require_one_of`	At least one field from each group (e.g. SWIFT: `iban` or `account_number`)
`methods[].optional_fields`	Truly optional only
`methods[].aliases`	Accepted alternate scheme strings (e.g. GHS `eft` → `gh_eft`)

Common schemes by currency

Currency	Schemes (see discovery)	Local bank fields
NGN	`nip` (default), `swift`	`bank_code` + `account_number` + `bank_name` + `country=NG`
GHS	`gh_eft` / `eft`, `swift`	`bank_code` + `account_number` + `bank_name` + `country=GH`
CAD	`eft` (default), `interac_email`, `interac_account`, `swift`	EFT: institution + transit + account; Interac email: `email`
EUR	`sepa` (default), `swift`	SEPA: `iban` + `bank_name` + `country`
USD	`ach` / `wire`, `swift`	`routing_number` + `account_number` + …

SWIFT: required_fields include swift_bic; use require_one_of: [["iban","account_number"]]. Do not treat both as optional. Do not use corridor GET /partner/banks for these codes. That list is for quote network_id (African / international corridors), not banking payouts.

2. Discover banks (NGN / GHS / CAD)

curl -sS "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payout-banks" \
  -H "X-API-Key: $API_KEY" | jq '.data | {country, currency, n: (.banks|length), sample: .banks[0:3]}'

data.banks[] typically includes bank_code, bank_name, and optionally swift_bic / bank_institution_number. Country is derived from the account currency (NGN→NG, GHS→GH, CAD→CA). Currencies without a directory return banks: [].

3. Preview

Preview and confirm must use the same source account_id.

NGN (NIP)

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts/preview" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1.00",
    "beneficiary": {
      "first_name": "Chidinma",
      "last_name": "Okafor",
      "email": "chidinma@example.com",
      "address": {
        "line_1": "1 Broad St",
        "city": "Lagos",
        "postal_code": "100001",
        "country": "NG"
      }
    },
    "bank": {
      "account_holder_name": "Chidinma Okafor",
      "country": "NG",
      "bank_code": "044",
      "account_number": "0690000031",
      "bank_name": "Access Bank"
    }
  }' | jq '.'

GHS (EFT)

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts/preview" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1.00",
    "beneficiary": {
      "first_name": "Kwame",
      "last_name": "Mensah",
      "email": "kwame@example.com",
      "address": {
        "line_1": "1 Independence Ave",
        "city": "Accra",
        "postal_code": "GA000",
        "country": "GH"
      }
    },
    "bank": {
      "account_holder_name": "Kwame Mensah",
      "country": "GH",
      "bank_code": "030100",
      "account_number": "1234567890",
      "bank_name": "ABSA BANK OF GHANA LIMITED"
    }
  }' | jq '.'

CAD Interac email

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts/preview" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1.00",
    "beneficiary": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "address": {
        "line_1": "1 Main",
        "city": "Toronto",
        "postal_code": "M5V1A1",
        "country": "CA"
      }
    },
    "bank": {
      "scheme": "interac_email",
      "account_holder_name": "Jane Doe",
      "country": "CA",
      "email": "jane@example.com"
    },
    "security_question": "What is your favorite color?",
    "security_answer": "blue"
  }' | jq '.'

Outbound Interac security_question / security_answer are optional on preview. Share the answer with the recipient out of band. Answers are never returned in partner responses.

EUR SEPA (shape check)

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts/preview" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1.00",
    "beneficiary": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "address": {
        "line_1": "1 Example Street",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "DE"
      }
    },
    "bank": {
      "iban": "DE89370400440532013000",
      "account_holder_name": "Ada Lovelace",
      "bank_name": "Example Bank",
      "country": "DE"
    }
  }' | jq '.'

Save preview_token. Fees on preview are often fee_status=pending_confirm / fee: null until confirm.

4. Confirm

On live, confirm initiates an external bank payout. Do not confirm unless you intend to send funds.

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_token": "<from preview response>",
    "idempotency_key": "payout-2026-09-14-001"
  }' | jq '.'

Reuse the same idempotency_key after network errors. Tokens expire quickly; re-preview if needed.

5. Get payout

curl -sS "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/payouts/$PAYOUT_ID" \
  -H "X-API-Key: $API_KEY" | jq '.'

Business rules

Same currency fiat → external bank only (no FX on this rail).
Discover → preview → confirm on the same source account_id.
Balance: available >= amount (exact balance allowed). Insufficient → 422 with data.available, data.amount, data.currency.
Partner-neutral JSON: errors do not name upstream PSPs.
Fees may finalize only on confirm/GET; do not invent a fee schedule.

Funding the source account

Rail	How the end-customer funds
NGN / GHS / many local fiats	Deposit instructions only
CAD	Deposit instructions and/or Interac payment-requests (when enabled)
EUR / GBP	Deposit instructions and/or Open Banking payment-requests (when enabled)

NGN has no “request money” payment-request; use deposit coordinates.

Errors

Situation	Typical	Action
Banking gate not ready	`409` + `banking_profile_incomplete`	Poll `deposit_account`
Insufficient balance	`422` + `available` / `amount` / `currency`	Fund via deposit-instructions or lower amount
Missing `bank_code` / scheme fields	`422` + `field`	Re-read `payout-methods` / `payout-banks`
Preview token expired	`4xx`	Re-preview on the same `account_id`

Get started

Customer KYC

Banking

Corridors

Sandbox

Payouts

External bank payouts

Auth

Integrator flow (recommended order)

1. Discover schemes

Common schemes by currency

2. Discover banks (NGN / GHS / CAD)

3. Preview

NGN (NIP)

GHS (EFT)

CAD Interac email

EUR SEPA (shape check)

4. Confirm

5. Get payout

Business rules

Funding the source account

Errors

Next

​External bank payouts

​Auth

​Integrator flow (recommended order)

​1. Discover schemes

​Common schemes by currency

​2. Discover banks (NGN / GHS / CAD)

​3. Preview

​NGN (NIP)

​GHS (EFT)

​CAD Interac email

​EUR SEPA (shape check)

​4. Confirm

​5. Get payout

​Business rules

​Funding the source account

​Errors

​Next

External bank payouts

Auth

Integrator flow (recommended order)

1. Discover schemes

Common schemes by currency

2. Discover banks (NGN / GHS / CAD)

3. Preview

NGN (NIP)

GHS (EFT)

CAD Interac email

EUR SEPA (shape check)

4. Confirm

5. Get payout

Business rules

Funding the source account

Errors

Next