Mobile money is a form of digital money, where instead of a bank account and a card, people get a mobile money wallet connected to their phone number. When people sign up for a mobile money account with their Mobile Network Operator (MNO), they go through KYC just like with a bank account. Instead of ATMs and bank branches, you can put money on your mobile money wallet through an extensive agent network. Instead of getting a bank account number/IBAN, your mobile money wallet is identified by your phone number. It allows users to send money to and receive money from other mobile money users, pay their bills, pay merchants online, receive their salary etc.

Mobile money wallets have transaction limits like many modern bank accounts and cards. Most important limits are:

• Number of payments done within a day, week or month.
• Value of payments done within a day, week or month.
• Maximum balance of a mobile money wallet.

Users can get those limits increased by going through extended KYC processes with the MNOs.

Mobile money payments are different from classic cards payments. They are more similar to A2A or 3-D Secure enabled card payments. Specifically, user has to explicitly authorise each payment. When a user attempts to pay from their mobile money wallet, they need to enter their mobile money PIN code to authorise the payment. The PIN code is only known by the issuer (MNO) and the owner the mobile money wallet. Authorisation happens between those two parties and the merchant is not involved. The owner of the mobile money wallet always receives an SMS receipt whenever their balance changes.d This makes mobile money payments much more secure than classic card payments reducing fraud and chargeback risk to a minimum.

This has two important implications.

First, this expands the technical infrastructure involved in processing every single payment. Since the user needs to enter their mobile money PIN code to authorise each payment, both the server infrastructure and the cell network infrastructure are involved in the payment chain. The PIN code is usually requested from the user by sending a USSD message over the cell network and utilising the handsets SIM toolkit to handle user interaction. This gives mobile money incredible accessibility as it works securely on everything from the simplest of push-button handsets all the way to flagship smartphones. On the flip side, there's a lot involved from server infrastructure, internet connectivity, cell networks, USSD gateways etc.

Second, the user is now part of the processing chain of each transaction. A user attempting to initiate a payment on your website or app needs to take out their handset and enter their PIN in a limited amount of time. Or they might not find their phone, accidentally close the PIN prompt, forget their PIN code, get a phone call etc.

To conclude, mobile money is highly accessible and secure. The challenges to ensure high success rates and a great customer experience are different from other payment methods.

With the pawaPay Merchant API you can easily transact with you customers any way you need:

• You can collect money from them Money will move from the customers mobile money wallet into your account in pawaPay. You can do that with our Deposits functionality.
• You can disburse money to them Money will move from your account in pawaPay to the customers mobile money wallet. You can do that with our Payouts functionality.
• You can refund them Already collected funds will move back from your account in pawaPay to the customers mobile money wallet. You can do that with our Refunds functionality.

The pawaPay Merchant API simplifies integrating mobile money into your payment flows. It provides a single standardised API to connect to Mobile Network Operators (MNOs) providing mobile money services across Africa. 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 love and is easy to operate.

As described in the Introduction, mobile money transaction chains are complex. This means that payment services stability 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 MNOs on our platform for instability and downtime. We stop accepting payments to those MNOs if the success rate is too low. This information is accessible from our availability endpoint. You can verify before initiating the payment if the MNO 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 clarity for longer. Read more about our availability endpoint.

For customer support purposes, information about MNOs availability is also published on our 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 MNOs.

When an MNO is experiencing difficulties in successfully processing disbursements, our platform will enqueue them to be processed once the MNO is operational. Read more about enqueued payouts.

Sometimes MNOs systems have degraded performance. When that happens, the MNOs APIs might have trouble returning the final status of payments. Our platform still accepts payments for processing during those times. These payments are reconciled through other means with the MNO using our reconciliation engine. This means that When using pawaPay, all payments are always reconciled to their final status. This process takes a little longer than processing during normal operations.

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 MNOs that you transact with using pawaPay have transaction limits. These are the lowest and highest amounts that can be collected, disbursed or refunded with the specific MNO. They are based on the limits of the most common wallet types of this MNO. As the effective limits are dependent on the specific users transaction history, transaction may still fail due to hitting limits.

For example, an MNO 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 might still fail.

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

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 was accepted for processing or rejected. Reasons for rejecting a transaction might be using the same ID for transaction more than once or the MNO 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.

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

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

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 IP-s are documented here.
  • Ensure that you have excluded the callback endpoint from your applications 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 certificates from a trusted CA.
• We will attempt to deliver callbacks for 15 minutes.
• If the callback delivery fails, you can always trigger a resend of the callback. This can be done by:
  • Calling the respective Resend callback endpoint
  • Manually from our portal.

As pawaPays 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 it's status.

All statuses of payment initiations, status checks (Get Status and Details) and callbacks should be explicitly handled.

Following handling should NOT be used:

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

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

  if( status == "COMPLETED" ) {
    creditCustomer();
  } else if ( status == "FAILED" ) {
    failPayment();
  } else {
    //escalate and leave 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 our portal. Whether the payment was accepted by pawaPay and what is it's status can be verified from there.

Second, you can use the corresponding Get status and details 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.

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, things like network connectivity issues, system downtime and configuration errors might cause the callback to not be recieved 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 a while. It can then query the respective Get status and details 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.

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

When integrating with mobile network operators, 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

When creating an account with pawaPay, you will first receive access to our sandbox environemnt. The sandbox environment is completely isloated from our production environment. You can safely test your integration with pawaPay without real mobile money wallets and real money involved. You will get access to your production account when you have completed the onboarding on your sandbox account.

The base URL for the pawaPay Merchant API is different between our sandbox and production environments. The specific operation can be called by appending the endpoint to the base URL.

Example: https://api.sandbox.pawapay.cloud/payouts

Environment	Base URL
Sandbox	https://api.sandbox.pawapay.cloud/
Production	https://api.pawapay.cloud/

The base URL and the authentication token are the only things that change between using pawaPay Merchant API in our sandbox and in production. These should be a part of your applications environment specific configuration.

The pawaPay Merchant API uses bearer token for authentication. An authorization header is required for all calls to the pawaPay Merchant APIs except for MNO Availability.

The token can be generated from our portal. Instructions on how to do that can be found in our portal documentation.

The token generated from your sandbox account can only be used for authenticating against the Merchant API in sandbox. For authenticating against the Merchant API in production, a separate token must be generated with your live account.

As our sandbox environment is completely isolated from our production environment, the URLs for the portal are also different.

Environment	Portal URL
Sandbox	https://dashboard.sandbox.pawapay.cloud/
Production	https://dashboard.pawapay.cloud/

The base URL and the authentication token are the only things that change between using the Merchant API in our sandbox and in production. These should be a part of your applications environment specific configuration.

Below is an example payout request with curl:

curl -i -X POST |
https://api.sandbox.pawapay.cloud/payouts \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"payoutId": "<UUID>",
"amount": "15",
"currency": "ZMW",
"country": "ZMB",
"correspondent": "MTN_MOMO_ZMB",
"recipient": {
  "type": "MSISDN",
  "address": {
    "value": "260763456789"
  }
},
  "customerTimestamp": "2020-02-21T17:32:28Z",
  "statementDescription": "Note of 4 to 22 chars"
}'

The pawaPay Merchant API is asyncrhonous. You can read more from Asynchronous API.

Callback URLs are configured from our portal. You can find instructions on how to do that from our portal documentation.

When using callbacks, please ensure the following IP addresses are whitelisted to ensure we can reliably deliver callbacks to you.

Environment	IP
Sandbox	3.64.89.224/32
Production	18.192.208.15/32
Production	18.195.113.136/32
Production	3.72.212.107/32
Production	54.73.125.42/32
Production	54.155.38.214/32
Production	54.73.130.113/32

Correspondents in our Merchant API refer to the specific Mobile Network Operators (MNOs) that are available through our platform. The parameters that define the destination of the payment are correspondent and payer for Deposits or recipient for Payouts. This routes the payment to the correct person (specified by the MSISDN) on the correct mobile network (specified by the correspondent).

You can always check which correspondents are available on your account from the active configuration endpoint.

You can use the predict-correspondent endpoint to predict the MNO for a phone number (MSISDN).

The amount of decimal places that can be specified as the amount of the transaction vary between different MNOs. You can find the list of all available correspondents, their currency and supported decimal places below.

Benin

MNO	Correspondent	Country	Currency	Decimals in amount
MTN	MTN_MOMO_BEN	BEN	XOF	Not supported
MTN	MOOV_BEN	BEN	XOF	Not supported

Cameroon

MNO	Correspondent	Country	Currency	Decimals in amount
MTN	MTN_MOMO_CMR	CMR	XAF	Not supported
Orange	ORANGE_CMR	CMR	XAF	Not supported

Côte d'Ivoire (Ivory Coast)

MNO	Correspondent	Country	Currency	Decimals in amount
MTN	MTN_MOMO_CIV	CIV	XOF	Not supported
Orange	ORANGE_CIV	CIV	XOF	Not supported

Democratic Republic of the Congo

MNO	Correspondent	Country	Currency	Decimals in amount
Vodacom	VODACOM_MPESA_COD	COD	CDF	2 places
Airtel	AIRTEL_COD	COD	CDF	2 places
Orange	ORANGE_COD	COD	CDF	2 places

Ghana

MNO	Correspondent	Country	Currency	Decimals in amount
MTN	MTN_MOMO_GHA	GHA	GHS	2 places
AT	AIRTELTIGO_GHA	GHA	GHS	2 places
Vodafone	VODAFONE_GHA	GHA	GHS	2 places

Kenya

MNO	Correspondent	Country	Currency	Decimals in amount
MPesa	MPESA_KEN	KEN	KES	Deposits: not supported; payouts: 2 places

Malawi

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_MWI	MWI	MWK	2 places
TNM	TNM_MWI	MWI	MWK	2 places

Mozambique

MNO	Correspondent	Country	Currency	Decimals in amount
Vodacom	VODACOM_MOZ	MOZ	MZN	2 places

Nigeria

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_NGA	NGA	NGN	Not supported
MTN	MTN_MOMO_NGA	NGA	NGN	2 places

Rwanda

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_RWA	RWA	RWF	Not supported
MTN	MTN_MOMO_RWA	RWA	RWF	Not supported

Senegal

MNO	Correspondent	Country	Currency	Decimals in amount
Free	FREE_SEN	SEN	XOF	Not supported
Orange	ORANGE_SEN	SEN	XOF	Not supported

Sierra Leone

MNO	Correspondent	Country	Currency	Decimals in amount
Orange	ORANGE_SLE	SLE	SLE	2 places

Tanzania

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_TZA	TZA	TZS	2 places
Vodacom	VODACOM_TZA	TZA	TZS	2 places
Tigo	TIGO_TZA	TZA	TZS	Not supported
Halotel	HALOTEL_TZA	TZA	TZS	Not supported

Uganda

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_OAPI_UGA	UGA	UGX	Not supported
MTN	MTN_MOMO_UGA	UGA	UGX	2 places

Zambia

MNO	Correspondent	Country	Currency	Decimals in amount
Airtel	AIRTEL_OAPI_ZMB	ZMB	ZMW	2 places
MTN	MTN_MOMO_ZMB	ZMB	ZMW	2 places
Zamtel	ZAMTEL_ZMB	ZMB	ZMW	2 places

As part of using the pawaPay platform, you will have access to our sandbox environment. Your sandbox account will have access to all the MNOs available on our platform. You can safely test your integration without any real mobile money wallets and real money involved. In sandbox, we have also created special phone numbers (MSISDNs) that can be used to test different scenarios.

Benin - MTN (MTN_MOMO_BEN)

Deposits

MSISDN	failureCode
22951345029	PAYER_NOT_FOUND
22951345039	PAYMENT_NOT_APPROVED
22951345069	OTHER_ERROR
22951345129	NO CALLBACK (stuck in SUBMITTED state)
22951345789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
22951345089	RECIPIENT_NOT_FOUND
22951345119	OTHER_ERROR
22951345129	NO CALLBACK (stuck in SUBMITTED state)
22951345789	N/A (COMPLETED)

Benin - MOOV (MOOV_BEN)

Deposits

MSISDN	failureCode
22995345679	PAYMENT_NOT_APPROVED
22995345529	OTHER_ERROR
22995345639	NO CALLBACK (stuck in SUBMITTED state)
22995345789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
22995345219	OTHER_ERROR
22995345279	NO CALLBACK (stuck in SUBMITTED state)
22995345789	N/A (COMPLETED)

Cameroon - MTN (MTN_MOMO_CMR)

Deposits

MSISDN	failureCode
237653456019	PAYER_LIMIT_REACHED
237653456029	PAYER_NOT_FOUND
237653456039	PAYMENT_NOT_APPROVED
237653456069	OTHER_ERROR
237653456129	NO CALLBACK (stuck in SUBMITTED state)
237653456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
237653456089	RECIPIENT_NOT_FOUND
237653456119	OTHER_ERROR
237653456129	NO CALLBACK (stuck in SUBMITTED state)
237653456789	N/A (COMPLETED)

Cameroon - Orange (ORANGE_CMR)

Deposits

MSISDN	failureCode
237693456019	PAYER_LIMIT_REACHED
237693456029	PAYER_NOT_FOUND
237693456039	PAYMENT_NOT_APPROVED
237693456049	INSUFFICIENT_BALANCE
237693456069	OTHER_ERROR
237693456129	NO CALLBACK (stuck in SUBMITTED state)
237693456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
237693456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
237693456119	OTHER_ERROR
237693456129	NO CALLBACK (stuck in SUBMITTED state)
237693456789	N/A (COMPLETED)

Côte d'Ivoire - MTN (MTN_MOMO_CIV)

Deposits

MSISDN	failureCode
2250503456029	PAYER_NOT_FOUND
2250503456039	PAYMENT_NOT_APPROVED
2250503456069	OTHER_ERROR
2250503456129	NO CALLBACK (stuck in SUBMITTED state)
2250503456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
2250503456089	RECIPIENT_NOT_FOUND
2250503456119	OTHER_ERROR
2250503456129	NO CALLBACK (stuck in SUBMITTED state)
2250503456789	N/A (COMPLETED)

Democratic Republic of the Congo - Vodacom (VODACOM_MPESA_COD)

Deposits

MSISDN	failureCode
243813456019	PAYER_LIMIT_REACHED
243813456029	PAYER_NOT_FOUND
243813456039	PAYMENT_NOT_APPROVED
243813456049	INSUFFICIENT_BALANCE
243813456069	OTHER_ERROR
243813456129	NO CALLBACK (stuck in SUBMITTED state)
243813456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
243813456089	RECIPIENT_NOT_FOUND
243813456119	OTHER_ERROR
243813456129	NO CALLBACK (stuck in SUBMITTED state)
243813456789	N/A (COMPLETED)

Democratic Republic of the Congo - Airtel (AIRTEL_COD)

Deposits

MSISDN	failureCode
243973456069	OTHER_ERROR
243973456129	NO CALLBACK (stuck in SUBMITTED state)
243973456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
243973456089	RECIPIENT_NOT_FOUND
243973456119	OTHER_ERROR
243973456129	NO CALLBACK (stuck in SUBMITTED state)
243973456789	N/A (COMPLETED)

Democratic Republic of the Congo - Orange (ORANGE_COD)

Deposits

MSISDN	failureCode
243893456029	PAYER_NOT_FOUND
243893456039	PAYMENT_NOT_APPROVED
243893456049	INSUFFICIENT_BALANCE
243893456069	OTHER_ERROR
243893456129	NO CALLBACK (stuck in SUBMITTED state)
243893456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
243893456119	OTHER_ERROR
243893456129	NO CALLBACK (stuck in SUBMITTED state)
243893456789	N/A (COMPLETED)

Ghana - MTN (MTN_MOMO_GHA)

Deposits

MSISDN	failureCode
233593456019	PAYER_LIMIT_REACHED
233593456029	PAYER_NOT_FOUND
233593456039	PAYMENT_NOT_APPROVED
233593456069	OTHER_ERROR
233593456129	NO CALLBACK (stuck in SUBMITTED state)
233593456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
233593456089	RECIPIENT_NOT_FOUND
233593456119	OTHER_ERROR
233593456129	NO CALLBACK (stuck in SUBMITTED state)
233593456789	N/A (COMPLETED)

Ghana - AT (AIRTELTIGO_GHA)

Deposits

MSISDN	failureCode
233273456069	OTHER_ERROR
233273456129	NO CALLBACK (stuck in SUBMITTED state)
233273456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
233273456089	RECIPIENT_NOT_FOUND
233273456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
233273456119	OTHER_ERROR
233273456129	NO CALLBACK (stuck in SUBMITTED state)
233273456789	N/A (COMPLETED)

Ghana - Vodafone (VODAFONE_GHA)

Deposits

MSISDN	failureCode
233503456039	PAYMENT_NOT_APPROVED
233503456049	INSUFFICIENT_BALANCE
233503456069	OTHER_ERROR
233503456129	NO CALLBACK (stuck in SUBMITTED state)
233503456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
233503456089	RECIPIENT_NOT_FOUND
233503456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
233503456119	OTHER_ERROR
233503456129	NO CALLBACK (stuck in SUBMITTED state)
233503456789	N/A (COMPLETED)

Kenya - MPesa (MPESA_KEN)

Deposits

MSISDN	failureCode
254703456019	PAYER_LIMIT_REACHED
254703456039	PAYMENT_NOT_APPROVED
254703456049	INSUFFICIENT_BALANCE
254703456059	TRANSACTION_ALREADY_IN_PROCESS
254703456069	OTHER_ERROR
254703456129	NO CALLBACK (stuck in SUBMITTED state)
254703456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
254703456089	RECIPIENT_NOT_FOUND
254703456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
254703456109	RECIPIENT_LIMIT_REACHED
254703456119	OTHER_ERROR
254703456129	NO CALLBACK (stuck in SUBMITTED state)
254703456789	N/A (COMPLETED)

Malawi - Airtel (AIRTEL_MWI)

Deposits

MSISDN	failureCode
265993456049	INSUFFICIENT_BALANCE
265993456069	OTHER_ERROR
265993456129	NO CALLBACK (stuck in SUBMITTED state)
265993456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
265993456089	RECIPIENT_NOT_FOUND
265993456119	OTHER_ERROR
265993456129	NO CALLBACK (stuck in SUBMITTED state)
265993456789	N/A (COMPLETED)

Malawi - TNM (TNM_MWI)

Deposits

MSISDN	failureCode
265883456049	INSUFFICIENT_BALANCE
265883456069	OTHER_ERROR
265883456129	NO CALLBACK (stuck in SUBMITTED state)
265883456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
265883456089	RECIPIENT_NOT_FOUND
265883456119	OTHER_ERROR
265883456129	NO CALLBACK (stuck in SUBMITTED state)
265883456789	N/A (COMPLETED)

Nigeria - Airtel (AIRTEL_NGA)

Deposits

MSISDN	failureCode
2349034567069	OTHER_ERROR
2349034567129	NO CALLBACK (stuck in SUBMITTED state)
2349034567899	N/A (COMPLETED)

Payouts

MSISDN	failureCode
2349034567089	RECIPIENT_NOT_FOUND
2349034567119	OTHER_ERROR
2349034567129	NO CALLBACK (stuck in SUBMITTED state)
2349034567899	N/A (COMPLETED)

Nigeria - MTN (MTN_MOMO_NGA)

Deposits

MSISDN	failureCode
2348134567019	PAYER_LIMIT_REACHED
2348134567029	PAYER_NOT_FOUND
2348134567039	PAYMENT_NOT_APPROVED
2348134567069	OTHER_ERROR
2348134567129	NO CALLBACK (stuck in SUBMITTED state)
2348134567899	N/A (COMPLETED)

Payouts

MSISDN	failureCode
2348134567089	RECIPIENT_NOT_FOUND
2348134567099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
2348134567119	OTHER_ERROR
2348134567129	NO CALLBACK (stuck in SUBMITTED state)
2348134567899	N/A (COMPLETED)

Rwanda - Airtel (AIRTEL_RWA)

Deposits

MSISDN	failureCode
250733456039	PAYMENT_NOT_APPROVED
250733456049	INSUFFICIENT_BALANCE
250733456069	OTHER_ERROR
250733456129	NO CALLBACK (stuck in SUBMITTED state)
250733456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
250733456089	RECIPIENT_NOT_FOUND
250733456119	OTHER_ERROR
250733456129	NO CALLBACK (stuck in SUBMITTED state)
250733456789	N/A (COMPLETED)

Rwanda - MTN (MTN_MOMO_RWA)

Deposits

MSISDN	failureCode
250783456019	PAYER_LIMIT_REACHED
250783456029	PAYER_NOT_FOUND
250783456039	PAYMENT_NOT_APPROVED
250783456069	OTHER_ERROR
250783456129	NO CALLBACK (stuck in SUBMITTED state)
250783456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
250783456089	RECIPIENT_NOT_FOUND
250783456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
250783456119	OTHER_ERROR
250783456129	NO CALLBACK (stuck in SUBMITTED state)
250783456789	N/A (COMPLETED)

Senegal - Free (FREE_SEN)

Deposits

MSISDN	failureCode
221763456049	INSUFFICIENT_BALANCE
221763456069	OTHER_ERROR
221763456129	NO CALLBACK (stuck in SUBMITTED state)
221763456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
221763456119	OTHER_ERROR
221763456129	NO CALLBACK (stuck in SUBMITTED state)
221763456789	N/A (COMPLETED)

Senegal - Orange (ORANGE_SEN)

Deposits

MSISDN	failureCode
221773456029	PAYER_NOT_FOUND
221773456049	INSUFFICIENT_BALANCE
221773456069	OTHER_ERROR
221773456129	NO CALLBACK (stuck in SUBMITTED state)
221773456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
221773456119	OTHER_ERROR
221773456139	NO CALLBACK (stuck in SUBMITTED state)
221773456789	N/A (COMPLETED)

Sierra Leone - Orange (ORANGE_SLE)

Deposits

MSISDN	failureCode
23276123456	N/A (COMPLETED)

Payouts

MSISDN	failureCode
23276123456	N/A (COMPLETED)

Tanzania - Airtel (AIRTEL_TZA)

Deposits

MSISDN	failureCode
255683456019	PAYER_LIMIT_REACHED
255683456039	PAYMENT_NOT_APPROVED
255683456049	INSUFFICIENT_BALANCE
255683456069	OTHER_ERROR
255683456129	NO CALLBACK (stuck in SUBMITTED state)
255683456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
255683456089	RECIPIENT_NOT_FOUND
255683456119	OTHER_ERROR
255683456129	NO CALLBACK (stuck in SUBMITTED state)
255683456789	N/A (COMPLETED)

Tanzania - Vodacom (VODACOM_TZA)

Deposits

MSISDN	failureCode
255763456039	PAYMENT_NOT_APPROVED
255763456069	OTHER_ERROR
255763456129	NO CALLBACK (stuck in SUBMITTED state)
255763456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
255763456119	OTHER_ERROR
255763456129	NO CALLBACK (stuck in SUBMITTED state)
255763456789	N/A (COMPLETED)

Tanzania - Tigo (TIGO_TZA)

Deposits

MSISDN	failureCode
255713456039	PAYMENT_NOT_APPROVED
255713456049	INSUFFICIENT_BALANCE
255713456069	OTHER_ERROR
255713456129	NO CALLBACK (stuck in SUBMITTED state)
255713456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
255713456089	RECIPIENT_NOT_FOUND
255713456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
255713456119	OTHER_ERROR
255713456129	NO CALLBACK (stuck in SUBMITTED state)
255713456789	N/A (COMPLETED)

Tanzania - Halotel (HALOTEL_TZA)

Deposits

MSISDN	failureCode
255623456029	PAYER_NOT_FOUND
255623456049	INSUFFICIENT_BALANCE
255623456069	OTHER_ERROR
255623456129	NO CALLBACK (stuck in SUBMITTED state)
255623456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
255623456089	RECIPIENT_NOT_FOUND
255623456119	OTHER_ERROR
255623456129	NO CALLBACK (stuck in SUBMITTED state)
255623456789	N/A (COMPLETED)

Uganda - Airtel (AIRTEL_OAPI_UGA)

Deposits

MSISDN	failureCode
256753456019	PAYER_LIMIT_REACHED
256753456039	PAYMENT_NOT_APPROVED
256753456049	INSUFFICIENT_BALANCE
256753456069	OTHER_ERROR
256753456129	NO CALLBACK (stuck in SUBMITTED state)
256753456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
256753456089	RECIPIENT_NOT_FOUND
256753456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
256753456119	OTHER_ERROR
256753456129	NO CALLBACK (stuck in SUBMITTED state)
256753456789	N/A (COMPLETED)

Uganda - MTN (MTN_MOMO_UGA)

Deposits

MSISDN	failureCode
256783456019	PAYER_LIMIT_REACHED
256783456029	PAYER_NOT_FOUND
256783456069	OTHER_ERROR
256783456129	NO CALLBACK (stuck in SUBMITTED state)
256783456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
256783456089	RECIPIENT_NOT_FOUND
256783456099	RECIPIENT_NOT_ALLOWED_TO_RECEIVE
256783456119	OTHER_ERROR
256783456789	N/A (COMPLETED)

Zambia - Airtel (AIRTEL_OAPI_ZMB)

Deposits

MSISDN	failureCode
260973456019	PAYER_LIMIT_REACHED
260973456039	PAYMENT_NOT_APPROVED
260973456049	INSUFFICIENT_BALANCE
260973456069	OTHER_ERROR
260973456129	NO CALLBACK (stuck in SUBMITTED state)
260973456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
260973456089	RECIPIENT_NOT_FOUND
260973456119	OTHER_ERROR
260973456129	NO CALLBACK (stuck in SUBMITTED state)
260973456789	N/A (COMPLETED)

Zambia - MTN (MTN_MOMO_ZMB)

Deposits

MSISDN	failureCode
260763456019	PAYER_LIMIT_REACHED
260763456029	PAYER_NOT_FOUND
260763456039	PAYMENT_NOT_APPROVED
260763456069	OTHER_ERROR
260763456129	NO CALLBACK (stuck in SUBMITTED state)
260763456789	N/A (COMPLETED)

Payouts

MSISDN	failureCode
260763456079	RECIPIENT_NOT_FOUND
260763456119	OTHER_ERROR
260763456129	NO CALLBACK (stuck in SUBMITTED state)
260763456789	N/A (COMPLETED)

Zambia - Zamtel (ZAMTEL_ZMB)

Deposits

MSISDN	failureCode
260953456704	INSUFFICIENT_BALANCE
260953456712	OTHER_ERROR
260953456789	NO CALLBACK (stuck in SUBMITTED state)
260953456700	N/A (COMPLETED)

Payouts

MSISDN	failureCode
260953456712	OTHER_ERROR
260953456789	NO CALLBACK (stuck in SUBMITTED state)
260953456700	N/A (COMPLETED)

Technical failures should not happen during live operation and are intended to provide clear information during the development of the integration.

Failure Code	Operation	Description
INVALID_RECIPIENT_FORMAT	Payouts	The financial address for the recipient is in an unrecognizable format. Please refer to recipient in Mobile Money Payout Request
INVALID_PAYER_FORMAT	Deposits	The financial address for the payer is in an unrecognizable format. Please refer to payer in Mobile Money Deposit Request.
INVALID_CURRENCY	Both	The currency is not supported by the MNO specified as the correspondent.
INVALID_AMOUNT	Both	The amount is in an unrecognizable format. Please refer to amount in Mobile Money Deposit Request.
INVALID_COUNTRY	Both	The country is not supported by the MNO specified as the correspondent.
AMOUNT_TOO_SMALL	Both	The specified amount is smaller than the minimum allowed by the MNO specified as the correspondent.
AMOUNT_TOO_LARGE	Both	The specified amount is larger than the maximum allowed by the MNO specified as the correspondent.
PARAMETER_INVALID	Both	An invalid parameter was found as part of the request.
DEPOSITS_NOT_ALLOWED	Deposits	The MNO specified as the correspondent does not support deposit transactions.
PAYOUTS_NOT_ALLOWED	Payouts	The MNO specified as the correspondent does not support payout transactions.
AUTHENTICATION_ERROR	Both	The token specified for authentication is not valid or missing. Please refer to Authentication.
INVALID_INPUT	Both	We were was unable to parse the payload of the request.

Transaction failures are expected to happen during live operation and are intended to provide clear information as to why a particular payment was not successful.

Failure Code	Operation	Description
PAYER_LIMIT_REACHED	Deposits	The customer has reached a limit on their wallet. Example: Customer is only allowed to transfer a maximum of 1 000 000 a week.
PAYER_NOT_FOUND	Deposits	The phone number (MSISDN) specified as the payer does not belong to the MNO specified as the correspondent.
PAYMENT_NOT_APPROVED	Deposits	The customer did not authorize the payment. Example: Customer did not enter their PIN in time.
INSUFFICIENT_BALANCE	Deposits	The customer does not have enough funds to perform the deposit.
TRANSACTION_ALREADY_IN_PROCESS	Deposits	The customer is initiating a transaction while an unfinished transaction is still pending. Note: Some MNOs only allow a single transaction to be processed at any given time. When the customer does not enter the PIN to authorize a payment in time, it might take up to 10 minutes for them to be able to initiate a new transaction.
BALANCE_INSUFFICIENT	Payouts	The balance of your pawaPay wallet does not have the funds to initiate this payout.
RECIPIENT_NOT_FOUND	Payouts	The phone number (MSISDN) specified as the recipient, does not belong to the mobiler network operator (MNO) specified as the correspondent.
RECIPIENT_NOT_ALLOWED_TO_RECEIVE	Payouts	The recipient has reached a limit on their wallet that stops them from being able to accept this payout. Example: The customers wallet is able to hold up to 1 000 000 and the payout would take their balance over this limit.
MANUALLY_CANCELLED	Payouts	The payout request was enqueued and subsequently failed manually from your pawaPay portal or through the Cancel Enqueued Payout endpoint.
OTHER_ERROR	Both	The payment failed due to an unknown error.
CORRESPONDENT_TEMPORARILY_UNAVAILABLE	Both	The MNO specified as the correspondent is currently experiencing an outage and processing of payments has been temporarily halted. Please refer to our Status Page for live information about MNO availability.

When you are ready to move from the sandbox environment to production, make sure you are using the correct base URL and the correct authentication token. These are the only parameters that should be different between sandbox and production.

We recommend keeping those parameters in your environemnt specific configuration.

If you use IP whitelisting, make sure our IP-s are whitelisted to ensure we can deliver you callbacks.

We recommend implementing a feature flag for your integration with pawaPay to enable go-live testing in production, before market launch. This allows you to test the end-to-end flow in production to uncover any environemnt specific problems without affecting customers.

To test live payments you will need for each MNO that you use:

• A phone and phone number with the specific MNO.
• An active mobile money wallet on that phone number.
• An available balance on the mobile money wallet to conduct the tests with.
• Be ready to enter the PIN code on the phone around 20-60 seconds from initiating the payment through our API.

You can disburse money from your pawaPay account to a customers mobile money wallet.

This operation does not involve the recipient having to authorise the transaction by entering their PIN code. The operation is usually processed within seconds.

