AlphaPay API documentation

Introduction

The AlphaPay API is organized around REST. It uses predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes. Every account gets a test and a live key — build your integration in test mode, then switch to live keys when you're ready to go live.

Authentication

Authenticate requests by including your secret key in the Authorization header. You can find your keys on the Developers page of your dashboard. Never expose your secret key in client-side code.

Authorization: Bearer sk_test_9d3e7c2a1b5f4d8e6c0a2b7f9e1d4c6a

Initialize a payment

Starts a payment for a customer. Returns a checkout_url you redirect the customer to — a fully AlphaPay-branded checkout page, hosted on your own domain, where they enter their mobile money number and approve the charge. Hold on to the reference — you'll need it to verify the payment once the customer completes it.

curl http://localhost:3000/api/payments/initialize \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "GHS",
    "customer_email": "customer@example.com",
    "reference": "ORDER-1042"
  }'

Response

{
  "id": "pay_9f3a2b1c",
  "status": "pending",
  "amount": 500000,
  "currency": "GHS",
  "reference": "ORDER-1042",
  "checkout_url": "http://localhost:3000/pay/ORDER-1042"
}

Verify a payment

Confirm the final status of a payment before you fulfil an order. Always verify server-side — never trust a redirect or client-side callback on its own.

curl http://localhost:3000/api/payments/verify/ORDER-1042 \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "id": "pay_9f3a2b1c",
  "status": "success",
  "amount": 500000,
  "currency": "GHS",
  "reference": "ORDER-1042",
  "paid_at": "2026-08-09T14:22:00Z",
  "channel": "card"
}

status is one of pending, success, or failed. Only fulfil the order once it reads success.

Move your available balance to a linked bank account. Most withdrawals settle within a few hours. This endpoint isn't wired up to a live payout rail yet — withdrawals in the dashboard today are simulated.

curl https://api.alphapay.dev/v1/withdrawals \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 120000,
    "bank_account_id": "bank_01"
  }'

Webhooks

Configure an endpoint from the Developers page to receive real-time events as they happen — a payment succeeds, fails, or a withdrawal completes. AlphaPay signs every request with an X-AlphaPay-Signature header so you can verify it came from us. In this demo the forwarding destination is set via an environment variable rather than a dashboard field — a per-business settings UI is next.

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_9f3a2b1c",
    "amount": 500000,
    "reference": "ORDER-1042"
  }
}

Errors

AlphaPay uses conventional HTTP response codes: 2xx for success, 4xx for an error caused by the request (a missing parameter, an invalid key), and 5xx for an error on AlphaPay's side.

{
  "error": {
    "type": "invalid_request",
    "message": "amount must be greater than 0"
  }
}