Build your payment
connection.

Start here

From setup to a paid intent

1. Prepare your webhook. Implement the registration challenge and signed event handler on a public HTTPS endpoint.
2. Register your merchant. Save the API key and webhook secret on your server.
3. Connect the receiving phone. Create a listener, install the Android app, and verify its connection.
4. Create an intent at checkout. Send the payer number, exact package amount and your account reference. Display the receiving number and registered name returned by the API.
5. Handle the payment event. Verify the signature, persist the event, and activate the package once. Keep connection failures available for recovery.

Built-in sender lists cover Uganda (256) and Ghana (233). Other networks can be configured with provider: "other" and their actual sender names, including in countries without a built-in list. Deployment country restrictions still apply; Kenya is excluded by the default configuration. Check GET /v1/me and validate your receipt format before enabling automatic activation. Provider names identify message formats, not commercial partnerships.

Authentication

Merchant requests use a server-side bearer key. Phones use a separate device key. Never place either credential in a customer-facing page, checkout app or public repository.

API and device keys are returned when issued and stored as hashes by the gateway. Store their full values securely; they cannot be retrieved later. The webhook signing secret is separate and must remain available to both servers.

Returns merchant details, configured currency, webhook URL, available providers and active pay_to accounts. The provider list includes other for custom sender setup; this option is not a guarantee that an untested receipt format will parse.

curl https://ispbillingpay.com/v1/me \
  -H "Authorization: Bearer $ISP_PAY_API_KEY"

01 / Merchant setup

Register your merchant

Initial registration does not require a payment-provider API key. A challenge verifies control of your webhook. Generate a random, single-use nonce on your server and store it as pending before sending this request.

{
  "name": "Example Networks",
  "country": "uganda",
  "dial_code": "256",
  "currency": "UGX",
  "webhook_url": "https://billing.example.com/payments/webhook",
  "nonce": "c70fca624ab244339767da0684020858"
}

Send currency as a three-letter code such as UGX or GHS. The example nonce is illustrative; generate a new one each time and keep it at most 64 characters. During registration, the gateway sends the following to your webhook with X-Gateway-Event: challenge:

{
  "type": "challenge",
  "challenge": "<gateway-generated-random-value>",
  "nonce": "<the-pending-nonce-you-sent>"
}

Check that the nonce matches a registration your server initiated and has not already consumed. Only then echo the exact challenge with HTTP 200:

{"challenge":"<the-exact-received-challenge>"}

This setup challenge is not a signed payment event. Do not echo every challenge blindly. Successful initial registration returns HTTP 201:

{
  "merchant_id": "mer_…",
  "api_key": "sk_live_…",
  "webhook_secret": "whsec_…",
  "reissued": false
}

02 / Payment source

Connect a listener phone

Choose a provider code returned by GET /v1/me. Enter the number and registered account name your customers will pay.

{
  "provider": "mtn_ug",
  "receiving_number": "+256770000001",
  "receiving_name": "EXAMPLE NETWORKS",
  "label": "Main collection phone"
}

The response contains device and a one-time device_key. Paste that key into the listener app and use the full message endpoint below. Keep the phone powered, online and able to receive SMS on the payment SIM. Grant the requested SMS and background-operation permissions.

https://ispbillingpay.com/v1/device/messages

Connect a network outside the built-in list

Register with your local dial code and currency, then create the device with provider: "other". Supply extra_senders as a comma-separated list of the sender names shown on genuine receiving-account messages. The following fictional example assumes a merchant registered with dial code 260 and currency ZMW:

{
  "provider": "other",
  "receiving_number": "+260970000001",
  "receiving_name": "EXAMPLE NETWORKS",
  "label": "Local collection phone",
  "extra_senders": "ExampleMoney"
}

Replace the example sender and account details. Add the same sender names to the Android app's allowed-sender list; creating the device does not update the phone automatically. Ordinary numeric senders are not accepted as network aliases.

