Integration Guide

Every project connects to the same gateway. That gateway handles pay-ins (collecting money from customers), payouts (sending money to customers where available for the method and project) and merchant settlement. What changes between the two connection options is who renders the payment step and how much of the flow your own code controls.

With the Hosted Payment Page, your platform sends the customer to a payment page that the gateway provides. The customer completes the payment there in the browser and then returns to your interface.

With the H2H API, your server talks directly to the gateway and you build the payment experience inside your own interface. H2H describes how the systems connect. It is not a white-label arrangement.

If you are still deciding which markets to launch first, the directory of supported African markets lists the currency and methods for each country. The mobile money overview introduces the supported wallets.

No connection option works from the front end alone. Even when the gateway hosts the payment page, your server still has to create operations, receive status updates and record the final result.

A customer returning to your site after a hosted payment tells you nothing reliable about the outcome. A browser can close, a redirect can fail, or a customer can leave halfway through. Treat the return step as navigation only. Your backend must receive and store the result separately before you mark an order as paid.

Status updates reach your server as postbacks (webhooks). They are sent to you as the merchant. The gateway does not run a separate notification service for your customers, so any messages to the customer, such as order confirmations, come from your own systems. The webhook handling guide covers how to receive and process these updates.

The hosted option suits teams that want to go live without building a payment form for each method. The sequence below is conceptual. Exact field names and endpoints come with your onboarding materials.

1. Your server creates a pay-in for the order, with the amount, the currency for the target country and your own order reference.
2. The gateway returns the details needed to send the customer to the hosted page.
3. The customer completes payment on that page with a supported local method, for example M-Pesa in Kenya or Wave in Senegal.
4. The customer is returned to the address you supplied in your interface.
5. Your backend receives a postback with the operation status and updates the order from that result, not from the redirect.

Illustrative request shape: POST {API_BASE_URL}/payments { "project_id": "{PROJECT_ID}", "order_reference": "order-1042", "amount": "1500.00", "currency": "KES", "return_url": "https://your-site.example/checkout/return/" }

The H2H option gives you full control of the checkout screens. Your server collects what the chosen method needs, sends it to the gateway, and shows the customer the right next step.

Mobile wallet payments usually need the customer to confirm the payment on their own device or account. Your interface should therefore tell the customer clearly what to expect, and should keep the order in a pending state until a final status arrives.

If your mobile app uses the Hosted Payment Page, customers complete payment on a browser-based page. Do not plan your mobile experience around an embedded native in-app checkout component.

Request structure, authentication and the grouping of operations are described in the API overview. Examples there use neutral placeholders such as {API_BASE_URL} and {PROJECT_ID} in place of live values.

You do not have to choose one option for your whole business. A single project can use the Hosted Payment Page for some flows and the H2H API for others.

A common pattern is to launch quickly on the hosted page and then move high-traffic flows to the API once your team has built custom screens. In another pattern, the hosted page covers web checkout while H2H handles payouts from your back office.

Whichever mix you choose, keep one source of truth on your backend. Postbacks are the reliable signal for every operation, however it was started.

Design your data model so that pay-ins, payouts and settlement stay separate. They move money in different directions, and mixing them makes reconciliation hard.

Pay-ins collect funds from your customers. Payouts send funds to your customers where the method and project support them. Settlement transfers funds from the gateway to you, the merchant. Payment Gateway Africa dispatches merchant settlements on the day of processing (T+0). This describes dispatch timing only. When the funds appear in your account depends on your bank's posting times.

Give each flow its own records, statuses and postback handling. A payout status should never update a pay-in order, and a settlement entry should never be read as a customer payment.

Your integration works with the confirmed method list for each country you enable. Each country also has its own currency:

Kenya (KES): M-Pesa. Egypt (EGP): mobile wallet payments by phone number. Ethiopia (ETB): CBE Birr, M-Pesa (Ethiopia) and local transfers. Senegal (XOF): Wave and Orange Money. Mali (XOF): Wave, Orange Money and Moov Money. Guinea (GNF): Orange Money. Tunisia (TND): D17 and Flouci.

Senegal and Mali share the XOF currency, so do not rely on the currency alone to identify the market. Your onboarding materials specify how the country or method is set for each operation.

Existing merchants can activate additional supported payment methods with no connection surcharge. Their connection price stays the same however many methods they use. For existing clients, enabling a method that is already supported can often be completed within one day.

Testing cannot start until the gateway knows where to deliver status updates. Before your first test operation, share these handler addresses:

• The endpoint on your server that receives postbacks for incoming payments (pay-ins). • The endpoint on your server that receives postbacks for payouts, if your project uses them. • The return address for customers if you use the Hosted Payment Page.

Make sure these endpoints are reachable from outside your network and return a clear acknowledgement when they receive an update. Each one should also handle a repeated update for the same operation without creating duplicate records.

The testing guide explains how to run test operations once these addresses are in place. Merchant verification runs alongside integration work. The AML and KYC requirements outline the business checks involved, and the security overview describes the responsibilities that sit with your team.