Quickstart

End-to-end: KYC every customer → approved → KE OnRamp quote → accept. Banking (IBAN / ledger) is optional and comes later — see Accounts.

Prerequisites

Sandbox API key (is_test_…) from Element Pay
webhook_url on that key (recommended)
curl and jq
Non-custodial partners who need the customer wallet to authorize accept: enable Signed accepts in Console and follow Customer-signed accepts (this quickstart uses empty-body accept)

1. 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

2. Customer KYC (required)

Every end-customer must complete the vault before you use customer_id on quote.

Requirements

See required profile fields and document categories.

Create

POST /partner/customers — save pcus_*.

Documents

Upload identity and address (individual).

Submit

POST …/submit — fix any missing[] until 200.

Approved

Sandbox usually auto-approves; live waits for EP review. Poll or webhook customer.approved.

Detailed curls: Customer KYC quickstart. Minimal individual checklist before submit:

Profile: name, email, DOB, gender, phone, id_number, id_type, address (line1, city, country)
Documents: identity, address (base64 upload)

After create, always check what’s left:

export CUSTOMER_ID="pcus_…"

curl -sS "$BASE/partner/customers/$CUSTOMER_ID" \
  -H "X-API-Key: $API_KEY" | jq '.data | {status, missing, documents: [.documents[].category]}'

Submit when missing is empty:

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/submit" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{}' | jq '.data | {id, status}'

Wait until status is approved:

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

3. Discover Kenya M-PESA `network_id`

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}'

Copy a providers[].id for Safaricom M-PESA into payment_method.network_id below.

4. Quote (OnRamp, `customer_id`)

Default sandbox asset: Base USDC.

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": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
    },
    "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)

Response anatomy: Quote and accept.

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

5. Accept

sleep 2

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

If Signed accepts is on for this API key, empty {} is rejected — use Customer-signed accepts.

6. Webhooks

Configure webhook_url on your API key:

Event	Meaning
`customer.approved`	KYC cleared — may quote with `customer_id`
`order.processing`	Accept succeeded
`order.settled`	Fiat and crypto legs complete
`order.failed`	Terminal failure

See Webhooks.

Deprecated: inline customer on quote

Inline customer on quote is deprecated. Still supported while you migrate existing integrations. New work: vault KYC → customer_id only. Sandbox inline examples: Quote and accept — deprecated · Test payloads.

Customer KYC — business KYB, revoke, ref lookup
Quote and accept — OffRamp, errors, response fields
Customer-signed accepts — optional EIP-712 accept (non-custodial)
Sandbox success & failure — sandbox phone/account triggers
Banking / accounts — optional, after deposit_account.status=ready

Get started

Customer KYC

Banking

Corridors

Sandbox

Quickstart

Quickstart

Prerequisites

1. Environment

2. Customer KYC (required)

3. Discover Kenya M-PESA `network_id`

4. Quote (OnRamp, `customer_id`)

5. Accept

6. Webhooks

Deprecated: inline customer on quote

Next

​Quickstart

​Prerequisites

​1. Environment

​2. Customer KYC (required)

​3. Discover Kenya M-PESA network_id

​4. Quote (OnRamp, customer_id)

​5. Accept

​6. Webhooks

​Deprecated: inline customer on quote

​Next

Quickstart

Prerequisites

1. Environment

2. Customer KYC (required)

3. Discover Kenya M-PESA `network_id`

4. Quote (OnRamp, `customer_id`)

5. Accept

6. Webhooks

Deprecated: inline customer on quote

Next