Heartbeats and health

The app calls POST /v1/device/messages with X-Device-Key. With no message text, the request updates last contact and returns {"ok":true,"result":"pong"}.

{"ping":1,"version":"1.0"}

Message submissions carry from, text, sentStamp (Unix milliseconds) and version. Results are recorded, duplicate, ignored or reversal. HTTP 200 means the submission was handled, not that a customer was connected.

Health is never until first contact, online after contact within 30 minutes, quiet after that, or revoked. This is a contact indicator, not a guarantee that every payment SMS arrived. Messages already captured while offline remain queued for upload.

03 / Checkout

Create a payment intent

Create an intent from your server after the customer chooses a package. It connects a payer number and amount to an account reference in your billing system.

{
  "amount": 1000,
  "payer_phone": "+256770000002",
  "payer_name": "Alex",
  "reference": "hotspot-user-1042",
  "metadata": {"package_id":"daily-1000"}
}

Currency comes from merchant registration. There is no per-intent currency override. Intents stay open for 24 hours. The response contains intent and pay_to, an array of receiving numbers, registered names and provider labels. Display these at checkout with a copy button for the receiving number.

Use reference for the stable account and the returned intent.id for this purchase. Repeating the same still-open reference, number and amount returns the existing intent. This is limited reuse of a waiting intent, not general request idempotency. Save the ID and read it on reload. A qualifying unmatched payment received within the previous 24 hours can be linked at intent creation; always inspect the returned status.

Returns {"intent":{…}} with status waiting, paid or expired. A paid intent includes payment. Use this server-side lookup to reconcile a delayed webhook.

04 / Payment events

Receive webhooks

Each event is stored before delivery. Verify the signature, durably record the ID and payload, then return a 2xx status. Run activation from your queue so a slow router does not hold the webhook connection open.

{
  "id": "evt_…",
  "type": "payment.matched",
  "created": 1789900000,
  "data": {
    "intent": {
      "id": "pi_…", "status": "paid",
      "reference": "hotspot-user-1042",
      "amount": 1000, "currency": "UGX",
      "payment": {"id":"pay_…","reversed":false}
    }
  }
}

Retries are part of the integration

Timeouts and non-2xx responses queue retries after 1 minute, 5 minutes, 15 minutes, 1 hour, 4 hours, and then three daily intervals. The deployment must run server/bin/deliver-webhooks.php every minute for scheduled retries to execute. Requests time out after 10 seconds.

Events can arrive more than once or out of order. Deduplicate by event.id and make the package-credit operation unique by payment ID too. A reversal is a separate event about an existing payment; do not discard it as a duplicate credit. Reconcile delivery failures through the payment and intent APIs.

If a recognized reversal arrives before its original receipt, the gateway reserves that transaction identity with reversed: true. When the credit arrives, it fills the receipt details and emits payment.reversed; it never creates a paid intent. A reversal without a readable transaction ID still requires manual reconciliation.

Verify the signature

Read X-Gateway-Signature: t=…,v1=…. Compute HMAC SHA-256 of the timestamp, a literal dot and the unchanged raw request body, using the entire whsec_… secret as the key.

This helper verifies signed payment events. Handle registration challenges separately using the pending nonce; add your transactional event-storage and queue handler after verification.

function verifyGatewayEvent(string $rawBody, string $header,
    string $secret): array
{
    if ($secret === '' || !preg_match(
        '/^t=([0-9]{1,12}),v1=([a-f0-9]{64})$/D', $header, $parts
    )) {
        throw new RuntimeException('Invalid signature header');
    }

    $timestamp = (int) $parts[1];
    $expected = hash_hmac('sha256', $parts[1] . '.' . $rawBody, $secret);
    if (abs(time() - $timestamp) > 300 ||
        !hash_equals($expected, $parts[2])) {
        throw new RuntimeException('Signature verification failed');
    }

    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($event) || empty($event['id']) || empty($event['type'])) {
        throw new RuntimeException('Invalid event');
    }
    return $event;
}

