Webhooks

Element Pay notifies your backend when orders, customers, and accounts change. Treat webhooks as the source of truth for settlement, KYC / banking readiness, and account credits / sends — HTTP responses only confirm the request was accepted. If a webhook is delayed, poll the matching GET endpoint as a backup.

Configuration

Set webhook_url and webhook_secret on your partner API key (sandbox and production separately). The same endpoint receives order, customer, and account events.

Order events

Header `X-Webhook-Event`	When
`order.processing`	Quote accepted; rail execution started
`order.settled`	Order completed successfully
`order.failed`	Terminal failure
`order.refunded`	Refund issued (when applicable)

Backup poll: GET /partner/orders/{order_id}.

Customer events

Same signing headers and secret as orders. Backup poll: GET /partner/customers/{customer_id}.

Header `X-Webhook-Event`	When
`customer.submitted`	After a successful submit
`customer.approved`	Element Pay approves the vault case
`customer.rejected`	Review declines the case
`customer.updated`	Material status / product update
`customer.deposit_account.updated`	Deposit-account product status changes (e.g. becomes `ready` so you may open accounts)

Customer payload (example)

{
  "customer_id": "pcus_…",
  "partner_customer_ref": "partner-cust-001",
  "type": "individual",
  "status": "approved",
  "environment": "sandbox",
  "submitted_at": "2026-08-01T12:00:00+00:00",
  "reviewed_at": "2026-08-01T12:05:00+00:00",
  "products": {
    "deposit_account": {
      "status": "ready"
    }
  }
}

Deposit-account payload (example)

Fired as customer.deposit_account.updated:

{
  "customer_id": "pcus_…",
  "partner_customer_ref": "partner-cust-001",
  "status": "approved",
  "products": {
    "deposit_account": {
      "status": "ready"
    }
  },
  "can_open_deposit_account": true
}

When products.deposit_account.status is ready (and can_open_deposit_account is true), you may call Accounts open/list/get. See also Customers quickstart.

Account events

Same signing headers and secret. These fire for customer deposit-account rails (and related money movement). Backup poll: GET /partner/customers/{customer_id}/accounts/{account_id} (and send/payout GET where applicable).

Header `X-Webhook-Event`	When
`account.opened`	First successful open of a rail
`account.ready`	Coordinates become usable (bank fields or wallet)
`account.credited`	Inbound credit posted (deposit, card charge, or other credit source)
`account.send.completed`	Outbound stablecoin send reached a success terminal state
`account.send.failed`	Outbound stablecoin send reached a failure terminal state

Use account.credited / account GET balance before spending. For sends, prefer account.send.completed / account.send.failed; if GET stays non-terminal after debit for a long time, escalate rather than assuming destination credit.

HTTP delivery

POST <your-webhook_url>
Content-Type: application/json
User-Agent: ElementPay/1.0 (+support@elementpay.net)
X-Webhook-Event: order.settled
X-Webhook-Id: <uuid>
X-Webhook-Signature: t=<unix_ts>,v1=<base64_signature>

Order payload (example)

Webhook bodies have no internal routing metadata or upstream PSP blobs. Typical order fields:

{
  "order_id": "YC-580e04c2-a136-5cca-be54-b49fcf80970c",
  "status": "settled",
  "amount_fiat": 800.0,
  "currency": "KES",
  "amount_crypto": 5.12,
  "exchange_rate": 156.25,
  "order_type": "OnRamp",
  "wallet_address": "0x4F07419E6bfCCF8D256E8ef803Cc2653dfbB9558",
  "phone_number": "2541111111111",
  "settlement_transaction_hash": "0xabc...",
  "created_at": "2026-07-07T10:00:00.000000Z",
  "updated_at": "2026-07-07T10:00:15.000000Z"
}

Fields vary by corridor and rail. client_metadata and other internal fields are not included on the public partner API.

Signature verification

Parse X-Webhook-Signature:

t=1710000000,v1=<base64_hmac>

Reject if t is older than 5 minutes (replay protection).
Compute HMAC-SHA256 over {t}.{raw_body} using your webhook_secret.
Compare constant-time to v1.

Idempotency

Use X-Webhook-Id to deduplicate deliveries. Your endpoint should return 2xx quickly; heavy work can be async.

Local testing

Use a tunnel (ngrok, Cloudflare Tunnel) pointing at your dev server, or log payloads in sandbox before going live.

Get started

Customers

Corridors

Sandbox

Webhooks

Webhooks

Configuration

Order events

Customer events

Customer payload (example)

Deposit-account payload (example)

Account events

HTTP delivery

Order payload (example)

Signature verification

Idempotency

Local testing

​Webhooks

​Configuration

​Order events

​Customer events

​Customer payload (example)

​Deposit-account payload (example)

​Account events

​HTTP delivery

​Order payload (example)

​Signature verification

​Idempotency

​Local testing

Webhooks

Configuration

Order events

Customer events

Customer payload (example)

Deposit-account payload (example)

Account events

HTTP delivery

Order payload (example)

Signature verification

Idempotency

Local testing