Implementation Guide

Nkwa Pay simplifies integrating mobile money into your payment flows across Cameroon. Our API supports both collections (customer-to-business) and disbursements (business-to-customer) in an asynchronous, high-performance environment designed for reliability.

Key Features and Architecture

Standardized endpoints for initiating and querying payment status
24/7 operations monitoring with automatic suspension of underperforming MNOs
Built‑in reconciliation for any “pending” transactions when MNO systems degrade
Webhooks (callbacks) to notify you of final payment outcomes
Multiple language SDKs to accelerate your integration process

The following sections introduce important aspects of mobile money integration and working with Nkwa Pay’s API to help you build a high-quality payment experience.

MNO Stability Management

Our 24/7 payment operations team monitors all Mobile Network Operators (MNOs) on our platform for instability and downtime. We automatically stop accepting payments to those MNOs if the success rate drops below acceptable thresholds. This information is accessible from our availability endpoint, which you can poll to adjust your application’s behavior accordingly. Sometimes MNO systems experience degraded performance. When that happens, their APIs might have trouble returning the final status of payments (stuck in pending). In such cases, Nkwa Pay ensures these payments are reconciled manually. This means that when using Nkwa Pay, all payments are always reconciled to their final status. This reconciliation process takes a little longer than processing during normal operations but guarantees payment status integrity.

Asynchronous API with Webhooks

Nkwa Pay’s API is fully asynchronous. This design is necessary to provide high performance and reliable payment infrastructure across unreliable mobile networks. When you create a payment (collection or disbursement), you’ll get an initial response that confirms whether the payment was accepted for processing. There are two ways to determine the final status of a payment:

1. Webhook Callbacks (Recommended)

Configure a callback URL in our portal to automatically receive notifications when a payment reaches its final status. You’ll need to implement a callback handler in your application that can receive and process these notifications. Your endpoint must accept an HTTP POST request containing: Headers

X-Signature: <sig>
X-Timestamp: <ts>

Body The request body contains the payment object. Refer to the Collection or Disbursement API reference for the full object definition.

Webhooks are currently not retried. Your endpoint must return a 200 response if the event is received successfully.

Understanding the Webhook Fields

ts — Timestamp: Milliseconds since Unix epoch. It indicates when the webhook event was generated on our servers. sig — Signature: A base64 encoded cryptographic signature used to verify the authenticity of the webhook.

Verify signature

Recompose the message

msg = ts + your_callback_url + json_body

Then verify the message as

function verifySignature(publicKey, message, signatureBase64):

    // Step 1: Decode the signature from Base64
    signature = Base64Decode(signatureBase64)

    // Step 2: Compute the SHA-256 digest of the message
    digest = SHA256(message)

    // Step 3: Use your cryptography library to verify that
    //         'signature' is a valid signature of 'digest'
    //         using the provided 'publicKey'.

    isValid = PublicKeyVerify(
        publicKey  = publicKey,
        message    = digest,
        signature  = signature,
        algorithm  = "RSA",
        hash       = "SHA-256",
        padding    = "PKCS#1 v1.5"
    )

Our public key can be found in the settings section of the merchant dashboard.

2. Polling

Use the corresponding Get payment/:id endpoint periodically to check if the payment has reached its final status. While simpler to implement, this approach is less efficient and may introduce delays in payment status awareness.

Implementing Webhooks

When implementing your callback handler, consider the following best practices:

Public Accessibility: Your endpoint should be accessible to our platform
IP Whitelisting: If you use IP whitelisting, allow our sending IPs: [ip1, ip2, ip3]
Authentication Exclusion: Exclude the callback endpoint from your application’s regular authentication system
Idempotency: Your endpoint must be idempotent to handle potential duplicate callbacks
HTTP Method: Accept POST requests with the payment details in the request body
Response Code: Return HTTP 200 OK to acknowledge receipt of the callback
SSL Security: Use SSL certificates from a trusted CA
Retry Handling: We will attempt to deliver callbacks for 15 minutes, retrying every minute if we don’t receive a 200 OK

Integration Best Practices

Retry Logic: Design your application to handle temporary MNO unavailability gracefully
MNO Monitoring: Poll /availability regularly (e.g., once per hour) to detect MNO degradations and adjust customer messaging accordingly
Error Handling: Implement comprehensive error handling to manage various payment failure scenarios
Idempotency: Generate and store unique transaction references to prevent duplicate payments
Testing: Thoroughly test your integration in the sandbox environment before moving to production
Security: Protect API keys and follow security best practices for handling payment data

By following these implementation guidelines, you’ll create a robust and reliable mobile money payment experience for your customers using Nkwa Pay.

​Implementation Guide

​Key Features and Architecture

​MNO Stability Management

​Asynchronous API with Webhooks

​1. Webhook Callbacks (Recommended)

​Understanding the Webhook Fields

​Verify signature

​2. Polling

​Implementing Webhooks

​Integration Best Practices

Implementation Guide

Key Features and Architecture

MNO Stability Management

Asynchronous API with Webhooks

1. Webhook Callbacks (Recommended)

Understanding the Webhook Fields

Verify signature

2. Polling

Implementing Webhooks

Integration Best Practices