pawaPay Merchant API for Mobile Money (v1)

Download OpenAPI specification:Download

You can get help from our Discord server.

pawaPay Merchant API allows you to collect and disburse mobile money across Africa. Using our Merchant API, with just a single integration you'll have access to millions of mobile money wallets.

Introduction

About mobile money

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.

What does a payment look like

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

Implementation

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.

MNO stability

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.

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

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

Deposit with pawaPay Merchant API

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

Safe handling

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.

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

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

Using the API

Where is the API?

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.

Authentication

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

Callback URLs

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

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

Testing the API

Overview

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.

Test phone numbers (MSISDNs)

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 failure codes

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 failure codes

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.

Moving to production

Overview

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.

Go-live testing

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.

Payout (Disbursement)

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.

Enqueued payouts

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.

Payout with pawaPay Merchant API

Deposit (Collection)

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.
Deposit with pawaPay Merchant API

Refund

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.

Payment Page

Overview

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

Payment page - Start

Authorise the payment

Payment page - Enter PIN

All done

Payment page - Success

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...
Payment page - Features

Implementation

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.
Payment page - Implementation flow

Payouts

Mobile Money Payout Request

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

Payouts operation allows you to initiate a disbursement for asynchronous processing. Read more about Payouts.

  • This API call is idempotent, which means it is safe to submit a request with the same payoutId multiple times.
  • Duplicate requests with the same payoutId will be ignored with the DUPLICATE_IGNORED status in the PayoutCreationResponse.
  • Since the request can be rejected, you must check the status code in the PayoutCreationResponse for each submitted request. The rejectionReason in the PayoutCreationResponse will contain information about the reason of the rejection.

Each request can become either ACCEPTED, ENQUEUED, REJECTED or DUPLICATE_IGNORED:

Status Callback Description
ACCEPTED Yes The payout request has been accepted by pawaPay for processing.
ENQUEUED Yes The payout request has been accepted, but has been enqueued for processing later. Read more about enqueued payouts.
REJECTED No The payout request has been rejected. See rejectionReason for details.
DUPLICATE_IGNORED No The payout request has been ignored as a duplicate of an already accepted payout request. Duplication logic relies upon payoutId.

What next?

As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the accepted payout by either:

  1. Configuring callback URLs and waiting for payoutCallback from pawaPay with the final status.
  2. Periodically polling the Get Payout Status and Details endpoint for a final status.
SecuritybearerAuth
Request
Request Body schema: application/json
required
payoutId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the payout.

amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the payout process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
required
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

Responses
200

Request has been accepted for processing by pawaPay

Response Schema: application/json
payoutId
required
string <uuid> = 36 characters

The payoutId of the payout transaction.

status
required
string (PayoutCreationStatus)

Enumeration presenting the status of the Payout Creation:

  • 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. Read more about enqueued payouts.
  • REJECTED - The payout request has been rejected by pawaPay. See rejectionReason for details.
  • DUPLICATE_IGNORED - The payout request has been ignored as a duplicate of already accepted payout request. Duplication logic relies upon payoutId.
Enum: "ACCEPTED" "ENQUEUED" "REJECTED" "DUPLICATE_IGNORED"
created
string <date-time>

The timestamp of when the payout was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object (PayoutRejectionReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/payouts
Request samples
application/json
{
  • "payoutId": "<INSERT_UUID_FOR_PAYOUT>",
  • "amount": "15",
  • "currency": "ZMW",
  • "correspondent": "MTN_MOMO_ZMB",
  • "recipient": {
    • "type": "MSISDN",
    • "address": {
      • "value": "260763456789"
      }
    },
  • "customerTimestamp": "2020-02-21T17:32:28Z",
  • "statementDescription": "Note of 4 to 22 chars"
}
Response samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "created": "2020-10-19T11:17:01Z"
}

Mobile Money Bulk Payout Request

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

Bulk payouts operation allows you to initiate multiple disbursements for asynchronous processing. Read more about Payouts.

  • Bulk requests with more than 20 payout transactions can be rejected by pawaPay.
  • This API call is idempotent, which means it is safe to submit a request with the same payoutId multiple times.
  • Duplicate requests with the same payoutId will be ignored with the DUPLICATE_IGNORED status in the PayoutCreationResponse.
  • Since the request can be partially or fully rejected, you must check the status code in the PayoutCreationResponse for each submitted request. The rejectionReason in the PayoutCreationResponse will contain information about the reason of the rejection.
  • Callback will be delivered separetly for each payout in the bulk request as the payouts are resolved to their final status.

Each disbursement in a bulk request can become either ACCEPTED, ENQUEUED, REJECTED or DUPLICATE_IGNORED:

Status Callback Description
ACCEPTED Yes The payout request has been accepted by pawaPay for processing.
ENQUEUED Yes The payout request has been accepted, but has been enqueued for processing later. Read more about enqueued payouts.
REJECTED No The payout request has been rejected. See rejectionReason for details.
DUPLICATE_IGNORED No The payout request has been ignored as a duplicate of an already accepted payout request. Duplication logic relies upon payoutId.

What next?

