Direct payments
Mobile money
Send channel "mobile_money" with flow "direct". No redirect and no hosted page.
Where it works
| Provider | Currencies | Notes |
|---|---|---|
| Paystack | GHS, KES | Phone prompt. Vodafone Ghana asks for a voucher code instead. |
| Flutterwave | GHS, KES, UGX, RWF, ZMW, TZS, XOF, XAF | Kenya and Tanzania send a prompt to the phone. Every other currency redirects the customer to a Flutterwave page to approve. XOF and XAF need a country and a network for it. |
| Fincra | KES, GHS, UGX, ZMW, TZS, XOF, XAF | Direct only. Connect Fincra with your business ID. |
Tunnel only uses a connected provider that supports the channel and currency. If none does, the call returns 400 UNSUPPORTED_CHANNEL.
Request
| Field | Type | Required | Notes |
|---|---|---|---|
| reference | string | Required | Your own id for this payment. Sending the same reference again returns the original collection. |
| flow | "direct" | Required | Completes the payment through the API with no redirect to a hosted page. |
| amount | number | Required | In the major unit of the currency: 5000 is ₦5,000.00. |
| currency | string | Required | ISO code. It must be one this method supports (see above). |
| customer.email | string | Required | Every provider needs it. |
| channel | "mobile_money" | Required | Selects this method. |
| paymentMethod.mobileMoney.provider | string | Required, except Flutterwave RWF and TZS | The network: mtn, vodafone, airteltigo, airtel or mpesa. See the table below. |
| paymentMethod.mobileMoney.phone | string | Required | The wallet’s number. For UGX, ZMW, TZS, XOF and XAF include the country code, for example +256772123456. |
| paymentMethod.mobileMoney.country | string | Flutterwave XOF and XAF: required | Two letter country code of the wallet, for Flutterwave XOF and XAF. XOF: CI, SN, BF. XAF: CM. The network must be one that country has (see the table below). Other providers ignore it. |
| customer.name | string | Optional | Shown on the provider’s receipt where supported. |
| customer.phone | string | Optional | Contact number. |
| provider | string | Optional | Force one provider. Leave it out to let your routing rules choose. |
| metadata | object | Optional | Your own key and value pairs, passed to the provider where supported. |
{
"reference": "ord_1003",
"flow": "direct",
"amount": 150,
"currency": "GHS",
"channel": "mobile_money",
"customer": { "email": "kwame@example.com" },
"paymentMethod": {
"mobileMoney": { "provider": "mtn", "phone": "0551234987" }
}
}curl -X POST "https://xv9ni4gwk9.execute-api.us-east-1.amazonaws.com/dev/v1/collections" \
-H "Authorization: Bearer sk_test_…" \
-H "Content-Type: application/json" \
-d '{
"reference": "ord_1003",
"flow": "direct",
"amount": 150,
"currency": "GHS",
"channel": "mobile_money",
"customer": { "email": "kwame@example.com" },
"paymentMethod": { "mobileMoney": { "provider": "mtn", "phone": "0551234987" } }
}'Response
{
"success": true,
"data": {
"transactionId": "txn_6b1e0a9c2d3f4871",
"reference": "ord_1003",
"provider": "paystack",
"status": "requires_action",
"amount": 150,
"currency": "GHS",
"channel": "mobile_money",
"nextAction": {
"type": "await_customer",
"message": "Approve the payment on your phone"
}
}
}Networks by currency: GHS mtn, vodafone, airteltigo. KES mpesa. UGX, ZMW, XOF and XAF mtn or airtel. TZS airtel. RWF takes no network. On Flutterwave, XOF and XAF take the networks of the chosen country: Côte d'Ivoire mtn, orange, moov, wave; Senegal orange, wave; Burkina Faso mobicash; Cameroon (XAF) mtn, orange. Zambia takes mtn only. Tanzania takes no network. Burkina Faso Orange Money is not offered yet because the payer must first generate a code on their phone. A currency with one network needs no choice from the customer.
A charge can also settle inside the create call. Then status is successful and there is no nextAction.
Next action types
When status is requires_action, switch on nextAction.type. These are the types you can get for this method.
| type | What it carries | What you do |
|---|---|---|
| await_customer | message only. | Tell the customer to approve the payment on their phone, and keep the page open while you wait. |
| otp | A message. Paystack Vodafone Ghana uses this for the voucher code. | Collect the code and send it to the authorize endpoint. |
| redirect | redirectUrl. Flutterwave Ghana. | Send the customer to that page to approve, then bring them back and wait for the final status. |
The flow
- 01Collect the network and number. Check the number has a country code where one is needed.
- 02Create.
POST /v1/collectionswithchannel: "mobile_money". ReadnextAction.typeand do what it says. - 03The customer approves. On their phone, with a code, or on an approval page.
- 04Tunnel checks and tells you. Your webhook receives the final status.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | Waiting for the customer to approve, or to send a code. |
| pending | The customer has acted and the network is processing. Wait for the final status. |
| successful | The wallet was debited. Final. |
| failed | Declined, the prompt expired, or the wallet had too little money. Final. |
Confirm the final status with verify or a webhook. Never treat the customer coming back to your site as proof of payment.
Sending a code
Submit the code a nextAction asks for
{ "type": "otp", "otp": "482913" }You get the updated collection back. A wrong code returns an error and the collection keeps waiting, so show the message and let the customer try again.
Errors to expect
| When | Code | Meaning | What to do |
|---|---|---|---|
| Create | 400 VALIDATION_ERROR | A required field is missing or malformed. | Nothing was charged. Fix the request and resend it with the same reference. |
| Create | 400 UNSUPPORTED_CHANNEL | No connected provider supports this channel and currency for direct payments. | Connect a provider that does, or use the hosted flow. |
| Create | 400 NO_PROVIDERS | No provider is enabled for this mode (test or live). | Connect and enable a provider in the dashboard. |
| Create | 422 | The provider declined the charge. | Use a new reference to try again. |
| Create | 503 PROVIDER_UNAVAILABLE | A temporary problem at the provider. | Retry with the same reference. |
| Authorize | 400 INVALID_OTP_OR_PIN | The code was wrong. | The collection keeps waiting. Let the customer try again. |
Every error uses the shape on the errors page.