Payment Gateway Africa Developer Documentation

Payment Gateway Africa is a payment gateway. It handles pay-ins (collecting money from your customers), payouts (sending money to recipients where available for the method and project) and merchant settlement. These are three separate flows. Each one has its own requests, statuses and records.

There are two ways to connect. You can use the Hosted Payment Page, or you can call the H2H (host-to-host) API from your server. These are two connection methods for the same gateway, not two different products. Either way, your own system keeps the order and the business logic.

Read the pages in this order: this overview, then integration options, then the API concepts guide, then postbacks and webhooks, and finally testing your integration. Each page links to the next one, so you can follow the sequence from start to finish.

Notice: Full API reference and credentials are provided after merchant onboarding. The examples in these docs show concepts only. They use placeholders such as {API_BASE_URL} and neutral field names. They do not show the live schema.

Hosted page. Your backend creates a payment and receives a link to the payment page. You redirect the customer to that page. The customer chooses a local method, such as a mobile wallet, and confirms the payment in the way that method requires. When they finish, the customer returns to your site and the final status arrives at your backend. This path needs the least front-end work. See how the hosted page compares with H2H.

H2H API. Your server sends payment requests directly to the gateway. You build the customer-facing steps yourself. You control what the customer sees and when, and you take on more responsibility for handling every state the payment can pass through. The conceptual API walkthrough covers how requests and statuses are structured.

Webhooks. Both paths send status updates to your backend as postbacks. These notifications go to you, the merchant. The gateway does not send a separate notification service to your customers, so your system decides what the customer is told. Setup details and handling tips are in the webhook handling guide.

Testing. Before going live, you work in a separate test project with its own keys and project ID. On request, support can set the callback statuses you need, so you can check successful, failed and pending scenarios, and confirm that your reconciliation logic holds up. The test project checklist lists what to verify.

Every integration has three participants: your merchant backend, the Payment Gateway Africa platform, and the customer. The flow below shows a pay-in through the hosted page.

Merchant backend → gateway: create a payment with an amount, a currency, your order reference and a return address. Gateway → merchant backend: return a payment identifier and the payment page link. Merchant backend → customer: redirect the customer to the payment page. Customer ↔ gateway: the customer selects a method and completes any confirmation step that method requires. Gateway → merchant backend: send a postback with the resulting status. Merchant backend → customer: show the result, based on the status your system recorded.

Treat the postback as the main signal. Do not rely on the customer returning to your site. Customers close tabs, lose connectivity or switch apps partway through a mobile wallet confirmation. If you missed a postback, you can query the payment status to catch up. Reports and the merchant portal let you reconcile at the end of the day.

Conceptual request (H2H, placeholders only): POST {API_BASE_URL}/payments { "project_id": "{PROJECT_ID}", "order_reference": "order-1042", "amount": "1500.00", "currency": "KES", "method": "{METHOD}", "callback_url": "https://merchant.example/postbacks" }

Conceptual postback body your endpoint might receive: { "payment_id": "{PAYMENT_ID}", "order_reference": "order-1042", "status": "{STATUS}", "amount": "1500.00", "currency": "KES" }

The gateway covers seven markets. Each market uses its own currency and local methods: - Kenya: KES, through M-Pesa. - Egypt: EGP, through mobile wallet payments identified by phone number. - Ethiopia: ETB, through CBE Birr, M-Pesa and local transfers. - Senegal: XOF, through Wave and Orange Money. - Mali: XOF, through Wave, Orange Money and Moov Money. - Guinea: GNF, through Orange Money. - Tunisia: TND, through D17 and Flouci.

Depending on the method, the customer may need to confirm the payment on their own device. Because that step happens outside your checkout, your code should expect pending states that resolve later. For an explanation of how wallet confirmation works in online checkout, read the mobile money payment gateway overview. Per-market details are in the directory of supported countries.

Existing merchants can enable additional supported methods at no extra connection charge, and your connection price stays the same regardless of how many methods you use. For existing merchants, activating an already supported method can often be completed within one day.

Pay-in: money a customer sends to you through a supported local method. A pay-in starts with your request and ends with a final status delivered to your backend.

Payout: money sent from your balance to a recipient, such as a customer or partner. Payouts are offered where available for the method and project. Treat them as a separate flow with their own statuses.

Settlement: the transfer of the funds you have collected to you, the merchant. Payment Gateway Africa dispatches merchant settlements same-day (T+0). This refers to when a settlement leaves Payment Gateway Africa. The time it is posted to your account depends on your bank.

Postback: a server-to-server notification from the gateway to the address you configure. It reports a status change for a pay-in or payout. Your endpoint should verify every postback, process it idempotently, and acknowledge it.

Project ID: the identifier for your configured project. Your methods, currencies and credentials are attached to the project. You use one project for testing and a separate live project after onboarding.

You receive live credentials after merchant onboarding, which includes a KYB review. To prepare documents in advance, read the merchant verification requirements. Our approach to protecting your account and its access is described on the security practices page.

Before you go live, confirm these points: - Your postback endpoint is publicly reachable and handles repeat deliveries safely. - Your system maps every gateway status to an order state. - You have tested status queries as a fallback for missed postbacks. - Your reports match your records for pay-ins, payouts and settlements separately.

Our overall transaction success rate is 85%, measured as successful transactions divided by all transactions. Design your checkout so that customers whose payment did not complete can retry easily.

When your test project behaves as expected, send your application to start onboarding. Through apply to start accepting payments, you can tell us your target markets, methods and integration type, and we will set up your live project.

Next in the docs: Integration: hosted page or H2H API.