Skip to main content
POST
/
orders
/
create
Create order from plaintext payload
curl --request POST \
  --url https://sandbox.elementpay.net/orders/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "user_address": "<string>",
  "token": "<string>",
  "order_type": 0,
  "fiat_payload": {
    "amount_fiat": 123,
    "cashout_type": "PHONE",
    "phone_number": "<string>",
    "till_number": "<string>",
    "paybill_number": "<string>",
    "account_number": "<string>",
    "bank_code": "<string>",
    "reference": "<string>",
    "currency": "KES",
    "narrative": "<string>",
    "client_ref": "<string>",
    "metadata": {}
  }
}
'
{
  "status": "success",
  "message": "Order submitted",
  "data": {
    "tx_hash": "0xabc123...",
    "status": "submitted",
    "rate_used": 142.1234,
    "amount_sent": 12.34,
    "fiat_paid": 1750
  }
}
Create a new on-ramp or off-ramp order. What happens
  • Validates request and locks the quote as rate_used.
  • For OFFRAMP, the service submits the on-chain tx for you (no gas from client).
  • Returns the creation transaction hash tx_hash immediately.
Response envelope All responses use: 
{ "status": "success|error", "message": "string", "data": { ... } }
Success data fields
  • tx_hash — creation transaction hash (use with GET /orders/tx/{tx_hash}).
  • status — order state: submitted | processing | settled | failed | refunded.
  • rate_used — FX rate applied when the quote was locked.
  • amount_sent — token amount in 6 decimals units (e.g., 0.71234 USDC).
  • fiat_paid — fiat amount charged/expected.
Example — 201 Created 
{
  "status": "success",
  "message": "Order submitted",
  "data": {
    "tx_hash": "0xabc123...",
    "status": "submitted",
    "rate_used": 142.1234,
    "amount_sent": 12.34,
    "fiat_paid": 1750
  }
}
Error shapes (examples) 400 insufficient allowance: 
{ "status": "error", "message": "Approve the contract to spend your tokens before OffRamp.", "data": { "required": 79218430, "current": 0 } }
401 missing/invalid key: 
{ "status": "error", "message": "Missing API key", "data": null }
Track the order
  • GET /orders/tx/{tx_hash} — fetch current status and details.
  • Webhooks — configure a webhook URL + secret on your API key to receive async updates.
Auth Send X-API-Key: <key> with every request.

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Create order request body.

​
user_address
string
required

Customer EVM address. For ONRAMP: receives the tokens. For OFFRAMP: spender address (must have ERC-20 allowance for the contract). If allowance is insufficient, the API returns 400 insufficient_allowance with data.required and data.current.

​
token
string
required

ERC-20 token contract address (checksummed). Use /meta/tokens to discover supported tokens and addresses.

​
order_type
enum<integer>
required

Order direction. Integer enum (0=ONRAMP, 1=OFFRAMP).

Available options:
0,
1
​
fiat_payload
FiatPayload · object
required

Fiat configuration (amount, destination type, and destination details).

Response

Order submitted