Direct payments
Take a payment inside your own page
Send
"flow": "direct" and Tunnel completes the payment through the provider’s API. There is no redirect and no hosted page: you show the customer what to do, in your own design.Choose a method
- Bank transferchannel: bank_transferRequest, response, next actions, flow, statuses and errors
- USSDchannel: ussdRequest, response, next actions, flow, statuses and errors
- Mobile moneychannel: mobile_moneyRequest, response, next actions, flow, statuses and errors
- Bank account debitchannel: bank_accountRequest, response, next actions, flow, statuses and errors
- OPaychannel: opayRequest, response, next actions, flow, statuses and errors
- NQR (QR code)channel: nqrRequest, response, next actions, flow, statuses and errors
Providers and currencies
| Method | Paystack | Flutterwave | Fincra |
|---|---|---|---|
| Bank transfer | NGN | NGN, GHS | NGN, GHS, KES, UGX, ZAR |
| USSD | NGN | NGN | – |
| Mobile money | GHS, KES | GHS, KES, UGX, RWF, ZMW, TZS, XOF, XAF | KES, GHS, UGX, ZMW, TZS, XOF, XAF |
| Bank account debit | NGN | NGN | – |
| OPay | – | NGN | – |
| NQR (QR code) | – | NGN | – |
Card is never direct, because it would put card data through your servers. Use the hosted flow for cards. Fincra takes direct payments only. Tunnel picks a connected provider that supports the channel and currency; if none does, you get 400 UNSUPPORTED_CHANNEL.
Every direct payment has the same shape
POST/v1/collections
Create the payment, then follow nextAction until it settles.
Common request
{
"reference": "ord_1001",
"flow": "direct",
"amount": 5000,
"currency": "NGN",
"channel": "bank_transfer | ussd | mobile_money | bank_account | opay | nqr",
"customer": { "email": "ada@example.com" },
"paymentMethod": { /* depends on the channel */ }
}- 01Create the collection. The response has a
statusand, when the customer must do something, anextAction. - 02Switch on
nextAction.typeand show the customer what it asks for. - 03If it asks for a code or a birthday, send it to
POST /v1/collections/{reference}/authorize. - 04Wait for the final status from a webhook, or ask with verify.
All next action types
| type | Used by | What you do |
|---|---|---|
| bank_transfer_instructions | Bank transfer | Show the account, amount and expiry. |
| ussd_code | USSD | Show the code to dial. |
| await_customer | Mobile money | Ask the customer to approve on their phone. |
| otp | Mobile money, bank account | Collect the code and send it to authorize. |
| birthday | Bank account (Paystack) | Collect the date of birth and send it to authorize. |
| redirect | Mobile money, bank account and OPay (Flutterwave) | Send the customer to redirectUrl to approve. |
| qr_code | NQR | Show qrCode.image, a data URI, for the customer to scan. |
The authorize endpoint
POST/v1/collections/{reference}/authorize
Submit the code or birthday a nextAction asks for
Body
{ "type": "otp", "otp": "482913" }
// or
{ "type": "birthday", "birthday": "1990-01-01" }The response is the updated collection. A wrong code returns 400 INVALID_OTP_OR_PIN and the collection keeps waiting.
Amounts that do not match
A bank transfer for less than the amount fails with
amount_mismatch. A transfer for more settles as successful. See underpayment and overpayment.