​

Agent quickstart — Element Pay Partner API

​

Install / auth

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

X-API-Key: is_test_YOUR_API_KEY
Content-Type: application/json

​

Sandbox credentials / test amounts

​

Happy path — local fiat → USDC (OnRamp)

​

Numbered steps (copy-pasteable)

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

1. GET /partner/customers/requirements
2. POST /partner/customers → save pcus_*
3. POST /partner/customers/{customer_id}/documents (identity + address)
4. POST /partner/customers/{customer_id}/submit
5. Wait for customer.approved webhook or poll GET /partner/customers/{customer_id} until status is approved

export CUSTOMER_ID="pcus_YOUR_APPROVED_CUSTOMER"

curl -sS "$BASE/partner/catalog?country=KE&order_type=OnRamp" \
  -H "X-API-Key: $API_KEY" \
  | jq '.data.onramp.countries.KE.payment_methods.mobile_money.providers[] | {id, name}'

curl -sS -X POST "$BASE/partner/orders/quote" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "OnRamp",
    "currency": "KES",
    "country": "KE",
    "local_amount": 800,
    "customer_id": "'"$CUSTOMER_ID"'",
    "asset": {
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913",
      "currency": "USDC",
      "network": "BASE"
    },
    "payment_method": {
      "type": "mobile_money",
      "phone_number": "+2541111111111",
      "network_id": "REPLACE_FROM_CATALOG"
    },
    "wallet_address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"
  }' | tee /tmp/quote.json | jq '{quote_id: .data.quote_id, expires_at: .data.expires_at, amounts: .data.amounts}'

export QUOTE_ID=$(jq -r '.data.quote_id' /tmp/quote.json)

sleep 2
curl -sS -X POST "$BASE/partner/orders/$QUOTE_ID/accept" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | tee /tmp/accept.json | jq '.data | {quote_id, status, order: .order.order_id, payment_instructions}'

export ORDER_ID=$(jq -r '.data.order.order_id' /tmp/accept.json)

curl -sS "$BASE/partner/orders/$ORDER_ID" -H "X-API-Key: $API_KEY" | jq '.data'

​

Webhook verify + idempotency

X-Webhook-Event: order.settled
X-Webhook-Id: <uuid>
X-Webhook-Signature: t=<unix_ts>,v1=<base64_signature>

1. Parse t=…,v1=…
2. Reject if t older than 5 minutes
3. HMAC-SHA256 over {t}.{raw_body} with YOUR_WEBHOOK_SECRET; constant-time compare to v1
4. Dedupe on X-Webhook-Id; return 2xx quickly

​

Banking (optional) — customers + accounts

​

Sequence

1. Wait until products.deposit_account.status is ready
2. POST /partner/customers/{customer_id}/accounts (open fiat or stablecoin rail; idempotent on rail tuple)
3. GET /partner/customers/{customer_id}/accounts → save account_id
4. GET …/accounts/{account_id}/deposit-instructions when you need bank details or a deposit wallet
5. Money movement (each has its own guide; confirm uses idempotency_key):
   • Stablecoin sends: …/sends/preview → …/sends
   • Book transfers (same currency): …/book-transfers/preview → …/book-transfers
   • Conversions (cross-currency, same pcus_*): …/conversions/preview → …/conversions
   • External bank payouts: …/payout-methods → …/payout-banks → …/payouts/preview → …/payouts

​

Open examples (sandbox)

# Fiat rail (e.g. EUR IBAN) — after deposit_account.status=ready
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'

# Stablecoin rail (Base USDC) — network casing per accounts guide
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'

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

• Sandbox outbound sends/conversions/payouts may need an Element Pay sandbox credit (customers/deposit-instructions.mdx).
• USD fiat open is not available for Kenya individuals (unsupported_region) — see customers/accounts.mdx.
• Card routes are documented in customers/cards.mdx but not in openapi.yaml yet (docs/KNOWN_GAPS.md).

​

Common pitfalls

1. Quoting before vault status=approved → 422
2. Calling accounts before deposit_account.status=ready → 409
3. Hardcoding network_id from docs instead of your catalog
4. Using sandbox success phones on production
5. Treating GET /partner/rates/indicative as the binding FX (it is not; use quote amounts.rate)
6. Confusing corridor OnRamp with ledger …/conversions (fiat↔fiat on banking accounts only)
7. Crediting the user ledger on accept/order.processing instead of order.settled
8. Missing webhook signature check or clock skew / replay beyond 5 minutes
9. Reusing OffRamp crypto deposit addresses across orders (per-order in production)

​

OpenAPI path map

​

Ramp happy path

​

Banking (after deposit_account.status=ready)