Direct payments
NQR (QR code)
Send channel "nqr" with flow "direct". No redirect and no hosted page.
Where it works
| Provider | Currencies | Notes |
|---|---|---|
| Flutterwave | NGN | Nigeria only. Charged as a QR payment with the NIBSS flag set. |
| Paystack | None | Its Charge API answers “QR payment not supported” for the QR providers we tried. |
| Fincra | None | Fincra 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
| 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 | "nqr" | Required | Selects this method. It is only available with flow "direct". |
| 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_1006",
"flow": "direct",
"amount": 3500,
"currency": "NGN",
"channel": "nqr",
"customer": { "email": "ada@example.com" }
}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
{
"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.
| type | What it carries | What you do |
|---|---|---|
| qr_code | qrCode.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
- 01Create.
POST /v1/collectionswithchannel: "nqr"andflow: "direct". You getrequires_actionand aqr_codenext action. - 02Show the code with the amount, and a waiting state.
- 03The customer scans it in their bank app, checks the amount, and confirms.
- 04Tunnel checks and tells you. Your webhook receives
transaction.successfulortransaction.failed. Release goods only onsuccessful.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | The code is issued and waiting to be scanned. |
| pending | The customer has confirmed and the bank is settling. |
| successful | The money arrived. Final. |
| failed | Declined, 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
| 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. |
| Create | 400 VALIDATION_ERROR | NQR was requested without flow "direct". | Send flow: "direct". NQR has no hosted version. |
Every error uses the shape on the errors page.