Currency conversions

Convert cross-currency fiat (and eligible ledger pairs) between accounts owned by the same customer — for example EUR → NGN on that customer’s ledger. This is not a book transfer (same currency) and not a corridor order quote (fiat ↔ crypto ramp).

Flow	When to use
Book transfers	Same currency, any account under this API key
Conversions	Different currencies on the same `pcus_*`
Corridor quote → accept	African / international ramps (fiat ↔ crypto)
External bank payouts	Same-currency push to an outside bank (separate product)

Prerequisite: Customers quickstart. Banking gate: products.deposit_account.status=ready. Both accounts must be status=active and owned by {customer_id}.

Auth and environments

export BASE="https://sandbox.elementpay.net/api/v1"   # or live / staging base
export API_KEY="is_test_…"                            # or is_live_…
export CUSTOMER_ID="pcus_…"

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

Gates

Gate	Field	Unlocks
Quote identity	`status` is `approved` (or `active`)	`customer_id` on ramps
Banking	`products.deposit_account.status` is `ready`	Conversions from that customer’s accounts

If banking routes are called before ready, expect 409 with data such as deposit_account_status and reason: banking_profile_incomplete.

Indicative rates vs binding conversion

Source	Role
`GET /partner/rates/indicative?fiat=…`	Corridor fiat vs USD tickers for checkout UI — not binding; not ledger pair FX
`POST …/conversions/preview`	Binding pair quote for this debit (`rate`, `amount_from`, `amount_to`, `expires_at`)

Use conversion preview for ledger FX insight and confirm. Do not treat corridor indicative rates as the convert price.

Happy path

Confirm banking ready

Poll GET /partner/customers/{customer_id} until deposit_account.status=ready

List accounts

Resolve source and destination fiat account_ids via GET …/accounts (different currencies; both owned by this customer)

Preview

POST …/conversions/preview with to_account_id + amount → preview_token, rate, expires_at

Confirm promptly

POST …/conversions with preview_token + idempotency_key before expires_at (often a few minutes)

Re-list balances

GET …/accounts on source and destination to confirm balances moved

1. Resolve accounts

Use ids returned by your API key (do not hardcode from this guide).

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

export ACCOUNT_ID="<source fiat account_id>"       # e.g. EUR
export TO_ACCOUNT_ID="<destination fiat account_id>"  # e.g. NGN

2. Preview

Preview and confirm must use the same source account_id. The preview_token seals source, destination, amounts, and rate.

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/accounts/$ACCOUNT_ID/conversions/preview" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"to_account_id\": $TO_ACCOUNT_ID,
    \"amount\": \"1.00\"
  }" | jq '.'

Typical success shape:

{
  "status": "success",
  "message": "Conversion preview",
  "data": {
    "preview_token": "ep_fx_prev_…",
    "from_account_id": 63,
    "to_account_id": 68,
    "from_currency": "EUR",
    "to_currency": "NGN",
    "amount_from": "1.00",
    "amount_to": "1511.72",
    "rate": 1511.724589,
    "fee": "0.00",
    "fee_status": "estimated",
    "expires_at": "2026-09-15T11:05:13+00:00"
  }
}

Save preview_token. Confirm before expires_at. If the quote is already stale at preview time, expect 422 with data.code: quote_expired — request a new preview.

Amounts below the rail minimum return 422 (for example data.min_amount / data.field: amount). Same source and destination account returns 422 on to_account_id.

3. Confirm

On live, confirm moves real balances. Sandbox: self-serve deposits may not credit usable balance for outbound converts. Contact Element Pay for a sandbox credit if you need to exercise preview → confirm (same pattern as deposit instructions / stablecoin sends).

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

Reuse the same idempotency_key on retries after network errors (replay returns the same conversion id). Do not reuse a preview token after a successful confirm — request a fresh preview for the next conversion.

Business rules

Cross-currency only — source and destination currencies must differ; same-currency moves use book transfers.
Same customer — both accounts belong to {customer_id} (not another pcus_* under the key).
Preview → confirm on the same source account_id; respect expires_at (shorter than many other banking previews).
Balance: available >= amount on the source account.
Partner-neutral JSON: error message / data do not expose upstream PSP names. Ops may see upstream_http_status only.

Errors

Situation	Typical	Action
Banking gate not ready	`409` + `banking_profile_incomplete`	Poll `deposit_account`
Same account / same currency	`422` + `to_account_id`	Pick a different-currency destination owned by this customer
Amount below minimum / insufficient balance	`422` + amount fields	Raise amount or fund source
Stale upstream quote at preview	`422` + `code: quote_expired`	Retry preview
Expired / wrong-account / tampered token	`422`	Fresh preview on the correct source `account_id`
Upstream reject after confirm	`5xx` + `upstream_http_status`	New preview; do not assume balances moved

Get started

Customer KYC

Banking

Corridors

Sandbox

Conversions

Currency conversions

Auth and environments

Gates

Indicative rates vs binding conversion

Happy path

1. Resolve accounts

2. Preview

3. Confirm

Business rules

Errors

Next

​Currency conversions

​Auth and environments

​Gates

​Indicative rates vs binding conversion

​Happy path

​1. Resolve accounts

​2. Preview

​3. Confirm

​Business rules

​Errors

​Next

Currency conversions

Auth and environments

Gates

Indicative rates vs binding conversion

Happy path

1. Resolve accounts

2. Preview

3. Confirm

Business rules

Errors

Next