Direct payments

Bank transfer

Tunnel returns a one-time account number. Your customer sends the exact amount to it from their banking app, and Tunnel tells you when the money arrives.
POST/v1/collections

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

Where it works

Providers and currencies
ProviderCurrenciesNotes
PaystackNGNPay with Transfer must be enabled on your Paystack account first.
FlutterwaveNGN, GHSNothing extra to send.
FincraNGN, GHS, KES, UGX, ZARDirect 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

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"bank_transfer"RequiredSelects this method.
paymentMethod.bankTransfer.expiresInMinutesnumberOptionalHow long the account stays open, from 15 to 480 minutes. Paystack only; other providers use their own window.
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_1001",
  "flow": "direct",
  "amount": 12000,
  "currency": "NGN",
  "channel": "bank_transfer",
  "customer": { "email": "ada@example.com", "name": "Ada Obi" },
  "paymentMethod": { "bankTransfer": { "expiresInMinutes": 30 } }
}
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_1001",
    "flow": "direct",
    "amount": 12000,
    "currency": "NGN",
    "channel": "bank_transfer",
    "customer": { "email": "ada@example.com" }
  }'

Response

HTTP 201, requires_action
{
  "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.

Next action types
typeWhat it carriesWhat you do
bank_transfer_instructionsBank 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

  1. 01Create. POST /v1/collections with flow: "direct" and channel: "bank_transfer". You get requires_action and nextAction.bankTransfer.
  2. 02Show the account. Display the bank, account number and amount, with a copy button for the number and a countdown to expiresAt.
  3. 03The customer pays. They send the money from their own banking app. Nothing happens in your page.
  4. 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.
  5. 05You are told. Your webhook receives transaction.successful or transaction.failed once, when the payment reaches a final status. Release goods only on successful.

Statuses to expect

Statuses
statusMeaning
requires_actionThe account is open and waiting for the transfer.
successfulThe full amount arrived. Final.
failedThe 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.

  1. 01Do not release the goods. The collection is failed.
  2. 02The reason is in the collection response error, in the dashboard, and in the transaction.failed webhook as failureCode and failureReason.
  3. 03The provider normally returns the shortfall to the customer. Fincra reverses it by default.
  4. 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

Tunnel does not track or refund the surplus. If you need to pay it back, do it from your provider’s dashboard, and check the provider’s record of the transfer for the amount that actually arrived.

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

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.
Webhookamount_mismatchThe customer sent less than was asked.See underpayment below.

Every error uses the shape on the errors page.