Integration Guide

Authentication

All API requests must be authenticated using a custom HMAC-SHA256 signature. Include these headers with every request.

Rate Limits

Requests are throttled per client IP and, for transaction submission specifically, also per X-App-ID. Limits apply independently and both can trigger a 429 response.

The per-App-ID limit exists because transact is the one endpoint that triggers a real, synchronous call to the upstream mobile money provider for every request. A burst of concurrent calls from one integration doesn't just throttle that integration, it can degrade the upstream connection for every client on the platform, so it's enforced more strictly and with a cooldown, not just a rolling window.

Integration Flows

Understand the end-to-end process for the most common integration scenarios.

Collection (Receive Money)

Initiate a USSD push payment to a customer's mobile wallet. The customer will receive a prompt on their handset to confirm payment.

{
  "action": "collection",
  "amount": 1000,
  "msisdn": "255700000000",
  "reference": "ORDER_101",
  "callback_url": "https://yourapp.com/callback"
}

{
  "status": "success",
  "transaction_id": "901",
  "payment_status": "PENDING",
  "provider_response": {
    "result": "SUCCESS",
    "resultcode": "000",
    "message": "Payment notification logged"
  }
}

Disbursement (Send Money)

Send funds to various channels. Use the channel field to route the disbursement to the correct network or bank.

Card Payments & Checkout

There are two ways to process card payments: using a Hosted Checkout (for new cards) or Stored Card Tokens (for one-tap payments).

Hosted Checkout (New Cards)

Use the checkout action to receive a payment_gateway_url where the customer can enter their card details.

{
  "action": "checkout",
  "amount": 10000,
  "reference": "INV-1001",
  "billing_firstname": "John",
  "billing_lastname": "Doe",
  "billing_address_1": "969 Market Street",
  "billing_city": "San Francisco",
  "billing_state_or_region": "CA",
  "billing_postcode_or_pobox": "94103",
  "billing_country": "US",
  "billing_phone": "255000000000",
  "redirect_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Stored Card Payment (One-tap)

Use the card-payment action with a previously obtained card_token.

{
  "action": "card-payment",
  "amount": 5000,
  "reference": "INV-202",
  "card_token": "CT_987654321",
  "buyer_userid": "user_123",
  "gateway_buyer_uuid": "GB_uuid_001"
}

Card Management

List and delete stored card tokens for a user. This allows you to provide a "saved cards" experience in your checkout flow.

List Stored Cards

{
  "status": "success",
  "data": [
    {
      "card_token": "CT_987654321",
      "card_number": "411111XXXXXX1111",
      "expiry": "12/26",
      "card_type": "VISA"
    }
  ]
}

Delete Card

Parameter in URL: id (The index or card token to remove)

Virtual Card Network (VCN)

Issue and manage secure virtual cards for your customers. These cards can be used for online payments worldwide.

Issue New VCN

{
  "msisdn": "255700000000",
  "email": "user@example.com",
  "name": "John Doe"
}

Change VCN Status

Show Full Card Details

⚠️ Secure Endpoint: Only call when the user enters their PIN on your UI.

Get VCN Details & Balance

Name Lookup

Validate recipient details before sending funds. Supports wallet (mobile money), bank account, and Selcom Pesa lookups.

Wallet Lookup

{
  "type": "wallet",
  "channel": "vodacom",
  "msisdn": "255754000000"
}

Bank Account Lookup

{
  "type": "bank",
  "bank_code": "CRDB",
  "account_number": "01J12345678900"
}

Sample Response

{
  "status": "success",
  "name": "Jane Doe",
  "original_data": { ... }
}

Transaction Query

Check the current status of a transaction using your internal reference. For pending transactions, the middleware will automatically attempt a live status check with the provider.

{
  "reference": "ORDER_101"
}

{
  "status": "SUCCESS",
  "reference": "ORDER_101",
  "amount": 1000,
  "currency": "TZS",
  "payment_status": "COMPLETED",
  "created_at": "2024-01-15 10:30:00",
  "provider_checked": true,
  "provider_message": null
}

If payment_status is still PENDING, check provider_checked: true means we successfully reached the provider and the transaction is genuinely still pending; false means the live check itself failed (see provider_message) and you should retry shortly rather than treating it as confirmed.

Live provider checks are rate-limited per transaction: at most one every 30 seconds, and only for transactions created within the last hour. Outside those limits the stored status is returned with provider_checked: false. Older pending transactions are still resolved automatically by the provider callback and our background reconciliation, and you'll receive your callback_url webhook when they are, so there's no need to keep polling them.

Account Summary

Retrieve a financial summary for your application including total volume and transaction counts, with a breakdown by collections vs. disbursements the two have unrelated failure modes and shouldn't be read as one blended number.

{} // No body required

{
  "status": "SUCCESS",
  "data": {
    "collections": {
      "total_count": 150,
      "total_volume": 3800000,
      "success_count": 140,
      "pending_count": 2,
      "failed_count": 8,
      "delivered_count": 148
    },
    "disbursements": { "...same shape" },
    "account_balance": 3150000
  }
}

account_balance is your current available app balance (successful collections minus successful/pending disbursements and fees), scoped to live or sandbox depending on whether the X-Sandbox header was sent. Collections and disbursements are always reported separately there is no combined total, since the two have unrelated failure modes.

success_count is the real completed-payment count (status = 'success') the same thing account_balance is computed from. delivered_count counts requests that left our system and were accepted by the provider for collections that means the payment prompt actually reached the customer's phone; for disbursements it means the provider processed the payout. Neither field is redefined by this endpoint; that distinction only affects how the admin/portal dashboards label a number for humans, not this data contract. Rate/percentage fields (delivery rate, completion rate) are temporarily removed from this response while their definitions are finalized.

Webhooks (Callbacks)

Payme Africa does not require pre-registration of webhooks. Instead, you must provide a callback_url in each /transact request. The gateway will send an asynchronous POST request to this URL when the transaction reaches a final state.

Status Descriptions

Sample Webhook Payload

{
  "transid": "7945454515",
  "reference": "ORDER_101",
  "result": "SUCCESS",
  "payment_status": "COMPLETED",
  "amount": "1000",
  "msisdn": "255700000000"
}

Verifying Webhook Signatures

To ensure the webhook came from the middleware, you must verify the X-Middleware-Signature header.

$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_MIDDLEWARE_SIGNATURE'];

$expected  = base64_encode(
    hash_hmac('sha256', $payload . $timestamp, $secret, true)
);

if (hash_equals($signature, $expected)) {
    // ✓ Verified process the webhook safely
}

Transaction Result Codes

Common result codes returned in API responses and webhook payloads.

Supported Channels & Banks

Use these codes in the channel and recipient_bank_code request fields.

Mobile Networks

Popular Banks (Qwiksend)