API Reference

Complete documentation of all available endpoints in the Hexai Payment Gateway API. All endpoints are prefixed with /api/v1.

Base URLs

HexAI provides separate environments for testing and production:

Sandbox (Testing)https://hpg.hexai.gm/api/v1

Use test API keys (sk_test_*) to trigger sandbox mode

Production (Live)https://hpg.hexai.gm/api/v1

Use live API keys (sk_live_*) for real transactions

🧪 Sandbox Mode

The sandbox environment is activated automatically when you use test API keys (sk_test_*). No real money is processed, and you can test edge cases using magic amounts:

Amount (GMD)	Outcome	Simulated Behavior
100.00	SUCCESS	Transaction completes successfully
200.00	PENDING	Transaction stays pending (test polling)
400.00	FAILED	Insufficient funds error
403.00	FAILED	Account blocked error
429.00	FAILED	Rate limit exceeded
500.00	ERROR	Internal server error (test retries)

Collections API

Endpoints for initiating and managing customer payments via Wave Mobile Money.

Post/collections/initiate

Auth Required

Start a new payment collection. This returns a Wave checkout URL to redirect your customer.

Request Body

{
  "amount": "100.00",
  "currency": "GMD",
  "client_reference": "ORDER-12345",
  "success_url": "https://yoursite.com/success",
  "error_url": "https://yoursite.com/cancel"
}

Implementation Examples

curl -X POST https://hpg.hexai.gm/api/v1/collections/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "GMD",
    "client_reference": "ORDER-12345",
    "success_url": "https://yoursite.com/success",
    "error_url": "https://yoursite.com/cancel"
  }'

Response Sample

{
  "status": "success",
  "data": {
    "transaction_id": "tx_abc123",
    "redirect_url": "https://checkout.wave.com/...",
    "status": "PENDING"
  }
}

Get/collections/status/:reference

Retrieve the current status of a transaction using your client_reference.

Payouts API

Endpoints for sending money from your business balance to Wave customers. The system automatically handles idempotency to prevent duplicate payouts.

Post/payouts/initiate

Send funds to a Wave mobile number. Balance is deducted instantly upon success.

Parameters

Field	Type	Description
amount	string	Amount to send (e.g. "10.00")
recipient_mobile	string	Gambian Wave number (+220...)

Implementation Examples

curl -X POST https://hpg.hexai.gm/api/v1/payouts/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50.00",
    "currency": "GMD",
    "recipient_mobile": "+2201234567",
    "client_reference": "OUT-101"
  }'

Utility & Dashboard API

Endpoints for retrieving account statistics, balance, and transaction history for custom dashboard integrations.

Get/client/balance

Auth Required

Retrieve your current available balance and collection statistics.

Implementation Sample

curl -X GET https://hpg.hexai.gm/api/v1/client/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Sample

{
  "status": "success",
  "data": {
    "available_balance_bututs": 450050,
    "available_balance_gmd": "4500.50",
    "total_collected_bututs": 1000000,
    "total_collected_gmd": "10000.00",
    "platform_commissions_bututs": 20000,
    "platform_commissions_gmd": "200.00",
    "net_collections_bututs": 980000,
    "net_collections_gmd": "9800.00",
    "total_paid_out_bututs": 530000,
    "total_paid_out_gmd": "5300.00",
    "successful_collections": 25,
    "total_payouts": 10
  }
}

Get/client/stats

Auth Required

Get a quick overview of your today's earnings and volume.

Response Sample

{
  "total_volume_bututs": 125000,
  "total_volume_gmd": "1250.00",
  "today_earnings_bututs": 150025,
  "today_earnings_gmd": "1500.25",
  "pending_transactions_count": 3,
  "pending_volume_bututs": 45000,
  "pending_volume_gmd": "450.00"
}

Get/client/earnings-chart

Auth Required

Retrieve historical earnings data for the last 7 days, grouped by date.

Response Sample

[
  { "date": "2026-01-19", "earnings_bututs": 120050, "earnings_gmd": "1200.50", "count": 12 },
  { "date": "2026-01-20", "earnings_bututs": 85000, "earnings_gmd": "850.00", "count": 8 },
  { "date": "2026-01-21", "earnings_bututs": 210000, "earnings_gmd": "2100.00", "count": 15 },
  { "date": "2026-01-22", "earnings_bututs": 150075, "earnings_gmd": "1500.75", "count": 10 },
  { "date": "2026-01-23", "earnings_bututs": 320000, "earnings_gmd": "3200.00", "count": 22 },
  { "date": "2026-01-24", "earnings_bututs": 180050, "earnings_gmd": "1800.50", "count": 14 },
  { "date": "2026-01-25", "earnings_bututs": 250000, "earnings_gmd": "2500.00", "count": 18 }
]

Get/client/transactions

Auth Required

List your recent transactions with pagination support.

Implementation Sample

curl -X GET "https://hpg.hexai.gm/api/v1/client/transactions?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Param	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 10)

Webhooks

Receive asynchronous notifications when transaction statuses change.

Payload Example

{
  "event": "transaction.completed",
  "transaction": {
    "id": "tx_abc123",
    "client_reference": "INV-001",
    "type": "COLLECTION",
    "amount": 500.00,
    "status": "SUCCEEDED"
  }
}

Webhooks are signed with an HMAC-SHA256 signature passed in the wave-signature header. Always verify the signature using your secret before fulfilling orders.

Error Handling

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

Status Code	Meaning	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid parameters, missing required fields, malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Resource doesn't exist (invalid transaction ID, etc.)
429	Rate Limited	Too many requests in a short time
500	Internal Error	Server-side issue (retry with exponential backoff)
503	Service Unavailable	Temporary maintenance or overload

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":"transaction.completed",...}' | \
openssl dgst -sha256 -hmac "YOUR_WEBHOOK_SECRET"