{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "order_id": "ord_1234567890abcdef",
    "transaction_hash": "0xabc123def456789...",
    "status": "PENDING",
    "order_type": "onramp",
    "amount_fiat": 1000,
    "currency": "KES",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "wallet_address": "0x742d35Cc6634C0532925a3b8D4C0532925a3b8D4",
    "phone_number": "254712345678",
    "payment_instructions": {
      "method": "mpesa",
      "paybill": "123456",
      "account_number": "ORD1234567890",
      "amount": 1000
    },
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}

​
Create Order

Create an onramp (fiat → crypto) or offramp (crypto → fiat) order with Element Pay.
Endpoint: POST /orders/createAuthentication: Required (x-api-key header)

​
Order Types

Onramp (order_type: 0)

Fiat → CryptoUsers pay with mobile money and receive cryptocurrency in their wallet.

Offramp (order_type: 1)

Crypto → FiatUsers send cryptocurrency and receive fiat via mobile money.

​
Quick Examples

curl -X POST "https://staging.elementpay.net/api/v1/orders/create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_fiat": 1000,
    "currency": "KES",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "order_type": 0,
    "wallet_address": "0x742d35Cc6634C0532925a3b8D4C0532925a3b8D4",
    "phone_number": "254712345678",
    "webhook_url": "https://yourapp.com/webhooks/elementpay"
  }'

​
Supported Networks & Tokens

​
Offramp Integration Guide

For offramp orders, users must first approve the token transfer:
1

Token Approval

Before creating an offramp order, approve the token spend:
import { ethers } from 'ethers';

const tokenContract = new ethers.Contract(
  tokenAddress, 
  ['function approve(address spender, uint256 amount) external returns (bool)'],
  signer
);

// Approve Element Pay contract to spend tokens
const approveTx = await tokenContract.approve(
  ELEMENT_PAY_CONTRACT_ADDRESS,
  ethers.parseUnits(amount.toString(), tokenDecimals)
);

await approveTx.wait();
2

Create Offramp Order

After approval, create the offramp order:
const orderResponse = await fetch('/api/v1/orders/create', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount_fiat: 1000,
    currency: 'KES',
    token: tokenAddress,
    order_type: 1, // Offramp
    wallet_address: userWalletAddress,
    phone_number: '254712345678'
  })
});
3

Execute Transfer

Use the transaction hash from the order response to complete the transfer.

​
Response Format

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "order_id": "ord_1234567890abcdef",
    "transaction_hash": "0xabc123def456789...",
    "status": "PENDING",
    "order_type": "onramp",
    "amount_fiat": 1000,
    "currency": "KES",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "wallet_address": "0x742d35Cc6634C0532925a3b8D4C0532925a3b8D4",
    "phone_number": "254712345678",
    "payment_instructions": {
      "method": "mpesa",
      "paybill": "123456",
      "account_number": "ORD1234567890",
      "amount": 1000
    },
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}

​
Response Fields

​
order_id
string
Unique identifier for the order
​
transaction_hash
string
Blockchain transaction hash (for tracking)
​
status
string
Current order status: PENDING, PROCESSING, COMPLETED, FAILED, EXPIRED
​
payment_instructions
object
Payment details for the user (onramp orders only)
​
expires_at
string
Order expiration timestamp (ISO 8601 format)

​
Error Handling

{
  "status": "error",
  "message": "Invalid token address provided",
  "code": "INVALID_TOKEN_ADDRESS",
  "details": {
    "field": "token",
    "provided": "0xinvalid...",
    "supported_tokens": [
      "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    ]
  }
}
Common Errors:
  • INVALID_API_KEY - Check your API key
  • INVALID_TOKEN_ADDRESS - Use supported token addresses
  • INSUFFICIENT_LIQUIDITY - Try a smaller amount
  • UNSUPPORTED_CURRENCY - Check supported currencies

​
Testing

Sandbox Environment: Use the staging API (https://staging.elementpay.net/api/v1) for testing. No real money will be transferred.Test Phone Numbers: Use 254700000000 - 254700000999 for testing in sandbox.

​
Next Steps

Monitor Order Status

Track your order progress

Webhook Integration

Get real-time updates

​
Request Parameters

​
Required Fields

​
amount_fiat
number
required
Amount in fiat currency (e.g., 1000 for 1000 KES)
​
currency
string
required
Fiat currency code. Supported: KES, UGX, TZS, NGN, GHS
​
token
string
required
Contract address of the token to receive/send
​
order_type
integer
required
Order type: 0 for Onramp (fiat → crypto), 1 for Offramp (crypto → fiat)
​
wallet_address
string
required
User’s wallet address to receive/send cryptocurrency
​
phone_number
string
required
User’s phone number for mobile money transactions (format: 254712345678)

​
Optional Fields

​
webhook_url
string
URL to receive order status updates. Required for onramp orders
​
fiat_payload
object
Additional fiat payment details (varies by currency and provider)

​
fiat_payload Schema

FieldTypeRequiredDescription
amount_fiatfloatYesAmount in KES
cashout_typestringYesMust be “PHONE”
phone_numberstringYesM-PESA number in format 2547XXXXXXXX
currencystringNoDefaults to “KES”
till_numberstringNoOnly for cashout_type = TILL
paybill_numberstringNoFor cashout_type = PAYBILL
account_numberstringNoFor cashout_type = PAYBILL
referencestringNoOptional payment reference

​
Example Response

{
  "tx_hash": "0xabc123...",
  "status": "submitted",
  "rate_used": 144.32,
  "amount_sent": 6.93,
  "fiat_paid": 1000
}

​
Notes

  • All amounts are in KES unless otherwise specified.
  • For Offramp, ensure the user has approved the token transfer before creating the order.
References: