This guide explains how to collect payments directly from your customers’ Mobile Money accounts using Payaza — covering MoMo (GHS, KES, UGX, TZS, LRD, XAF), XOF (Côte d’Ivoire and Benin), and ZAR EFT and Capitec (South Africa).
Retrieve your API keys from your dashboard by following the steps on our
Authentication page. Use your public API key for
all collection requests.
Set the following headers on every request:
{ "Authorization": "Payaza <Your public API key encoded in base 64>", "X-TenantID": "test", "X-ProductID": "app"}
Set X-TenantID to test while developing and live when processing real
payments. X-ProductID defaults to "app" for all requests.
Collections to countries other than Nigeria are available on request only.
Send an email to support@payaza.africa to
request access. You will be granted access once the team reviews and approves
your request.
Make sure your webhook URL is saved on the dashboard and configured to accept POST requests. See our Webhooks guide for setup instructions.
Mobile Money collections follow a different flow from card payments because the customer must approve the payment on their own phone.The flow varies slightly depending on the collection type:
Standard MoMo flow (GHS, KES, UGX, TZS, XAF, LRD)
Your server calls Process Collection with the customer’s
phone number and amount.
Payaza instructs the telecom network to send a
USSD prompt to the customer’s phone.
The customer sees a message like
“Approve payment of GHS 50 to Business X?” and enters their MoMo
PIN.
Your server uses the Transaction Status Query API or
listens for a webhook to confirm success or failure.
XOF flow — Côte d'Ivoire and Benin (OTP is only required for Orange CIV XOF Collections)
Your server calls Process Collection.
Check the requires_otp field in the response:
If false — the customer is prompted directly on their
phone. Check for the status.
If true — the customer receives an OTP via SMS. Your UI
must collect the OTP and submit it via
XOF Process OTP API before the payment can proceed.
After the OTP is submitted
(Required for Orange CIV XOF Collections), use the
Transaction Status Query or listen for a webhook.
ZAR EFT and Capitec flow — South Africa
Your server calls Process Collection with
currency_code: “ZAR”.
The response includes a payment_completion_url.
Redirect the customer to this URL to complete their EFT
or Capitec payment.
After the customer completes the bank redirect, Use the
Transaction Status Query API or listen for a webhook.
SLE flow — Sierra Leone (Afrimoney, Orange Money)
Your server calls Process Collection with
currency_code: “SLE” and the customer’s Sierra Leone mobile
money number.
Payaza instructs the mobile money network (Afrimoney or Orange Money) to
send a payment prompt to the customer’s phone.
The customer approves the payment on their device.
Use the Transaction Status Query API or listen for a
webhook to confirm the final outcome.
Sample response XOF with OTP required(For Orange CIV Only)
{ "response_code": "09", "response_message": "PENDING", "requires_otp": true, "otp_length": 4, "before_payment_instruction": "1/ Générer un code provisoire en ouvrant l'application Orange Money Afrique et en sélectionnant \\\"Mon Compte\\\", ou en composant le #144*82# et en effectuant l'appel.\\r\\n---\\r\\n2/ Entrez votre code secret et confirmez.\\r\\n---\\r\\n3/Copiez le code que vous avez reçu par SMS et collez-le dans le champ prévu à cet effet.", "after_payment_instruction": "Merci de confirmer le paiement en suivant les directives fournies dans le SMS que vous avez reçu.", "payment_token": "fcda6596-c7ec-4adb-8030-b8725dbfc66c", "payee": "+2251114462945", "transaction_channel": "MOMCIV", "transaction_reference": "MOCIV0009383"}
Sample response — XOF with No OTP required
{ "response_code": "09", "response_message": "PENDING", "requires_otp": false, "otp_length": 0, "before_payment_instruction": "Assurez-vous de disposer de fonds suffisants sur votre compte mobile money pour réaliser ce paiement.", "after_payment_instruction": "Merci de confirmer le paiement en suivant les directives fournies dans le SMS que vous avez reçu.", "payment_token": "e20467b2-d53d-484e-8fd5-a57fcb428d33", "payee": "+2250004768076", "payment_method": "MTN_CI", "transaction_channel": "MOMCIV", "transaction_reference": "MOCIV0009384"}
A response_code: "09" and response_message: "PENDING" is the expected
successful response from this endpoint. It does not mean the collection
succeeded — it means the prompt has been sent or the redirect URL is ready.
Always confirm the final outcome via Step 3 (Status Query) or a webhook.
This step only applies to XOF collections where the initial Process
Collection response returned requires_otp: true. This applies to all Orange
CIV Money transactions. Skip to Step 3 for all other currencies.
When requires_otp is true, the customer receives an OTP on their phone. Your UI must collect this code from the customer and submit it before the payment can be authorised.Use the payment_token, payee, payment_method, and transaction_channel values directly from the Process Collection response.
curl --request POST \ --url https://api.payaza.africa/live/subsidiary/collections/v1/process-otp \ --header 'Authorization: Payaza <Your public API key encoded in base 64>' \ --header 'Content-Type: application/json' \ --header 'X-ProductID: app' \ --header 'X-TenantID: test' \ --data '{ "payment_token": "45c3d124-7831-4f97-8844-581bf497a20b", "otp_code": "4567", "payee": "+2251114462945", "payment_method": "ORANGE_CI", "transaction_reference": "MOCIV0009383", "transaction_channel": "MOMCIV", "country_code": "CI"}'
Check the final status of a collection. Use this endpoint to confirm whether the payment was successful, failed, or is still pending.When to use it: Use this endpoint after initiating a collection (and after submitting the OTP for XOF), or use it as a fallback if a webhook is not received.
curl --request GET \ --url 'https://api.payaza.africa/live/subsidiary/collections/v1/check-status?transaction_reference=COL-REF-20240501-001&country_code=GH' \ --header 'Authorization: Payaza <Your public API key encoded in base 64>' \ --header 'X-TenantID: test' \ --header 'X-ProductID: app'
Sample response — pending (customer has not yet approved)
Never assume a MoMo collection was successful just because the initial request
went through. A customer can ignore the USSD prompt, cancel it, or have
insufficient funds. Always confirm the final status via this endpoint or a
webhook before fulfilling an order.
Payaza sends webhook events for both successful and failed collections. Webhooks are the recommended way to receive the final status rather than continuous polling.
Event
When it fires
Successful Collection
The customer approved the payment and funds were received
Always generate a unique transaction_reference per collection to avoid duplicate errors.
A response_code: "09" on Process Collection is normal — it means the prompt was sent, not that the collection succeeded.
For XOF, check requires_otp in the Process Collection response before deciding whether to show an OTP input field in your UI.
For ZAR, check redirect_customer_to_url_processing and redirect the customer to payment_completion_url to complete payment via their bank.
Webhooks are sent for both successful and failed collections. Use Transaction Status Query as a fallback when a webhook is not received within your expected timeout.
Collections are not retried automatically. If a collection fails or times out, your application must handle the retry logic and generate a new transaction_reference.
Use the bank code that matches both the currency and the telecom network of the customer’s MoMo account. Mismatched bank codes will fail silently on some networks.
