​
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:

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.

​
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.