Customer accounts

Optional banking product — EUR/USD IBAN, stablecoin ledger, sends, book transfers, currency conversions, payouts, and cards.

Prerequisite — KYC (required for everyone): complete Customer KYC quickstart until status is approved. Banking does not replace KYC.Prerequisite — banking gate: products.deposit_account.status must be ready before account open / list / sends. KYC approval alone is not enough for this section.

Give each vault customer bankable and on-chain balances under one customer_id (pcus_*):

Fiat accounts — e.g. EUR (IBAN) and USD (account / routing or SWIFT when returned)
Stablecoin accounts — e.g. USDC / USDT on Base or Polygon

Use each account_id for deposit instructions, stablecoin sends, book transfers, currency conversions, payouts, and cards. Corridor quote → accept uses customer_id only — no account open required.

Sandbox funding: usable balance for outbound stablecoin sends may require an Element Pay sandbox credit. See deposit instructions.

USD fiat for Kenya individuals: opening a USD fiat account is not available when the customer is an individual with Kenya residence (country / residence KE). The API returns 422 with message USD bank accounts are not available for this customer region and data.code: unsupported_region. EUR / GBP / CAD (and other non-USD fiats) and stablecoin rails can still open for those customers when otherwise eligible. Issued cards require an active USD account (Cards), so KE individuals cannot issue cards.

Auth and environments

Production: https://api.elementpay.net/api/v1 with is_live_… keys.

export BASE="https://sandbox.elementpay.net/api/v1"
export API_KEY="is_test_…"

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

Gate

Gate	Field	Unlocks
Quote identity	`status` is `approved`	`customer_id` on quote
Banking	`products.deposit_account.status` is `ready`	Account open / list / get

approved alone does not unlock accounts. Always read both fields from GET /partner/customers/{customer_id}. Prefer the customer.deposit_account.updated webhook (and customer.approved) over polling — see Webhooks. Poll GET as a backup until products.deposit_account.status is ready. If account routes are called before ready, the API returns 409 with message Deposit account is not ready. Response data includes deposit_account_status (current status) or, in some cases, reason: banking_profile_incomplete.

Happy path

Confirm banking ready

Prefer customer.deposit_account.updated (Webhooks); or poll GET /partner/customers/{customer_id} until data.products.deposit_account.status is ready

Open a rail (optional)

POST /partner/customers/{customer_id}/accounts when you need a new fiat or stablecoin rail

List accounts

GET /partner/customers/{customer_id}/accounts → pick account_id

Get one (optional)

GET /partner/customers/{customer_id}/accounts/{account_id}

Fund via deposit instructions, corridor quote → accept where applicable, then stablecoin sends or other money-movement guides when you have balance

1. Poll customer

export CUSTOMER_ID="pcus_…"

curl -sS "$BASE/partner/customers/$CUSTOMER_ID" \
  -H "X-API-Key: $API_KEY" | jq '{
    id: .data.id,
    status: .data.status,
    deposit_account: .data.products.deposit_account
  }'

2. Open an account

Idempotent on the rail tuple (asset_type + currency + network for stablecoin). Opening an existing rail returns 200 with the existing account; a new rail returns 201.

Fiat (bank rail)

Example: EUR (IBAN). USD (where enabled) returns account / routing or SWIFT-style fields when ready, not always an IBAN.

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_type": "fiat",
    "currency": "EUR"
  }' | jq '.data'

After open, deposit instructions return the bank coordinates to show the end-customer (EUR: IBAN/BIC; USD: account number and routing / SWIFT when provisioned; GBP: account and sort code when returned).

Stablecoin

network is required: Base or Polygon. Currency: USDC or USDT.

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_type": "stablecoin",
    "currency": "USDC",
    "network": "Base"
  }' | jq '.data'

Save data.id as account_id.

3. List accounts

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

export ACCOUNT_ID="21"

Typical fields: id, customer_id, asset_type, currency, network, status, balances, and rail coordinates when ready (for example account_number / bank fields for fiat, wallet_address for stablecoin).

4. Get one account

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

Errors

Situation	Typical	Action
Banking gate not ready	`409` with message `Deposit account is not ready`	Poll `products.deposit_account` until `status=ready`
KE individual opens USD fiat	`422` + `unsupported_region`	Open EUR/GBP/CAD (or stablecoin); for USD (and issuing) use a non-KE individual
Unknown / other-tenant customer	`404`	Use id from this API key
Account not found	`404`	List accounts and pick a valid `account_id`

Deposit instructions: fund a fiat or stablecoin rail
Quickstart: corridor quote → accept as an alternate funding / exit path
Stablecoin sends: preview → confirm → poll
Route cheat sheet

Get started

Customer KYC

Banking

Corridors

Sandbox

Accounts

Customer accounts

Auth and environments

Gate

Happy path

1. Poll customer

2. Open an account

Fiat (bank rail)

Stablecoin

3. List accounts

4. Get one account

Errors

Next

​Customer accounts

​Auth and environments

​Gate

​Happy path

​1. Poll customer

​2. Open an account

​Fiat (bank rail)

​Stablecoin

​3. List accounts

​4. Get one account

​Errors

​Next

Customer accounts

Auth and environments

Gate

Happy path

1. Poll customer

2. Open an account

Fiat (bank rail)

Stablecoin

3. List accounts

4. Get one account

Errors

Next