Direct payments

Bank account debit

Debit a customer’s Nigerian bank account directly. The bank confirms the account owner first, so expect one or two extra steps before the money moves.
POST/v1/collections

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

Where it works

Providers and currencies
ProviderCurrenciesNotes
PaystackNGNBirthday step, then an OTP to confirm the owner, then an OTP to confirm the payment.
FlutterwaveNGNReturns a redirect. Send the customer to nextAction.redirectUrl.

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_account"RequiredSelects this method.
paymentMethod.bankAccount.accountNumberstringRequiredThe customer’s 10 digit NUBAN. Tunnel does not store it.
paymentMethod.bankAccount.bankCodestringRequiredThe bank’s code, for example 058.
paymentMethod.bankAccount.birthdayYYYY-MM-DDOptionalPaystack only. Send it up front and the birthday step is skipped.
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_1004",
  "flow": "direct",
  "amount": 20000,
  "currency": "NGN",
  "channel": "bank_account",
  "customer": { "email": "ada@example.com" },
  "paymentMethod": {
    "bankAccount": { "accountNumber": "0123456789", "bankCode": "058" }
  }
}
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_1004",
    "flow": "direct",
    "amount": 20000,
    "currency": "NGN",
    "channel": "bank_account",
    "customer": { "email": "ada@example.com" },
    "paymentMethod": { "bankAccount": { "accountNumber": "0123456789", "bankCode": "058" } }
  }'

Response

HTTP 201, requires_action (Paystack asks for a birthday)
{
  "success": true,
  "data": {
    "transactionId": "txn_a41f9e02c7b3d658",
    "reference": "ord_1004",
    "provider": "paystack",
    "status": "requires_action",
    "amount": 20000,
    "currency": "NGN",
    "channel": "bank_account",
    "nextAction": {
      "type": "birthday",
      "message": "Enter the account owner’s date of birth"
    }
  }
}

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
birthdaymessage. Paystack only, and only when you did not send a birthday.Ask for the account owner’s date of birth and send { "type": "birthday", "birthday": "1990-01-01" } to the authorize endpoint.
otpmessage. Asked twice on Paystack: once to confirm the account owner, once to confirm the payment.Collect the code the bank sent and send { "type": "otp", "otp": "482913" } to the authorize endpoint. Repeat when it asks again.
redirectredirectUrl. Flutterwave.Send the customer to that page to finish the debit. No authorize call is needed.

The flow

  1. 01Create. POST /v1/collections with the account number and bank code. Read nextAction.type.
  2. 02Answer each step. For every birthday or otp, call POST /v1/collections/{reference}/authorize. The response is the updated collection, with the next step if there is one.
  3. 03Wait for the final status. After the last step the status is pending until the bank settles.

Statuses to expect

Statuses
statusMeaning
requires_actionA birthday, a code or a redirect is needed.
pendingAll steps answered. The bank is settling the debit.
successfulThe account was debited. Final.
failedWrong details, a declined debit or an owner mismatch. Final.

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

The authorize endpoint

POST/v1/collections/{reference}/authorize

Submit the birthday or code a nextAction asks for

Body
{ "type": "birthday", "birthday": "1990-01-01" }
// or
{ "type": "otp", "otp": "482913" }

Send the type that matches the current nextAction.type.

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.
Authorize400 INVALID_OTP_OR_PINThe code was wrong.The collection keeps waiting. Let the customer try again.

Every error uses the shape on the errors page.