Implementation considerations - PawaPay Merchant API

The PawaPay Merchant API simplifies integrating mobile money into your payment flows. It provides a single standardised API to connect to Mobile Money Operators (MMOs) providing mobile money services across Africa. The following chapters introduce some important aspects of mobile money and working with financial APIs to help you build a high-quality integration that your customers will love and that is easy to operate.

MMO stability

As described in the Introduction, mobile money transaction chains are complex. This means that the stability of payment services needs to be taken into account when implementing a high-quality payment flow. PawaPay provides multiple solutions to make this easy to manage. Our 24/7 payment operations team monitors all MMOs on our platform for instability and downtime. We stop accepting payments to those MMOs if the success rate is too low. This information is accessible from our availability endpoint. You can verify before initiating the payment if the MMO is currently experiencing any problems and inform the user before they attempt the payment. Knowing that your mobile money provider is currently unavailable is a better customer experience than having your payment fail. Failed payments usually take longer to process, leaving the customer waiting for the final result. Read more about our availability endpoint. To provide the best support for your customers, information about MMO availability is also published in the PawaPay Dashboard and Status page. You can subscribe to updates over e-mail, Slack and other channels to ensure your support team is always informed about any potential problems with the MMOs. When an MMO is experiencing difficulties in successfully processing disbursements, our platform will enqueue them to be processed once the MMO is operational. Read more about enqueued payouts. Occasionally, MMOs experience degraded system performance, which can prevent their APIs from returning the final status of payments. During these periods, our platform continues to accept and process payments. We reconcile these transactions through alternative methods using our reconciliation engine. This ensures that, when using PawaPay, all payments are eventually reconciled to their final status. Please note that this process may take slightly longer than during normal operations.

Transaction limits

Mobile money wallets have different limits for transactions. Most common and relevant are:

Maximum amount of deposits/payouts in a day/week/month.
Maximum number of deposits/payouts in a day/week/month.
Maximum balance of a mobile money wallet.

All MMOs that you transact with through PawaPay have transaction limits. These are the lowest and highest amounts that can be collected, disbursed or refunded with the specific MMO. They are based on the limits of the most common wallet types of this MMO. As the effective limits depend on the specific user’s transaction history, transactions may still fail due to hitting limits.

For example, an MMO has a 1,000 GHS maximum deposit amount. In reality the wallet has a limitation of 1,000 GHS total transaction value per day/week/month. If the user has already transacted 500 GHS during this period, a transaction of 700 GHS might still fail even though it is accepted by PawaPay.

You can easily find the transaction limits from our active configuration endpoint.

Asynchronous API

The PawaPay Merchant API is asynchronous. This is necessary to provide high performance and quality payment infrastructure that is able to process millions of payments every day. When you call any financial endpoint (payout, deposit, refund), the response will confirm whether the transaction has been accepted or rejected for processing. Reasons for rejecting a transaction might be using the same ID for transactions more than once or the MMO being unavailable at the moment. If the response confirms that the payment has been accepted for processing, it will take some time for it to process (remember that for deposits, the user needs to enter their PIN on their phone). There are two ways to find out about the final status of a payment.

Through callbacks

First, you can configure callback URLs in the PawaPay Dashboard. This will automatically send a callback to your configured callback URL as soon as a payment has reached its final status. You will have to implement a callback handler that is able to receive calls from our platform and handle them accordingly.

Polling for status

Second, you can use the corresponding Check Status endpoint for the transaction type to periodically check the status of a payment.

Handling callbacks

When implementing your callback handler, please consider the following points.

The endpoint should be accessible to our platform.
- If you are using IP whitelisting, our sending IPs are documented here.
- Ensure that you have excluded the callback endpoint from your application’s regular authentication system.
Your endpoint for receiving callbacks must be idempotent.
Your endpoint needs to allow us to POST the callback.
We expect you to return HTTP 200 OK response to consider the callback delivered.
Make sure you use an SSL certificate from a trusted CA.
We will make up to 8 delivery attempts over approximately 25 minutes. See Callback delivery attempts below.
If the callback delivery fails, you can trigger a resend of the callback within 90 days of the payment being initiated. This can be done by:
- Calling the respective Resend callback endpoint
- Manually from the PawaPay Dashboard.
- For payments older than 90 days, callbacks can no longer be resent. The status of the payment remains available through the Check Status endpoints.

