Integration Guide

Authentication

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

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"
}

Account Summary

Retrieve a financial summary for your application including total volume, success counts, and overall success rate.

{} // No body required

{
  "status": "SUCCESS",
  "data": {
    "total_volume": 4200000,
    "total_count": 182,
    "success_count": 175,
    "failed_count": 5,
    "pending_count": 2,
    "success_rate": 96.15
  }
}

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)