$event = verifyGatewayEvent(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '',
    getenv('ISP_PAY_WEBHOOK_SECRET') ?: ''
);

// Persist event.id with a UNIQUE constraint and enqueue processing
// in the same database transaction. A duplicate event is a no-op.
// Return 2xx only after that transaction commits.

Reject failed verification without processing the event. Keep server clocks synchronized. The five-minute window applies to the delivery timestamp, not the event's creation time: a valid retry can carry an older event. A valid signature authenticates the gateway event; it does not turn an SMS into a network-signed settlement record.

Payments, review and renewals

Returns {"payments":[…]}, newest first, up to 200 records. Use status=matched, status=unmatched or omit the filter. Records include transaction ID, provider, amount, currency, payer details, reference, hold reason, reversal flag and original message. Restrict access to trusted staff and servers.

Unmatched payments include known_references: accounts previously linked to this payer number. These help your renewal logic but do not prove current account ownership. Choose the package using your account and price data.

{"reference":"hotspot-user-1042","rule":"manual"}

Use rule: "remembered" for a renewal resolved by your server's policy. The response contains payment. Assignment records a reference; it does not activate a router, create a paid intent or emit a new payment.matched webhook. Persist and process the successful response once. Assignment to a different reference after matching is rejected.

Different transaction IDs remain separate payments, even for identical amounts and times. Repeated submissions of the same merchant, provider, receiving account and transaction ID are deduplicated.

“I paid, but I'm not connected.”

Keep recovery in your checkout. A MAC-address change is an account-access problem, not a new purchase. Start with the customer's existing intent and payment status.

{
  "transaction_id": "EXAMPLE123456",
  "payer_ip": "203.0.113.20"
}

Your server sends the customer's transaction ID and the client IP it observed. The gateway must have received the payment within the preceding seven days. Claims check amount, currency, payer number, reversal status and existing association. An invented code never creates a payment. Ambiguous IDs and receipts without a payer number require review; a name alone is insufficient.

An unused receipt requires an unexpired waiting intent. A payment associated with another account cannot be moved by claiming it. If a payment is already linked to an intent for the same reference, a repeat claim returns that original intent after payer and amount checks, without another credit. A claim cannot replace a different payment already attached to the intent.

Payments assigned through /payments/{id}/assign have no linked intent. Recover those through your billing system's saved assignment and payment record; the claim endpoint does not create a replacement intent for them.

Set payer_ip to a valid client IP observed by your trusted server, not a browser-supplied value. If omitted, the gateway uses the request's source IP, which can be your billing server's shared address. Five failed attempts in ten minutes trigger a limit for that merchant and IP. Apply customer/session limits too and avoid exposing account details in public errors. An unreachable router means session state is unknown, not that the account is unused.

Errors & troubleshooting

Handle the machine-readable code and show an appropriate message to the customer.

{"error":{"code":"bad_payer_phone","message":"Enter the full number the money will be sent from."}}

Find the stage that needs attention

• No receipt: check the SIM, listener connection, sender configuration and phone queue.
• Unassociated receipt: inspect number, amount, currency and hold reason; offer Claim payment or review.
• Paid but offline: inspect your activation queue, username, router response and session state.
• Missing webhook: inspect signature errors, endpoint responses and the retry worker; reconcile through the API.

Use the support guide for integration assistance. Share object IDs and sanitized errors, never full keys or webhook secrets.

Before your first live customer

Make the full journey reliable

• Use HTTPS, isolate secrets and verify every payment webhook.
• Validate real receipt formats for each configured provider and receiving account.
• Check that repeated notifications cannot add another package.
• Test phone and webhook outages, a reversal and a failed router login.
• Keep unassociated payments, failed activations and claims visible to staff.
• Agree privacy, reconciliation, support and refund responsibilities.