What you should know
How to start
How is this different from the Payment Page?
Both the Payment Page and checkouts give your customers a hosted, redirect-based payment experience, so a single API call and a redirect is all you need to get paid. The difference is the level of control and tracking:What does it look like
When you create a checkout you receive aredirectUrl. You forward your customer to that hosted payment page to pay you. It is optimised for mobile money:
- A 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 providers.
- The fields shown adapt to how you configure the checkout (see Different ways to use a checkout).
Pay

Authorise the payment

All done

Creating and using a checkout
Create the checkout
checkoutId must be a UUIDv4 that you generate and store before making the request.
This is so that you always have a reference to the checkout you are expecting, even if you do not receive a response from us due to network errors.
This allows you to always reconcile all payments between your system and PawaPay.The minimal valid request only requires checkoutId and returnUrl.
If you provide payer, then payer.accountDetails.allowCustomerToOverride is required.
When accepted, the response returns the redirectUrl for the hosted payment page that you forward the customer to.You will receive a response immediately.checkoutCode — a unique code for the checkout that also forms the path of the redirectUrl.
Store it alongside your checkoutId: when the customer is sent back to your returnUrl, the checkoutCode is appended as a query parameter.
It is how you find the checkout — and the checkoutId you stored for it — that the customer is returning from.You can tailor the customer experience through the optional parameters below.returnUrl once the payment is finished or cancelled. The returnMethod controls how that happens:Redirect the customer
redirectUrl.This hosted payment page is where the customer selects or confirms the wallet details and authorises the payment.
Once the checkout flow finishes, the customer will be redirected to the returnUrl you provided, according to the returnMethod, with the checkoutCode appended as a query parameter.Track the checkout status
POST a checkout callback to your callback URL when the checkout reaches a final status.You can also poll the status at any time. The status response gives you the overall checkout status together with the current payment attempt and the full history of attempts.deposit contains the latest payment attempt when one exists.
depositsHistory contains the full history of attempts for the checkout. PawaPay records these for you — you normally only need the checkout status.Expire an unused checkout if needed
Different ways to use a checkout
The same checkout endpoint supports a range of payment experiences, controlled by what you provide foramounts, countries and payer. Pick the combination that matches your use case.
The two parameters that shape the experience the most are:
amounts— fix the amount(s) the customer can pay, or leave it out to let them enter their own.payer— pre-fill the mobile money wallet, and decide withallowCustomerToOverridewhether the customer may change it.
Let the customer choose everything
checkoutId and returnUrl.
Fix the amount, let the customer choose the wallet
amounts and the amount is locked.amounts requires country, currency and amount together. The currency must be one that is supported in the specified country.If the customer can pay from more than one country, you must include an amounts entry for every country and currency combination you want to support — the page shows the entry matching the country the customer is paying from. A country can also support more than one currency: for example, in the DRC (COD) both the Congolese franc (CDF) and US dollar (USD) are supported, so to offer USD you must include a USD entry as well.
Offer a few fixed amount options
amounts.
Restrict which countries are available
countries to narrow it.Fix a single country so the customer can only pay from there:amounts as well, make sure the country of each amount option falls within the allowed countries. The page shows the amount option matching the country the customer is paying from.
Pre-fill the payer, but let the customer change it
allowCustomerToOverride: true still lets them pay from a different wallet if they want. Provide payer with allowCustomerToOverride set to true.
Fix the payer so it cannot be changed
payer with allowCustomerToOverride set to false and the wallet is locked.
Fix everything for a one-tap authorisation
amounts entry with a fixed payer leaves the customer nothing to enter but the authorisation.
The checkout lifecycle
A checkout moves through its own statuses, independently of the individual payment attempts inside it.- The initiation status returned in the initiate checkout response —
ACCEPTED,REJECTEDorDUPLICATE_IGNORED— tells you whether the request was accepted for processing. - The lifecycle status below — returned by check checkout status and in callbacks — tracks the checkout itself. Once accepted, a checkout enters its lifecycle at
WAITING_PAYMENT.
depositStatus and each entry in depositsHistory reflect the payment attempts, which follow the standard payment lifecycle (ACCEPTED, PROCESSING, COMPLETED, FAILED).
depositsHistory automatically — you don’t need to create or manage anything.Cancellation and returning to your site
The customer is sent back to yourreturnUrl with the checkoutCode appended as a query parameter:
checkoutCode to look up the checkout — and the checkoutId you stored for it — in your system, so you know which checkout the customer is returning from.
The customer is returned in these cases:
- The payment succeeds — the customer is returned automatically, following the
returnMethodyou set: immediately (INSTANT), after a short countdown (COUNTDOWN), or when they press Return to merchant (CUSTOMER_ACTION). - The customer cancels — they can press Cancel payment on the hosted payment page. They are asked to confirm (“Yes, cancel” / “No, stay”), and once they confirm they are redirected back to your
returnUrl. The checkout status becomesCANCELLED.
How to find out the result
Waiting for a callback or polling
returnUrl, use the checkoutCode query parameter to find the corresponding checkoutId in your system, then validate the final status by either confirming the callback has been received or using the check checkout status endpoint.And done!
Handling processing failures
If an attempt’sstatus is FAILED, you can find further information about the failure from its failureReason.
It includes the failureCode and the failureMessage indicating what has gone wrong.
Checkout payments use the same failure codes as standard deposits.
Find all the failure codes and implement handling as you choose.
Because the customer can make multiple attempts within a checkout, a failed attempt does not necessarily mean the checkout has failed — they can simply retry within the same checkout, with no action needed from you. Treat the checkout as failed only when its own status is FAILED, EXPIRED or CANCELLED.
Ensuring consistency
When working with financial APIs there are some considerations to take to ensure that you never think a payment is failed, when it is actually successful or vice versa. It is essential to keep systems in sync on the statuses of payments. Let’s take a look at some considerations and pseudocode to ensure consistency.Defensive status handling
Handling network errors and system crashes
checkoutId for each checkout is to ensure that you can always ask us what the status of a checkout is, even if you never get a response from us.You should always store this checkoutId in your system before initiating a checkout.
Once the checkout has been accepted, you should also store the checkoutCode from the response — it is appended to your returnUrl as a query parameter and is how you find the right checkout when the customer is redirected back to your site.ACCEPTED by PawaPay.Implementing an automated reconciliation cycle
Payments in reconciliation
When using PawaPay all payments are reconciled by default and automatically — we validate every final status to ensure there are no discrepancies. Sometimes the final status of a payment attempt cannot be determined immediately and the attempt is sent to our automatic reconciliation engine. While this happens, the payment attempt — and the checkout — simply remain inPROCESSING; the Checkout API does not surface a separate reconciliation status.
You do not need to take any action — the final status will be determined soon.
The reconciliation time varies by provider. Payments that turn out to be successful are reconciled faster.