​

Element Pay API

​

Quick Links

• Quickstart
• API Reference
• Verify webhook signatures
• Postman guide

​

How it works (at a glance)

• On-ramp (order_type = 0): customer pays via M-Pesa → tokens sent to user_address.
• Off-ramp (order_type = 1): customer spends tokens → fiat paid to PHONE / TILL / PAYBILL.
• You get webhooks for status updates (order.submitted, order.settled, order.failed, order.refunded).

​

Environments & base URLs

X-API-Key: <key>

​

Tokens & rates (at a glance)

• Fetch supported tokens/networks from GET /meta/tokens (use the correct environment).
• Amounts in responses (amount_sent) are human units (e.g., 12.34 USDC).
• Off-ramp needs ERC-20 allowance first; otherwise you’ll get 400 insufficient_allowance.
• rate_used is locked at order creation (see the guide below for fees/markups & examples).

​

First call (on-ramp)

POST https://sandbox.elementpay.net/api/v1/orders/create
X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "user_address": "0x40C2f2e0326bD1f647fbeB8732529e08B4DB309f",
  "token": "0x05D032ac25d322df992303dCa074EE7392C117b9",
  "order_type": 0,
  "fiat_payload": {
    "amount_fiat": 10,
    "cashout_type": "PHONE",
    "phone_number": "+254712531490",
    "currency": "KES",
    "narrative": "Top up for order #1007",
    "client_ref": "INV-1024"
  }
}

{
  "status": "success",
  "message": "Order submitted",
  "data": {
    "tx_hash": "0xabc123...",
    "status": "submitted",
    "rate_used": 142.1234,
    "amount_sent": 12.34,
    "fiat_paid": 1750
  }
}

• Poll: GET /orders/tx/{tx_hash}
• Prefer: webhooks (set URL + secret on your API key)

​

Errors (shape)

{ "status": "error", "message": "string", "data": null | { ... } }

• 401 Missing/invalid API key
• 400 insufficient_allowance / insufficient_balance
• 422 Validation errors (data.errors[])

​

Try in Postman

​

Need help?

• Email: elementpay.info@gmail.com
• Community: WhatsApp (see header)