Quickstart

Get a sandbox quote and accept flow working in minutes.

Prerequisites

Sandbox API key (is_test_…) from Element Pay
webhook_url configured on that key (recommended)
curl and jq (optional)

1. Configure environment

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

Every request:

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

Asset to use (sandbox)

Use Base USDC on every quote unless we tell you otherwise:

Field	Value
`asset.currency`	`USDC`
`asset.network`	`BASE`
`asset.token`	`0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913`

(Polygon USDT is also on the rail — see Corridors overview. Prefer Base USDC for integration.)

2. Discover Kenya corridors

# Full checkout catalog (providers + min/max) — preferred for integration
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}'

# Lightweight country list only (no provider UUIDs)
curl -sS "$BASE/partner/corridors?country=KE" \
  -H "X-API-Key: $API_KEY" | jq '.data.african_markets'

Note a providers[].id for M-PESA (mobile money) from catalog — you will send it as payment_method.network_id on quote.

3. Create a quote

Preferred: pass an approved vault customer_id (pcus_*) from the Customers quickstart. That is the main identity path for new integrations. Still accepted: an inline customer object on quote (shown below) for existing integrations and a first sandbox spike. Prefer migrating to customer_id once the vault case is approved.

# Preferred once you have an approved vault customer:
#   "customer_id": "pcus_…"
# and omit the inline "customer" object.

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,
    "asset": {
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913",
      "currency": "USDC",
      "network": "BASE"
    },
    "customer": {
      "uid": "partner-ke-001",
      "type": "user",
      "name": "Jane Doe",
      "country": "KE",
      "phone": "+2541111111111",
      "address": "Nairobi",
      "dob": "02/01/1997",
      "email": "jane@example.com",
      "id_number": "A1234567",
      "id_type": "passport"
    },
    "payment_method": {
      "type": "mobile_money",
      "phone_number": "+2541111111111",
      "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
    },
    "wallet_address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"
  }' | jq '{quote_id: .data.quote_id, expires_at: .data.expires_at, instructions: .data.payment_instructions}'

Save data.quote_id (format yc_receive_…).

Replace network_id with a value from your sandbox catalog if the example UUID does not match your environment.

4. Accept the quote

Wait ~2 seconds, then accept with an empty body:

export QUOTE_ID="yc_receive_..."   # from step 3

curl -sS -X POST "$BASE/partner/orders/$QUOTE_ID/accept" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data'

5. Listen for webhooks

Configure webhook_url on your API key. Element Pay POSTs:

Event	Meaning
`order.processing`	Accept succeeded; rail is executing
`order.settled`	Fiat and crypto legs complete
`order.failed`	Terminal failure

See Webhooks for payload shape and signature verification. Prefer a vault customer_id (pcus_*) on quote when available — Customers quickstart.

Next steps

Sandbox success & failure — required for reliable sandbox settle/fail
Kenya corridor guide — momo vs bank
Sandbox test payloads — NG, UG, OffRamp curls
API reference — full OpenAPI

​Quickstart

​Prerequisites

​1. Configure environment

​Asset to use (sandbox)

​2. Discover Kenya corridors

​3. Create a quote

​4. Accept the quote

​5. Listen for webhooks

​Next steps

Quickstart

Prerequisites

1. Configure environment

Asset to use (sandbox)

2. Discover Kenya corridors

3. Create a quote

4. Accept the quote

5. Listen for webhooks

Next steps