API Reference Overview

Full API reference and credentials are provided after merchant onboarding. Nothing on this page replaces that reference. Use it to plan your backend and to understand which calls your team will need.

When your merchant account is approved, you receive two items. The first is an API key. The second is a project identifier. Each request from your server carries both, so the gateway knows which merchant is calling and which project the operation belongs to.

Store the key only on your backend. Never place it in browser code, a mobile app bundle or a public repository. If you think a key has been exposed, contact support so it can be replaced. Our security responsibilities and yours are set out in more detail on the security page.

If you have not applied yet, the merchant onboarding steps explain the application and KYB review. The verification requirements for merchants describe what the review covers.

The API follows the three money flows the gateway handles. Pay-ins, payouts and settlement are separate flows, and the API keeps them apart. A pay-in call never moves money out to a customer, and a payout call never collects funds.

Pay-ins: you create a payment for a customer in one of the supported countries and methods. The response tells you how to continue. That may mean sending the customer to the Hosted Payment Page, or it may mean waiting while the customer confirms on their phone or wallet app.

Payouts: you send funds to a customer's wallet or account where available for the method and project. Not every method supports payouts, and availability is set per project.

Status and verification: you read the current state of an operation from your server. You also use these calls to confirm the amount that was actually received.

Reports: you request a CSV export of operations for reconciliation. The full reference describes how the export is delivered.

Missing-operation lookups: you open a search for a transaction your records show but the gateway status does not. The search has its own status.

Settlement: you request that your merchant balance is settled to your own wallet or account. The full reference describes the settlement call and any conditions that apply. Merchant settlements are dispatched same-day (T+0). This refers only to dispatch timing; when the money lands depends on the posting schedule of the receiving bank.

All calls go from your server to a base address issued with your credentials. In the examples below it appears as {API_BASE_URL}. Field names are neutral placeholders. The real names, formats and required fields are in the full reference.

Conceptual pay-in request: POST {API_BASE_URL}/payments Headers: authorization with your API key Body: { "project_id": "{PROJECT_ID}", "order_reference": "your-order-123", "amount": "1500", "currency": "KES", "method": "{METHOD}", "customer_phone": "{PHONE}" }

Conceptual response: { "operation_id": "{GATEWAY_ID}", "status": "pending", "next_action": "{REDIRECT_OR_WAIT}" }

Keep your own order reference unique for each order. Save the gateway operation identifier against it. You will need both identifiers when you check a status, match postbacks or open a missing-operation lookup.

Each pay-in names a currency and a method. The method must be enabled for your project in that country. The table below lists the public method names. The API uses its own method values, which are listed in the full reference.

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 the currency alone does not identify the market. Always send the country context your reference requires.

Existing merchants can switch on further supported payment methods without any connection surcharge, and adding more methods leaves their connection price unchanged. For an existing client, activating an already supported method can often be completed within one day. For how each method behaves, see the mobile money payment gateway overview. For market-specific detail, see the list of countries we cover.

Do not release goods because a customer came back to your return page. A browser redirect only shows where the customer went. It does not prove that the payment succeeded.

Use two signals instead. The first is the postback the gateway sends to your endpoint when a status changes. The second is a status request you make from your server. The status response shows the deposit state and the amount actually received. Compare that amount with the order before you fulfil it.

Conceptual status check: GET {API_BASE_URL}/payments/{GATEWAY_ID} Response: { "status": "{STATE}", "amount_received": "{AMOUNT}", "currency": "{CURRENCY}" }

Postbacks and webhooks report status to you, the merchant. The gateway does not send separate notifications to your customers. If you want to tell a customer that a payment has completed, your system sends that message. The webhook and postback guide covers delivery and handling.

You request a CSV report of operations using your filters. The full reference describes the request fields and how the file is delivered.

Your accounting team can use these exports to reconcile pay-ins, payouts and settlements as three separate lines.

Sometimes a customer says they paid, but your records show no final status. In that case, open a missing-operation lookup. Do not create a new payment for the same order.

The lookup is a separate request with its own status, which you can follow until the search ends. Opening a lookup does not charge the customer again and does not create a second payment. Retrying a pay-in, by contrast, starts a new operation. That is why the lookup is the correct path when a status is unclear.

Send your order reference and any identifiers the customer can give you. The full reference lists the fields each method accepts.

Make sure your backend does each of the following: - keeps the API key and project identifier on the server only; - stores your order reference and the gateway operation ID together; - fulfils an order only after a postback and a server-side status check agree; - compares the received amount with the order amount; - handles pay-in, payout and settlement records separately; - uses missing-operation lookups instead of repeating a payment; - collects CSV reports for reconciliation.

If you have not chosen a connection type, compare the Hosted Payment Page with H2H in the integration options guide. Both connect to the same gateway. They differ in how much of the checkout you build yourself.

When you are ready to begin, apply for a merchant account. Your credentials and the full reference will follow approval. Quote factors are explained on the pricing page.