As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the accepted payout by either:

  1. Configuring callback URLs and waiting for payoutCallback from pawaPay with the final status.
  2. Periodically polling the Get Payout Status and Details endpoint for a final status.
SecuritybearerAuth
Request
Request Body schema: application/json
required
Array
payoutId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the payout.

amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the payout process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
required
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
Array
payoutId
required
string <uuid> = 36 characters

The payoutId of the payout transaction.

status
required
string (PayoutCreationStatus)

Enumeration presenting the status of the Payout Creation:

  • 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. Read more about enqueued payouts.
  • REJECTED - The payout request has been rejected by pawaPay. See rejectionReason for details.
  • DUPLICATE_IGNORED - The payout request has been ignored as a duplicate of already accepted payout request. Duplication logic relies upon payoutId.
Enum: "ACCEPTED" "ENQUEUED" "REJECTED" "DUPLICATE_IGNORED"
created
string <date-time>

The timestamp of when the payout was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object (PayoutRejectionReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/payouts/bulk
Request samples
application/json
[
  • {
    • "payoutId": "<INSERT_UUID_FOR_PAYOUT>",
    • "amount": "15",
    • "currency": "ZMW",
    • "correspondent": "MTN_MOMO_ZMB",
    • "recipient": {
      • "type": "MSISDN",
      • "address": {
        • "value": "260763456789"
        }
      },
    • "customerTimestamp": "2020-02-21T17:32:28Z",
    • "statementDescription": "Note of 4 to 22 chars"
    }
]
Response samples
application/json
[
  • {
    • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
    • "status": "ACCEPTED",
    • "created": "2020-10-19T11:17:01Z"
    },
  • {
    • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
    • "status": "DUPLICATE_IGNORED",
    • "created": "2020-10-19T10:22:49Z"
    },
  • {
    • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
    • "status": "REJECTED",
    • "rejectionReason": {
      • "rejectionCode": "AMOUNT_TOO_LARGE",
      • "ejectionMessage": "Amount should not be greater than 1000"
      }
    }
]

Get Payout Status and Details

Get payout status and details by the payoutId from your initial payout request. A list with at most one Payout is returned.

This operation can be used to verify the status of a payout.

SecuritybearerAuth
Request
path Parameters
payoutId
required
string <uuid> = 36 characters

payoutId which has been specified in PayoutCreationRequest.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
Array
payoutId
required
string <uuid> = 36 characters

A payout identifier which has been specified in PayoutCreationRequest.

status
required
string (PayoutStatus)

Enumeration presenting the status of the payout:

  • 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. Read more about enqueued payouts.
  • SUBMITTED - The payout request has been submitted to the MNO and is being processed.
  • COMPLETED - The payout request has been successfully processed. This is a Final state.
  • FAILED - The payout request has been processed, but failed. Final state.
Enum: "ACCEPTED" "SUBMITTED" "ENQUEUED" "COMPLETED" "FAILED"
amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the payout process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the payout was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

receivedByRecipient
string <date-time>

When the payment was received by the recipient. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

object

The unqiue ID for this financial transaction assigned by the MNO.

object (PayoutFailureReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

get/payouts/{payoutId}
Request samples
Response samples
application/json
[
  • {
    • "payoutId": "8917c345-4791-4285-a416-62f24b6982db",
    • "status": "COMPLETED",
    • "amount": "123.45",
    • "currency": "ZMW",
    • "country": "ZMB",
    • "correspondent": "MTN_MOMO_ZMB",
    • "recipient": {
      • "type": "MSISDN",
      • "address": {
        • "value": "260763456789"
        }
      },
    • "customerTimestamp": "2020-10-19T08:17:00Z",
    • "statementDescription": "From ACME company",
    • "created": "2020-10-19T08:17:01Z",
    • "receivedByRecipient": "2020-10-19T08:17:02Z",
    • "correspondentIds": {
      • "SOME_CORRESPONDENT_ID": "12356789"
      }
    }
]

Resend callback

Resends the callback for a payout to your configured callback URL. The payout must have reached a final state. The callback delivery has to have failed already.

Please ensure your implementation of callback handling follows the guidelines in Handling callbacks.

SecuritybearerAuth
Request
Request Body schema: application/json
payoutId
required
string <uuid> = 36 characters

A UUIDv4 based ID previously specified by you, that uniquely identifies the payout.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
payoutId
required
string <uuid> = 36 characters

The payoutId of the payout transaction.

status
required
string (ManualCommandStatus)

Enumeration presenting the status of the manual command action:

  • ACCEPTED - The manual action request has been accepted by pawaPay for processing.
  • REJECTED - The manual action request has been rejected by pawaPay. See rejectionReason for details.
  • FAILED - The manual action request has failed during submitting for processing due to internal reasons.
Enum: "ACCEPTED" "REJECTED" "FAILED"
rejectionReason
string

Human-readable explanation why request has been rejected

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/payouts/resend-callback
Request samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639"
}
Response samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED"
}

Cancel Enqueued Payout

Cancels a payout that is currently in the ENQUEUED status. The payment will be moved to FAILED status. The payment will have the failure code MANUALLY_CANCELLED. If you have configured callbacks, a callback will be sent.

SecuritybearerAuth
Request
path Parameters
payoutId
required
string <uuid> = 36 characters

payoutId which has been specified in PayoutCreationRequest.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
payoutId
required
string <uuid> = 36 characters

The payoutId of the payout transaction.

status
required
string (ManualCommandStatus)

Enumeration presenting the status of the manual command action:

  • ACCEPTED - The manual action request has been accepted by pawaPay for processing.
  • REJECTED - The manual action request has been rejected by pawaPay. See rejectionReason for details.
  • FAILED - The manual action request has failed during submitting for processing due to internal reasons.
Enum: "ACCEPTED" "REJECTED" "FAILED"
rejectionReason
string

Human-readable explanation why request has been rejected

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/payouts/fail-enqueued/{payoutId}
Request samples
Response samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED"
}

Payout Status CallbackWebhook

If you have configured callbacks, pawaPay will POST a callback to your configured callback URL for each payout when it reaches a final status. Read more about handling callbacks and callback URLs.

If you have not configured callbacks, you can always call our Get Payout Status and Details endpoint to get the latest status and details of a specific payout request.

Request
Request Body schema: application/json
required
payoutId
required
string <uuid> = 36 characters

A payout identifier which has been specified in PayoutCreationRequest.

status
required
string (PayoutStatus)

Enumeration presenting the status of the payout:

  • 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. Read more about enqueued payouts.
  • SUBMITTED - The payout request has been submitted to the MNO and is being processed.
  • COMPLETED - The payout request has been successfully processed. This is a Final state.
  • FAILED - The payout request has been processed, but failed. Final state.
Enum: "ACCEPTED" "SUBMITTED" "ENQUEUED" "COMPLETED" "FAILED"
amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the payout process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the payout was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

receivedByRecipient
string <date-time>

When the payment was received by the recipient. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6).

object

The unqiue ID for this financial transaction assigned by the MNO.

object (PayoutFailureReason)
Responses
200

OK

Request samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "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",
  • "created": "2020-02-21T17:32:29Z",
  • "receivedByRecipient": "2020-02-21T17:32:30Z",
  • "correspondentIds": {
    • "MTN_INIT": "ABC123",
    • "MTN_FINAL": "DEF456"
    },
  • "failureReason": {
    • "failureCode": "OTHER_ERROR",
    • "failureMessage": "Recipient's address is blocked"
    }
}

Deposits

Mobile Money Deposit Request

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

Deposits operation allows you to initiate a collection for asynchronous processing. Read more about Deposits.

  • This API call is idempotent, which means it is safe to submit a request with the same depositId multiple times.
  • Duplicate requests with the same depositId will be ignored with the DUPLICATE_IGNORED status in the DepositCreationResponse.
  • Since the request can rejected, you must check status code in the DepositCreationResponse for each submitted request. The rejectionReason in the DepositCreationResponse will contain information about the reason of the rejection.

Each request can become either ACCEPTED, REJECTED or DUPLICATE_IGNORED:

Status Callback Description
ACCEPTED Yes The deposit request has been accepted by pawaPay for processing.
REJECTED No The deposit request has been rejected. See rejectionReason for details.
DUPLICATE_IGNORED No The deposit request has been ignored as a duplicate of an already accepted deposit request. Duplication logic relies upon depositId.

What next?

As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the accepted deposit by either:

  1. Configuring callback URLs and waiting for depositCallback from pawaPay with the final status.
  2. Periodically polling the Get Deposit Status and Details endpoint for a final status.
SecuritybearerAuth
Request
Request Body schema: application/json
required
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the deposit.

amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp of when the deposit was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
required
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer on the PIN prompt, in the SMS receipt or within their transaction history.

preAuthorisationCode
string [ 1 .. 36 ] characters ^[a-zA-Z0-9]+$

For MNOs (correspondents) that use a preauthorisation code instead of a PIN prompt for authorising the deposit.

Responses
200

Request has been accepted for processing by pawaPay

Response Schema: application/json
depositId
required
string <uuid> = 36 characters

The depositId of the deposit transaction.

status
required
string (DepositCreationStatus)

Enumeration presenting the status of the Deposit:

  • ACCEPTED - The deposit request has been accepted by pawaPay for processing.
  • REJECTED - The deposit request has been rejected. See rejectionReason for details
  • DUPLICATE_IGNORED - This deposit request is a duplicate and will be ignored.
Enum: "ACCEPTED" "REJECTED" "DUPLICATE_IGNORED"
created
string <date-time>