Callback delivery attempts

When a payment reaches its final status, we send the callback straight away. If your endpoint does not return HTTP 200 OK, we try again on the following schedule.

Attempt	Sent at	Wait before next attempt
1	0:00	1 minute
2	1:00	1 minute
3	2:00	3 minutes
4	5:00	5 minutes
5	10:00	5 minutes
6	15:00	5 minutes
7	20:00	5 minutes
8	25:00	—

Times are measured from when the callback is first sent. They are approximate.
Once your endpoint returns HTTP 200 OK, the callback is delivered and no further attempts are made.
If attempt 8 (around 25 minutes) also fails, we stop retrying. You can then:
- Resend the callback: deposits, payouts, refunds.
- Get the final status: deposits, payouts, refunds.
Because of retries, your endpoint may receive the same callback more than once. This is why it must be idempotent.

Timeouts and slow responses

We wait up to 10 seconds to establish a connection to your callback URL and up to 30 seconds for a response. If either is exceeded, the attempt counts as failed.
Respond with HTTP 200 OK as soon as you have received the callback and process it asynchronously. Do not hold the connection open while you run your own business logic.
If we detect slow responses or HTTP 429 Too Many Requests from your callback URL, we may skip some callback delivery attempts to avoid adding to the load on your system.

Safe handling

As PawaPay’s Merchant API is a financial API, status and error handling should be implemented defensively. All our financial transaction endpoints require you to specify a unique ID for the transaction. This allows you to always verify whether the payment was received by PawaPay and verify its status. All statuses of payment initiations, status checks (Check Status) and callbacks should be explicitly handled. Following handling should NOT be used:

    if( status == "COMPLETED" ) {
        creditCustomer();
    } else {
        failPayment();
    }

Instead, all statuses should be explicitly listed and unknown situations should be escalated.

    if( status == "COMPLETED" ) {
        creditCustomer();
    } else if ( status == "FAILED" ) {
        failPayment();
    } else {
        //escalate and leave the transaction as pending.
        informOperations();
    }

Special attention needs to be given to network-related errors as well. The following handling should NOT be used:

    try  {
        PawaPay.deposit();
    } catch (InterruptedException e) {
        failPayment();
    }

Instead, you have two options to ensure no discrepancies are created. First, you can leave the transaction pending in your system and inform your operations. All payments accepted for processing are visible in the PawaPay Dashboard. Whether the payment was accepted by PawaPay and what its status is can be verified there. Second, you can use the corresponding Check status endpoint to validate if the request was received by PawaPay. Since you always know the unique ID of the transaction, you can always verify the status of the payment on the PawaPay platform, even if no response was received when initiating the payment.

Automatic reconciliation

Implementing the considerations listed above avoids almost all discrepancies of payment statuses between your system and PawaPay. When using callbacks to receive the final statuses of payments, issues like network connectivity, system downtime, and configuration errors might cause the callback not to be received by your system. To avoid keeping your customers waiting, we strongly recommend implementing a status recheck cycle. For example, a periodic job that collects all payments that have been pending for an extended period. It can then query the respective Check status endpoint to verify the status of the payment. If the status recheck cycle finds a payment in a final state, you can use the respective Resend callback endpoint to trigger a callback to be resent. This avoids duplicating processing logic.

Backwards compatibility

The PawaPay Merchant API is always backwards compatible, but should not be strictly verified against the schema as backwards compatible changes might be introduced.

Brand guidelines

When integrating with Mobile Money Operators (MMOs), refer to the provided brand guidelines in this section. These documents outline the proper use of logos, color schemes, and typography, ensuring consistent and compliant representation of each operator’s brand identity.

MTN - https://momodeveloper.mtn.com/api-documentation/brand-guidelines
Airtel - https://developers.airtel.africa/brand-guidelines
Orange - https://boosted.orange.com/docs/4.4/about/brand/
MPESA - https://www.safaricom.co.ke/about/brand-toolkit

​MMO stability

​Transaction limits

​Asynchronous API

​Through callbacks

​Polling for status

​Handling callbacks

​Callback delivery attempts

​Timeouts and slow responses

​Safe handling

​Automatic reconciliation

​Backwards compatibility

​Brand guidelines