Direct payments
Bank transfer
Send channel "bank_transfer" with flow "direct". No redirect and no hosted page.
Where it works
| Provider | Currencies | Notes |
|---|---|---|
| Paystack | NGN | Pay with Transfer must be enabled on your Paystack account first. |
| Flutterwave | NGN, GHS | Nothing extra to send. |
| Fincra | NGN, GHS, KES, UGX, ZAR | Direct 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
| 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 | "bank_transfer" | Required | Selects this method. |
| paymentMethod.bankTransfer.expiresInMinutes | number | Optional | How long the account stays open, from 15 to 480 minutes. Paystack only; other providers use their own window. |
| 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_1001",
"flow": "direct",
"amount": 12000,
"currency": "NGN",
"channel": "bank_transfer",
"customer": { "email": "ada@example.com", "name": "Ada Obi" },
"paymentMethod": { "bankTransfer": { "expiresInMinutes": 30 } }
}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_1001",
"flow": "direct",
"amount": 12000,
"currency": "NGN",
"channel": "bank_transfer",
"customer": { "email": "ada@example.com" }
}'Response
{
"success": true,
"data": {
"transactionId": "txn_8f2a1c0b4e9d7a6c",
"reference": "ord_1001",
"provider": "paystack",
"status": "requires_action",
"amount": 12000,
"currency": "NGN",
"channel": "bank_transfer",
"nextAction": {
"type": "bank_transfer_instructions",
"message": "Please make a transfer to the account specified",
"bankTransfer": {
"accountNumber": "9930128847",
"accountName": "Adire House / Tunnel",
"bankName": "Wema Bank",
"amount": 12000,
"expiresAt": "2026-11-14T07:30:00.000Z"
}
}
}
}expiresAt is an ISO 8601 time when the provider gives one. Some providers send their own date format with no timezone, so only show a countdown when the value ends in Z or an offset.
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 |
|---|---|---|
| bank_transfer_instructions | Bank name, account number, account name, the exact amount, an optional narration and an expiry. | Show them to the customer and ask for exactly that amount. Do not ask them to enter anything back. |
The flow
- 01Create.
POST /v1/collectionswithflow: "direct"andchannel: "bank_transfer". You getrequires_actionandnextAction.bankTransfer. - 02Show the account. Display the bank, account number and amount, with a copy button for the number and a countdown to
expiresAt. - 03The customer pays. They send the money from their own banking app. Nothing happens in your page.
- 04Tunnel checks. Tunnel asks the provider about the payment every few seconds while it is new, then less often. You can also call verify yourself.
- 05You are told. Your webhook receives
transaction.successfulortransaction.failedonce, when the payment reaches a final status. Release goods only onsuccessful.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | The account is open and waiting for the transfer. |
| successful | The full amount arrived. Final. |
| failed | The payment ended without being paid in full, for example an underpayment. Final. Look at error.code. |
Confirm the final status with verify or a webhook. Never treat the customer coming back to your site as proof of payment.
Underpayment
If the customer sends less than the amount you asked for, the provider may still call the transfer "successful". Tunnel does not. It records the payment as failed with failureCode: "amount_mismatch" and a reason such as Underpayment: NGN 10000 was received but 12000 was expected. The payer needs to pay the full amount.
- 01Do not release the goods. The collection is
failed. - 02The reason is in the collection response
error, in the dashboard, and in thetransaction.failedwebhook asfailureCodeandfailureReason. - 03The provider normally returns the shortfall to the customer. Fincra reverses it by default.
- 04To collect the full amount, create a new collection with a new reference.
Overpayment
If the customer sends more than the amount, Tunnel does not reject it. The collection becomes successful, and the amount on the collection and in the webhook stays the amount you asked for.
Tunnel does not return the extra
When the account expires
After expiresAt the provider stops accepting transfers to the account. Treat a collection that has not become successful by then as unpaid, and create a new one with a new reference. A transfer sent to an expired account is the provider’s to return, not Tunnel’s.
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. |
| Webhook | amount_mismatch | The customer sent less than was asked. | See underpayment below. |
Every error uses the shape on the errors page.