Direct payments

Mobile money

The customer approves the payment from their mobile money wallet. Depending on the network that is a prompt on their phone, a code they type back, or an approval page.
POST/v1/collections

Send channel "mobile_money" with flow "direct". No redirect and no hosted page.

Where it works

Providers and currencies
ProviderCurrenciesNotes
PaystackGHS, KESPhone prompt. Vodafone Ghana asks for a voucher code instead.
FlutterwaveGHS, KES, UGX, RWF, ZMW, TZS, XOF, XAFKenya 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.
FincraKES, GHS, UGX, ZMW, TZS, XOF, XAFDirect 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

Request fields
FieldTypeRequiredNotes
referencestringRequiredYour own id for this payment. Sending the same reference again returns the original collection.
flow"direct"RequiredCompletes the payment through the API with no redirect to a hosted page.
amountnumberRequiredIn the major unit of the currency: 5000 is ₦5,000.00.
currencystringRequiredISO code. It must be one this method supports (see above).
customer.emailstringRequiredEvery provider needs it.
channel"mobile_money"RequiredSelects this method.
paymentMethod.mobileMoney.providerstringRequired, except Flutterwave RWF and TZSThe network: mtn, vodafone, airteltigo, airtel or mpesa. See the table below.
paymentMethod.mobileMoney.phonestringRequiredThe wallet’s number. For UGX, ZMW, TZS, XOF and XAF include the country code, for example +256772123456.
paymentMethod.mobileMoney.countrystringFlutterwave XOF and XAF: requiredTwo 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.namestringOptionalShown on the provider’s receipt where supported.
customer.phonestringOptionalContact number.
providerstringOptionalForce one provider. Leave it out to let your routing rules choose.
metadataobjectOptionalYour own key and value pairs, passed to the provider where supported.
Example body
{
  "reference": "ord_1003",
  "flow": "direct",
  "amount": 150,
  "currency": "GHS",
  "channel": "mobile_money",
  "customer": { "email": "kwame@example.com" },
  "paymentMethod": {
    "mobileMoney": { "provider": "mtn", "phone": "0551234987" }
  }
}
cURL
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

HTTP 201, requires_action (phone prompt)
{
  "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.

Next action types
typeWhat it carriesWhat you do
await_customermessage only.Tell the customer to approve the payment on their phone, and keep the page open while you wait.
otpA message. Paystack Vodafone Ghana uses this for the voucher code.Collect the code and send it to the authorize endpoint.
redirectredirectUrl. Flutterwave Ghana.Send the customer to that page to approve, then bring them back and wait for the final status.

The flow

  1. 01Collect the network and number. Check the number has a country code where one is needed.
  2. 02Create. POST /v1/collections with channel: "mobile_money". Read nextAction.type and do what it says.
  3. 03The customer approves. On their phone, with a code, or on an approval page.
  4. 04Tunnel checks and tells you. Your webhook receives the final status.

Statuses to expect

Statuses
statusMeaning
requires_actionWaiting for the customer to approve, or to send a code.
pendingThe customer has acted and the network is processing. Wait for the final status.
successfulThe wallet was debited. Final.
failedDeclined, 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

POST/v1/collections/{reference}/authorize

Submit the code a nextAction asks for

Body
{ "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

Errors
WhenCodeMeaningWhat to do
Create400 VALIDATION_ERRORA required field is missing or malformed.Nothing was charged. Fix the request and resend it with the same reference.
Create400 UNSUPPORTED_CHANNELNo connected provider supports this channel and currency for direct payments.Connect a provider that does, or use the hosted flow.
Create400 NO_PROVIDERSNo provider is enabled for this mode (test or live).Connect and enable a provider in the dashboard.
Create422The provider declined the charge.Use a new reference to try again.
Create503 PROVIDER_UNAVAILABLEA temporary problem at the provider.Retry with the same reference.
Authorize400 INVALID_OTP_OR_PINThe code was wrong.The collection keeps waiting. Let the customer try again.

Every error uses the shape on the errors page.