Direct payments

NQR (QR code)

Tunnel returns a QR code. The customer scans it with any Nigerian bank app that supports NIBSS QR and confirms the payment, and Tunnel tells you when the money arrives.
POST/v1/collections

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

Where it works

Providers and currencies
ProviderCurrenciesNotes
FlutterwaveNGNNigeria only. Charged as a QR payment with the NIBSS flag set.
PaystackNoneIts Charge API answers “QR payment not supported” for the QR providers we tried.
FincraNoneFincra lists no QR option for NGN.

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"nqr"RequiredSelects this method. It is only available with flow "direct".
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_1006",
  "flow": "direct",
  "amount": 3500,
  "currency": "NGN",
  "channel": "nqr",
  "customer": { "email": "ada@example.com" }
}
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_1006",
    "flow": "direct",
    "amount": 3500,
    "currency": "NGN",
    "channel": "nqr",
    "customer": { "email": "ada@example.com" }
  }'

Response

HTTP 201, requires_action (QR code)
{
  "success": true,
  "data": {
    "transactionId": "txn_7a3e91c0d4b2f658",
    "reference": "ord_1006",
    "provider": "flutterwave",
    "status": "requires_action",
    "amount": 3500,
    "currency": "NGN",
    "channel": "nqr",
    "nextAction": {
      "type": "qr_code",
      "message": "Scan this code with your bank app to pay",
      "qrCode": { "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…" }
    }
  }
}

qrCode.image is a data URI, so it goes straight into an img src. It is large (a few kilobytes), so the Tunnel dashboard’s payment list leaves it out and shows it only when you open one payment.

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
qr_codeqrCode.image, a data URI, and a message.Show the image large enough to scan, with the amount beside it. On a phone, tell the customer to screenshot it or open their bank app on another device.

The flow

  1. 01Create. POST /v1/collections with channel: "nqr" and flow: "direct". You get requires_action and a qr_code next action.
  2. 02Show the code with the amount, and a waiting state.
  3. 03The customer scans it in their bank app, checks the amount, and confirms.
  4. 04Tunnel checks and tells you. Your webhook receives transaction.successful or transaction.failed. Release goods only on successful.

Statuses to expect

Statuses
statusMeaning
requires_actionThe code is issued and waiting to be scanned.
pendingThe customer has confirmed and the bank is settling.
successfulThe money arrived. Final.
failedDeclined, or the code was never paid. Final.

Confirm the final status with verify or a webhook. Never treat the customer coming back to your site as proof of payment.

How long a code lasts

Flutterwave does not document an expiry for NQR codes. Treat a collection that has not become successful after a few minutes as unpaid, and create a new one with a new reference rather than reusing the old code.

Amounts

The code is for the exact amount of the collection. If a provider ever reports less than the collection amount as paid, Tunnel records it as failed with amount_mismatch, the same as for bank transfer.

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.
Create400 VALIDATION_ERRORNQR was requested without flow "direct".Send flow: "direct". NQR has no hosted version.

Every error uses the shape on the errors page.