After we receive a payout request, we send it to the MNO specified as the correspondent. When the MNO finalizes your payout request, it will inform pawaPay and consequently pawaPay notifies you of the result by calling your defined callback URL with a Payout Status Callback (if configured). If you have not configured callbacks, you can always check the status of your payout request through our Get Payout Status and Details endpoint.

Please follow the guidelines in the Implementation section of our API docs to ensure a reliable implementation.

After your payout request has been accepted for processing, it can have one of the following statuses in the pawaPay platform:

Status	Description
ACCEPTED	The payout request has been accepted by pawaPay for processing.
ENQUEUED	The payout request has been accepted, but has been enqueued for processing later.
SUBMITTED	The payout request has been submitted to the MNO and is being processed.
COMPLETED	The payout request has been successful. This is a final state.
FAILED	The payout request has failed. This is a final state.

Sometimes MNOs have either degraded performance or their systems are unavailable completely. Read more about MNO stability.

Our Payment Operations team monitors the MNOs availability 24/7 and publishes that information on our status page. This information is also accessible programmatically from our availability endpoint. When an MNO is not able to process payouts, our platform will still accepts payout requests for processing. Your payout request will return 'ENQUEUED' as the status. The payout will be enqueued until the MNOs systems become operational.

You can always cancel the enqueued payout before it's processed using the Cancel enqueued payout endpoint. It's also possible to cancel it from our portal as described in our portal documentation.

You can request payment from a customer. Funds will be moved from the customers mobile money wallet to your account in pawaPay.

This operation needs to be explicitly authorised by the customer by entering their PIN code. The operation can take between a few seconds up to a few minutes to be processed successfully.

After the deposit request is sent to pawaPay, we forward the request to the Mobile Network Operator (MNO) specified as the correspondent. The MNO sends the request to the customer for authorization. The customer then authorizes the payment by entering their PIN code on their mobile phone. Upon customers authorization (or rejection), the MNO informs pawaPay of the result and consequently pawaPay notifies you of the result by calling your defined callback URL with a Deposit Status Callback (if configured). If you have not configured callbacks, you can always check the status of your deposit request through our Deposit Get Status and Details endpoint.

Please follow the guidelines in the Implementation section of our API docs to ensure a reliable implementation.

After your deposit request has been accepted for processing, it can have one of the following statuses in the pawaPay platform:

Status	Description
ACCEPTED	The deposit request has been accepted by pawaPay for processing.
SUBMITTED	The deposit request has been submitted to the MNO and is being processed.
COMPLETED	The deposit request has been successful. This is a final state.
FAILED	The deposit request has failed. This is a final state.

You can refund an already completed collection (deposit) from your pawaPay account back to the customers mobile money wallet.

This operation does not involve the recipient having to authorise the transaction. The operation is usually processed within seconds.

After we have received a refund request, we send it to the MNO specified as the correspondent. When the MNO finalizes your refund request, it will inform pawaPay and consequently pawaPay notifies you of the result by calling your defined callback URL with a Refund Status Callback (if configured). If you have not configured callbacks, you can always check the status of your refund request through our Get Refund Status and Details endpoint.

Please follow the guidelines in the Implementation section of our API docs to ensure a reliable implementation.

After your refund request has been accepted for processing, it can have one of the following statuses in the pawaPay platform:

Status	Description
ACCEPTED	The refund request has been accepted by pawaPay for processing.
SUBMITTED	The refund request has been submitted to the MNO and is being processed.
COMPLETED	The refund request has been successful. This is a final state.
FAILED	The refund request has failed. This is a final state.

The pawaPay Payment Page allows you to rapidly integrate mobile money into your website or mobile app providing:

• User experience for your customers that is optimised for mobile money.
• Responsive design that works on desktop and mobile.
• Low code integration supporting all countries and MNOs.
• Support for both e-commerce and e-wallet use cases.

Enter details

Authorise the payment

All done

It is also integrated to the rest of the pawaPay merchant API, providing benefits like:

• Phone numbers are valildated to be in the correct format.
• The MNO to use for the payment is predicted based on the entered phone number.
• Minimum and maxium transaction limits are always up to date.
• When new countries or MNOs are enabled, they are available for your customers immediately.
• Information about MNOs having downtime is integrated into the user experience.
• With many more improvements to come...

Using the payment flow in your deposit or checkout experience is simple:

1. When it's time for the customer to pay, start a new session. The session will time out after 15 minutes.
2. Forward the customer to the redirectUrl that you received in the response.
3. The customer will complete the payment on the Payment Page and forwarded to returnUrl.
4. Your page on returnUrl should verify the status of the payment. The depositId will be passed as a URL parameter.
5. Based on the status of the payment handle a successful, failed or long running payment.