API Reference

Complete documentation of every endpoint in the HexAI Payment Gateway API. All endpoints are prefixed with /api/v1.

Base URL

One base URL serves both environments — your API key prefix selects which one you hit. There is no separate sandbox host to switch to.

Integrating each rail

HPG routes each payment to one of several underlying rails. Choose a rail per request with the optional provider field — omit it and HPG defaults to WAVE; an unknown or disabled provider returns 422 provider_not_enabled. The rails do not integrate the same way: Wave and Waychit redirect the customer, while APS is a two-step wallet + OTP charge with no redirect. Pick a rail below for its exact end-to-end flow.

Amounts

Amounts are decimal strings in major units — "134.00", not minor-unit integers. There is no cent-to-dalasi conversion to get wrong on your side.

Payout amounts must be whole dalasi. The mobile money rail rejects any payout carrying butut precision, so "134.00" settles where "134.06" is refused. HPG catches this at the API boundary and returns 400 amount_not_whole rather than letting the rail refuse it asynchronously half a minute later:

{
  "status": "error",
  "code": "amount_not_whole",
  "message": "Payout amount must be a whole GMD value — got 134.06. The payment rail rejects sub-unit amounts."
}

Treat it as a permanent validation error — retrying the same amount will always fail. Round down and carry the remainder into the recipient's next payout: rounding up disburses money your balance does not back, and dropping the remainder loses it a few bututs at a time. This bites hardest on amounts derived from a percentage — a commission split or a net figure lands on a fractional value most of the time.

Collections are unaffected. They run through a different endpoint on the rail and accept decimal amounts such as "10.50".

Webhooks

HPG sends a single, provider-agnostic webhook to your endpoint whenever a transaction status changes — the payload is identical whether the payment ran over Wave, APS, or Waychit. This is especially important for APS and WAYCHIT_CARD, which have no redirect/polling flow: the webhook is your primary signal that money moved.

{
  "event": "payment.succeeded",
  "data": {
    "id": "tx_abc123",
    "type": "collection",
    "reference": "INV-001",
    "amount": "500.00",
    "currency": "GMD",
    "status": "SUCCEEDED",
    "provider": "WAVE",
    "environment": "LIVE",
    "completed_at": "2026-01-01T12:00:00.000Z"
  }
}

Verify x-hexai-signature by recomputing the HMAC-SHA256 of the exact request body with your webhook secret and comparing in constant time before you act on the event. The wave-signature header carries the same value, so existing verifiers keep working unchanged.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

All error responses follow this structure:

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your account balance is insufficient for this payout.",
    "details": {
      "required_amount_bututs": 50000,
      "available_balance_bututs": 30000
    }
  }
}

Verification Examples

# Verify manually using openssl
echo -n '{"event":"payment.succeeded",...}' | \
openssl dgst -sha256 -hmac "YOUR_WEBHOOK_SECRET"