The timestamp of when the deposit was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object (DepositRejectionReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/deposits
Request samples
application/json
{
  • "depositId": "<INSERT_UUID_FOR_DEPOSIT>",
  • "amount": "15",
  • "currency": "ZMW",
  • "correspondent": "MTN_MOMO_ZMB",
  • "payer": {
    • "type": "MSISDN",
    • "address": {
      • "value": "260763456789"
      }
    },
  • "customerTimestamp": "2020-02-21T17:32:28Z",
  • "statementDescription": "Note of 4 to 22 chars"
}
Response samples
application/json
{
  • "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "created": "2020-10-19T11:17:01Z"
}

Get Deposit Status and Details

Get deposit transaction status and details by depositId from your initial deposit request. A list with at most one Deposit is returned.

This operation can be used to verify the status of a deposit.

SecuritybearerAuth
Request
path Parameters
depositId
required
string <uuid> = 36 characters

The depositId of the deposit transaction.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
Array
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the deposit.

status
required
string (DepositStatus)

Enumeration presenting the status of the deposit:

  • 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 successfully processed. This is a final state.
  • FAILED - The deposit request has been proceessed, but failed. This is a final state.
Enum: "ACCEPTED" "SUBMITTED" "COMPLETED" "FAILED"
requestedAmount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the deposit process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the deposit was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

depositedAmount
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

respondedByPayer
string <date-time>

When the MNO responded to this deposit request. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object

The unqiue ID for this financial transaction assigned by the MNO.

Array of objects (SuspiciousDepositTransactionReport)
object (DepositFailureReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

get/deposits/{depositId}
Request samples
Response samples
application/json
[
  • {
    • "depositId": "8917c345-4791-4285-a416-62f24b6982db",
    • "status": "COMPLETED",
    • "requestedAmount": "123.00",
    • "depositedAmount": "123.00",
    • "currency": "ZMW",
    • "country": "ZMB",
    • "payer": {
      • "type": "MSISDN",
      • "address": {
        • "value": "260763456789"
        }
      },
    • "correspondent": "MTN_MOMO_ZMB",
    • "statementDescription": "To ACME company",
    • "customerTimestamp": "2020-10-19T08:17:00Z",
    • "created": "2020-10-19T08:17:01Z",
    • "respondedByPayer": "2020-10-19T08:17:02Z",
    • "correspondentIds": {
      • "SOME_CORRESPONDENT_ID": "12356789"
      }
    }
]

Resend callback

Resends the callback for a deposit to your configured callback URL. The deposit must have reached a final state. The callback delivery has to have failed already.

Please ensure your implementation of callback handling follows our guidelines in Handling callbacks.

SecuritybearerAuth
Request
Request Body schema: application/json
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID previously specified by you, that uniquely identifies the deposit.

Responses
200

Request has been accepted for processing by pawaPay

Response Schema: application/json
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the deposit.

status
required
string (ManualCommandStatus)

Enumeration presenting the status of the manual command action:

  • ACCEPTED - The manual action request has been accepted by pawaPay for processing.
  • REJECTED - The manual action request has been rejected by pawaPay. See rejectionReason for details.
  • FAILED - The manual action request has failed during submitting for processing due to internal reasons.
Enum: "ACCEPTED" "REJECTED" "FAILED"
rejectionReason
string

Human-readable explanation why request has been rejected

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/deposits/resend-callback
Request samples
application/json
{
  • "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639"
}
Response samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED"
}

Deposit Status CallbackWebhook

If you have configured callbacks, pawaPay will POST a callback to your configured callback URL for each deposit when it reaches a final status. Read more about handling callbacks and callback URLs.

If you have not configured callbacks, you can always call our Get Deposit Status and Details endpoint to get the latest status and details of a specific deposit request.

Request
Request Body schema: application/json
required
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the deposit.

status
required
string (DepositStatus)

Enumeration presenting the status of the deposit:

  • 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 successfully processed. This is a final state.
  • FAILED - The deposit request has been proceessed, but failed. This is a final state.
Enum: "ACCEPTED" "SUBMITTED" "COMPLETED" "FAILED"
requestedAmount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the deposit process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the deposit was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

depositedAmount
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

respondedByPayer
string <date-time>

When the MNO responded to this deposit request. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object

The unqiue ID for this financial transaction assigned by the MNO.

Array of objects (SuspiciousDepositTransactionReport)
object (DepositFailureReason)
Responses
200

OK

Request samples
application/json
{
  • "depositId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "requestedAmount": "15",
  • "currency": "ZMW",
  • "country": "ZMB",
  • "correspondent": "MTN_MOMO_ZMB",
  • "payer": {
    • "type": "MSISDN",
    • "address": {
      • "value": "260763456789"
      }
    },
  • "customerTimestamp": "2020-02-21T17:32:28Z",
  • "statementDescription": "Note of 4 to 22 chars",
  • "created": "2020-02-21T17:32:29Z",
  • "depositedAmount": "15",
  • "respondedByPayer": "2020-02-21T17:32:30Z",
  • "correspondentIds": {
    • "MTN_INIT": "ABC123",
    • "MTN_FINAL": "DEF456"
    },
  • "suspiciousActivityReport": [
    • {
      • "activityType": "AMOUNT_DISCREPANCY",
      • "comment": "There is a discrepancy between requested and actual deposit amount."
      }
    ],
  • "failureReason": {
    • "failureCode": "OTHER_ERROR",
    • "failureMessage": "Payers address is blocked"
    }
}

Refunds

Mobile Money Refund Request

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

Refunds operation allows you to initiate a refund for asynchronous processing. Read more about Refunds.

  • This API call is idempotent, which means it is safe to submit a request with the same refundId multiple times.
  • Duplicate requests with the same refundId will be ignored with the DUPLICATE_IGNORED status in the RefundCreationResponse.
  • Since the request can be rejected, you must check the status code in the RefundCreationResponse for each submitted request. The rejectionReason in the RefundCreationResponse will contain information about the reason of the rejection.

Each request can become either ACCEPTED, REJECTED or DUPLICATE_IGNORED:

Status Callback Description
ACCEPTED Yes The refund request has been accepted by pawaPay for processing.
REJECTED No The refund request has been rejected. See rejectionReason for details.
DUPLICATE_IGNORED No The refund request has been ignored as a duplicate of an already accepted refund request. Duplication logic relies upon refundId.

What next?

As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the accepted refund by either:

  1. Configuring callback URLs and waiting for refundCallback from pawaPay with the final status.
  2. Periodically polling the Get Refund Status and Details endpoint for a final status.
SecuritybearerAuth
Request
Request Body schema: application/json
required
refundId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the refund.

depositId
required
string <uuid> = 36 characters

The depositId of the deposit to be refunded.

amount
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

Responses
200

Request has been accepted for processing by pawaPay

Response Schema: application/json
refundId
required
string <uuid> = 36 characters

The refundId of the refund transaction.

status
required
string (RefundCreationStatus)

Enumeration presenting the status of the Refund Creation:

  • ACCEPTED - The refund request has been accepted by pawaPay for processing.
  • REJECTED - The refund request has been rejected by pawaPay. See rejectionReason for details.
  • DUPLICATE_IGNORED - The refund request has been ignored as a duplicate of already accepted refund request. Duplication logic relies upon refundId.
Enum: "ACCEPTED" "REJECTED" "DUPLICATE_IGNORED"
created
string <date-time>

The timestamp of when the refund was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object (RefundRejectionReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

500

Internal Server Error

post/refunds
Request samples
application/json
{
  • "refundId": "<INSERT_UUID_FOR_REFUND>",
  • "depositId": "<INSERT_UUID_OF_DEPOSIT_TO_REFUND>"
}
Response samples
application/json
{
  • "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "created": "2020-10-19T11:17:01Z"
}

Get Refund Status and Details

Get refund transaction status and details by the refundId from your initial refund request. A list with at most one Refund is returned.

This operation can be used to verify the status of a refund.

SecuritybearerAuth
Request
path Parameters
refundId
required
string <uuid> = 36 characters

refundId which has been specified in RefundCreationRequest.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
Array
refundId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that unqiuely identifies the refund.

status
required
string (PayoutStatus)

Enumeration presenting the status of the payout:

  • 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. Read more about enqueued payouts.
  • SUBMITTED - The payout request has been submitted to the MNO and is being processed.
  • COMPLETED - The payout request has been successfully processed. This is a Final state.
  • FAILED - The payout request has been processed, but failed. Final state.
Enum: "ACCEPTED" "SUBMITTED" "ENQUEUED" "COMPLETED" "FAILED"
amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the refund process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the refund was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

receivedByRecipient
string <date-time>

When the payment was received by the recipient. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object

The financial ids used by the MNO to unqiuely identify this payment

object (RefundFailureReason)
400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

500

Internal Server Error

get/refunds/{refundId}
Request samples
Response samples
application/json
[
  • {
    • "refundId": "8917c345-4791-4285-a416-62f24b6982db",
    • "status": "COMPLETED",
    • "amount": "123.45",
    • "currency": "ZMW",
    • "country": "ZMB",
    • "correspondent": "MTN_MOMO_ZMB",
    • "recipient": {
      • "type": "MSISDN",
      • "address": {
        • "value": "260763456789"
        }
      },
    • "customerTimestamp": "2020-10-19T08:17:00Z",
    • "statementDescription": "From ACME company",
    • "created": "2020-10-19T08:17:01Z",
    • "receivedByRecipient": "2020-10-19T08:17:02Z",
    • "correspondentIds": {
      • "SOME_CORRESPONDENT_ID": "12356789"
      }
    }
]

Resend callback

Resends the callback for a refund to your configured callback URL. The refund must have reached a final state. The callback delivery has to have failed already.

Please ensure your implementation of callback handling follows our guidelines in Handling callbacks.

SecuritybearerAuth
Request
Request Body schema: application/json
refundId
required
string <uuid> = 36 characters

A UUIDv4 based ID previously specified by you, that uniquely identifies the refund.

Responses
200

Request has been processed by pawaPay

Response Schema: application/json
refundId
required
string <uuid> = 36 characters

The refundId of the refund transaction.

status
required
string (ManualCommandStatus)

Enumeration presenting the status of the manual command action:

  • ACCEPTED - The manual action request has been accepted by pawaPay for processing.
  • REJECTED - The manual action request has been rejected by pawaPay. See rejectionReason for details.
  • FAILED - The manual action request has failed during submitting for processing due to internal reasons.
Enum: "ACCEPTED" "REJECTED" "FAILED"
rejectionReason
string

Human-readable explanation why request has been rejected

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/refunds/resend-callback
Request samples
application/json
{
  • "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639"
}
Response samples
application/json
{
  • "payoutId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED"
}

Refund Status CallbackWebhook

If you have configured callbacks, pawaPay will POST a callback to your configured callback URL for each refund when it reaches a final status. Read more about handling callbacks and callback URLs.

If you have not configured callbacks, you can always call our Get Refund Status and Details endpoint to get the latest status and details of a specific refund request.

Request
Request Body schema: application/json
required
refundId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that unqiuely identifies the refund.

status
required
string (PayoutStatus)

Enumeration presenting the status of the payout:

  • 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. Read more about enqueued payouts.
  • SUBMITTED - The payout request has been submitted to the MNO and is being processed.
  • COMPLETED - The payout request has been successfully processed. This is a Final state.
  • FAILED - The payout request has been processed, but failed. Final state.
Enum: "ACCEPTED" "SUBMITTED" "ENQUEUED" "COMPLETED" "FAILED"
amount
required
string (Amount) [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

The amount to be collected or disbursed.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

currency
required
string (Currency)

The currency in which the amount is specified.

Format must be the ISO 4217 three character currency code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_4217#Active_codes.

You can find all the supported currencies that the specific correspondent supports from here.

The active configuration endpoint provides the list of correspondents configured for your account together with the currencies.

country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

required
object (FinancialAddress)

The phone number (MSISDN) of the recipient or payer must be specified as the value of the address

customerTimestamp
required
string <date-time>

The timestamp for when you initiated the refund process. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

created
required
string <date-time>

The timestamp of when the refund was created in the pawaPay platform. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

receivedByRecipient
string <date-time>

When the payment was received by the recipient. Format defined by 'date-time' in RFC3339 section 5.6 (https://tools.ietf.org/html/rfc3339#section-5.6)

object

The financial ids used by the MNO to unqiuely identify this payment

object (RefundFailureReason)
Responses
200

OK

Request samples
application/json
{
  • "refundId": "f4401bd2-1568-4140-bf2d-eb77d2b2b639",
  • "status": "ACCEPTED",
  • "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",
  • "created": "2020-02-21T17:32:29Z",
  • "receivedByRecipient": "2020-02-21T17:32:30Z",
  • "correspondentIds": {
    • "MTN_INIT": "ABC123",
    • "MTN_FINAL": "DEF456"
    },
  • "failureReason": {
    • "failureCode": "OTHER_ERROR",
    • "failureMessage": "Recipient's address is blocked"
    }
}

Payment Page

Deposit via Payment Page

Initiates a payment session using the pawaPay Payment Page. Read more about the Payment Page.

The request will return a redirectURL. The customer should be forwarded to this URL to start the payment process. Once the customer completes the payment process on the Payment Page, they will be fowarded to the returnUrl. The original depositId will be passed as a query parameter.

Your page on the returnUrl has two options to determine the status of the payment. You can use the Get Deposit Status and Details to retrive the deposit associated with this session. Read more about possible statuses of a payment. If you have configured callback URLs you will receive a callback to your configured callback URL when the payment reached its final status.

The customer experience of the Payment Page can be changed through the following parameters during initiation.

Parameter Behaviour if specified Behaviour if not specified
amount The specified amount will be used for the collection. Customer is not able to change it. The customer is able to enter the amount they wish to pay. For example, when depositing into their eWallet.
msisdn The collection will be initiated from the specified mobile money wallet. Customer is not able to change it. The customer can specify the phone number of the mobile money wallet they wish to pay from..
country The customer can pay only using a mobile money wallet from the specified country. The customer can pay with a mobile money wallet from any country that is configured on your pawaPay account. You can use the active configuration endpoint to verify which countries and MNOs have been configured for your account..
reason The reason will be shown to the customer on the Payment Page The customer will not be shown what they are paying for.

What next?

When the customer initiates a deposit from the payment page, the deposit will be avaialble in the system and can be handled the same way as deposits initiated with the Merchant API.
As the pawaPay Merchant API is an asynchronous API, you can find out the final status of the accepted deposit by either:

  1. Configuring callback URLs and waiting for depositCallback from pawaPay with the final status.
  2. Periodically polling the Get Deposit Status and Details endpoint for a final status.
SecuritybearerAuth
Request
Request Body schema: application/json
required
depositId
required
string <uuid> = 36 characters

A UUIDv4 based ID specified by you, that uniquely identifies the deposit.

returnUrl
required
string <uri>

The URL to which the user will be redirected after completion of the operation.

statementDescription
string [ 4 .. 22 ] characters ^[a-zA-Z0-9 ]+$

Short description for the transaction. Depending on the specific MNO performing the transaction this message may be visible to the customer in the SMS receipt or within their transaction history.

amount
string [ 1 .. 23 ] characters ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])...

If specified, the amount will be displayed to the collection as the collection amount. For example, when paying for specific goods or services.

If not specified, the customer will have to specify the amount they wish to pay. For example, when depositing money into their eWallet.

Amount has to follow below requirements or the request will be rejected:

  • Between zero and two decimal places can be supplied, depending on what the specific MNO supports. Learn about all MNO supported decimal places.
  • The maximum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • The minimum amount depends on the limits of the specific MNO. You can find them from the Active Configuration endpoint.
  • Leading zeroes are not permitted except where the value is less than 1. For any value less than one, one and only one leading zero must be supplied.
  • Trailing zeroes are permitted.

Valid examples: 5, 5.0, 5.00, 5.5, 5.55, 5555555, 0.5

Not valid examples: 5., 5.555, 5555555555555555555, .5, -5.5, 00.5, 00.00, 00001.32

msisdn
string

The phone number (MSISDN) of the payer or recipient.

If specified, this phone number will be used to collect the deposit. If not specified, the customer paying can specify the phone number that they want to pay from.

The format is (https://en.wikipedia.org/wiki/MSISDN). MSISDN validation has following rules:

  • Only digits without whitespaces or any other separators or prefixes like '+'.
  • Should not start with zero.
  • Country code is mandatory.
  • Should not exceed or be less than the valid length of specified country.

Valid examples for Ghana: 233558708954

Not valid examples for Ghana: +233558708954, 233 558 708954, 233-558-708954, 0233558708954, 233558708, 233558708954872, 999558708954, 37255870895

country
string

If specifified, allows payment from phone numbers only from a specific country. If not specified, the customer can select any country that is configured for your account in pawaPay.

You can use the active configuration endpoint to verify which counrties and MNOs have been configured for your account.

Format must be the ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

reason
string [ 1 .. 50 ] characters

An optional text which will be displayed to the customer on the payment page to specify what they are paying for.

Responses
200

Payment Page session is created successfully

Response Schema: application/json
redirectUrl
string <uri>

The unique URL of the payment page for this specific payment session. Customer has to be forwarded to this URL where they can complete the payment. The session is valid for 15 minutes for the customer to complete the payment.

Please note! The URL is valid for 5 minutes.

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token.

403

Authorization Failure. Please check your authentication token.

500

Internal Server Error

Wallet balances

Get wallet balances for all wallets

Allows you to get the list of wallets and their balances configured for your account.

SecuritybearerAuth
Responses
200

Request has been succesfully processed.

Response Schema: application/json
required
Array of objects (WalletState)

List of wallet balances

401

Authentication Failure. Please check your authentication token.

403

Authorization Failure. Please check your authentication token.

500

Internal Server Error

get/v1/wallet-balances
Request samples
Response samples
application/json
{
  • "balances": [
    • {
      • "country": "ZMB",
      • "balance": "21798.03",
      • "currency": "ZMW",
      • "mno": ""
      },
    • {
      • "country": "UGA",
      • "balance": "10798.03",
      • "currency": "UGX",
      • "mno": ""
      }
    ]
}

Get wallet balances for a country

Allows you to get the wallet balances for a specific country configured for your account.

You can filter the results by the country of the wallet.

SecuritybearerAuth
Request
path Parameters
country
required
string = 3 characters

The country for which to get wallet balances for.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

Responses
200

Request has been succesfully processed.

Response Schema: application/json
required
Array of objects (WalletState)

List of wallet balances

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token.

403

Authorization Failure. Please check your authentication token.

500

Internal Server Error

get/v1/wallet-balances/{country}
Request samples
Response samples
application/json
{
  • "balances": [
    • {
      • "country": "ZMB",
      • "balance": "21798.03",
      • "currency": "ZMW",
      • "mno": ""
      }
    ]
}

Toolkit

MNO Availability

Mobile Network Operators (MNOs) sometimes have instability in processing payments. Read more from MNO Stability.

Our 24/7 payment operations team constantly monitors all the MNOs available on our platform for any degraded performance or downtime. From this endpoint you can get the current processing status of each MNO. This endpoint returns all MNOs (correspondents) grouped by country. Each operation type has a separate status.

Following statuses are possible for different operations:

Status Description
OPERATIONAL The MNO (correspondent) is operational and open for processing requests.
DELAYED The MNO (correspondent) is having problems processing payouts. Our payment operations team is currently monitoring the MNO. Payouts are being enqueued and will be processed once the problems have been resolved.
CLOSED The MNO (correspondent) is having problems and all requests are being rejected by pawaPay.
Responses
200

If a request has been processed by pawaPay successfully.

Response Schema: application/json
Array
country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

required
Array of objects (GatewayAvailabilityCorrespondentResult)
500

If a system error has occured.

get/availability
Request samples
Response samples
application/json
[
  • {
    • "country": "GHA",
    • "correspondents": [
      • {
        • "correspondent": "VODAFONE_GHA",
        • "operationTypes": [
          • {
            • "operationType": "DEPOSIT",
            • "status": "OPERATIONAL"
            },
          • {
            • "operationType": "PAYOUT",
            • "status": "DELAYED"
            }
          ]
        },
      • {
        • "correspondent": "MTN_MOMO_GHA",
        • "operationTypes": [
          • {
            • "operationType": "DEPOSIT",
            • "status": "OPERATIONAL"
            },
          • {
            • "operationType": "PAYOUT",
            • "status": "OPERATIONAL"
            }
          ]
        },
      • {
        • "correspondent": "AIRTELTIGO_GHA",
        • "operationTypes": [
          • {
            • "operationType": "DEPOSIT",
            • "status": "CLOSED"
            },
          • {
            • "operationType": "PAYOUT",
            • "status": "DELAYED"
            }
          ]
        }
      ]
    },
  • {
    • "country": "ZMB",
    • "correspondents": [
      • {
        • "correspondent": "MTN_MOMO_ZMB",
        • "operationTypes": [
          • {
            • "operationType": "DEPOSIT",
            • "status": "CLOSED"
            },
          • {
            • "operationType": "PAYOUT",
            • "status": "OPERATIONAL"
            }
          ]
        },
      • {
        • "correspondent": "AIRTEL_OAPI_ZMB",
        • "operationTypes": [
          • {
            • "operationType": "DEPOSIT",
            • "status": "OPERATIONAL"
            },
          • {
            • "operationType": "PAYOUT",
            • "status": "DELAYED"
            }
          ]
        }
      ]
    }
]

Active Configuration

Allows you to query the MNOs that have been configured for your account. You can also get supporting information about your configuration:

  • Your company name on your pawaPay account.
  • The currency for the MNO.
  • Minimum and maximum amount for deposits, payouts and refunds.
  • The name of the company that is shown to the customer on the SMS receipt.
SecuritybearerAuth
Responses
200

If a request has been processed by pawaPay successfully.

Response Schema: application/json
merchantId
required
string

Your unique alphanumeric ID in the pawaPay platform.

merchantName
required
string

Your company name as configured in the pawaPay platform.

required
Array of objects (CustomerActiveCountryConfigResponse)
401

Authentication Failure. Please check your authentication token

500

If a system error has occured.

get/active-conf
Request samples
Response samples
application/json
{
  • "merchantId": "MERCHANT_INC",
  • "merchantName": "Merchant Inc.",
  • "countries": [
    • {
      • "country": "GHA",
      • "correspondents": [
        • {
          • "correspondent": "AIRTELTIGO_GHA",
          • "currency": "GHS",
          • "ownerName": "Merchant Inc.",
          • "operationTypes": [
            • {
              • "operationType": "DEPOSIT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 1000
              },
            • {
              • "operationType": "PAYOUT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 1000
              },
            • {
              • "operationType": "REFUND",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 1000
              }
            ]
          },
        • {
          • "correspondent": "MTN_MOMO_GHA",
          • "currency": "GHS",
          • "ownerName": "Merchant Inc.",
          • "operationTypes": [
            • {
              • "operationType": "DEPOSIT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 2000
              },
            • {
              • "operationType": "PAYOUT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 2000
              },
            • {
              • "operationType": "REFUND",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 2000
              }
            ]
          }
        ]
      },
    • {
      • "country": "ZMB",
      • "correspondents": [
        • {
          • "correspondent": "AIRTEL_OAPI_ZMB",
          • "currency": "ZMW",
          • "ownerName": "pawaPay Zambia",
          • "operationTypes": [
            • {
              • "operationType": "DEPOSIT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 10000
              }
            ]
          },
        • {
          • "correspondent": "MTN_MOMO_ZMB",
          • "currency": "ZMW",
          • "ownerName": "pawaPay Zambia",
          • "operationTypes": [
            • {
              • "operationType": "DEPOSIT",
              • "minTransactionLimit": 1,
              • "maxTransactionLimit": 10000
              }
            ]
          }
        ]
      }
    ]
}

Predict Correspondent

Predicts the correspondent (Mobile Network Operator) for the specified phone number (MSISDN).

Average misprediction rate when using this endpoint is 0.12%.

Please note! Benin has a relatively high level of number portability and therefore has an average misprediction rate of 6%.

SecuritybearerAuth
Request
Request Body schema: application/json
required
msisdn
required
string (FlexibleMsisdnValue)

The phone number (MSISDN) to predict the correspondent of. Must contain the country code.

The input will be sanitized by:

  • removing the leading + sign
  • removing all whitespace
  • removing non-numeric characters
Responses
200

Correspondent prediction was successful

Response Schema: application/json
country
required
string (Country)

The country in which the MNO operates.

Format is ISO 3166-1 alpha-3, three character country code in upper case. Read more from https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.

operator
required
string

The name of the MNO associated with the specified MSISDN.

correspondent
required
string (Correspondent)

The correspondent code refers to the specific MNO that the specified phone number (MSISDN) has an active mobile money wallet with.

You can find all the supported correspondents listed here.

The active configuration endpoint provides the list of correspondents configured for your account.

You can use the predict correspondent enpoint to predict the correct correspondent to use based on the phone number (MSISDN).

msisdn
required
string (PredictedMsisdnValue)

The correctly formatted phone number (MSISDN) from your original request that is in a valid format for the rest of the pawaPay Merchant API.

400

Request is rejected due to incompatibility with pawaPay API specification

401

Authentication Failure. Please check your authentication token

403

Authorization Failure. Please check your authentication token

500

Internal Server Error

post/v1/predict-correspondent
Request samples
application/json
{
  • "msisdn": "+260 763-456789"
}
Response samples
application/json
{
  • "country": "ZMB",
  • "operator": "MTN",
  • "correspondent": "MTN_MOMO_ZMB",
  • "msisdn": "260763456789"
}