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

Providers and currencies

Direct payment support
MethodPaystackFlutterwaveFincra
Bank transferNGNNGN, GHSNGN, GHS, KES, UGX, ZAR
USSDNGNNGN–
Mobile moneyGHS, KESGHS, KES, UGX, RWF, ZMW, TZS, XOF, XAFKES, GHS, UGX, ZMW, TZS, XOF, XAF
Bank account debitNGNNGN–
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 */ }
}
  1. 01Create the collection. The response has a status and, when the customer must do something, a nextAction.
  2. 02Switch on nextAction.type and show the customer what it asks for.
  3. 03If it asks for a code or a birthday, send it to POST /v1/collections/{reference}/authorize.
  4. 04Wait for the final status from a webhook, or ask with verify.

All next action types

Next action types
typeUsed byWhat you do
bank_transfer_instructionsBank transferShow the account, amount and expiry.
ussd_codeUSSDShow the code to dial.
await_customerMobile moneyAsk the customer to approve on their phone.
otpMobile money, bank accountCollect the code and send it to authorize.
birthdayBank account (Paystack)Collect the date of birth and send it to authorize.
redirectMobile money, bank account and OPay (Flutterwave)Send the customer to redirectUrl to approve.
qr_codeNQRShow 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.