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
| Provider | Currencies | Notes |
|---|---|---|
| Paystack | NGN | Birthday step, then an OTP to confirm the owner, then an OTP to confirm the payment. |
| Flutterwave | NGN | Returns 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
| 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_account" | Required | Selects this method. |
| paymentMethod.bankAccount.accountNumber | string | Required | The customer’s 10 digit NUBAN. Tunnel does not store it. |
| paymentMethod.bankAccount.bankCode | string | Required | The bank’s code, for example 058. |
| paymentMethod.bankAccount.birthday | YYYY-MM-DD | Optional | Paystack only. Send it up front and the birthday step is skipped. |
| 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. |
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.
| type | What it carries | What you do |
|---|---|---|
| birthday | message. 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. |
| otp | message. 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. |
| redirect | redirectUrl. Flutterwave. | Send the customer to that page to finish the debit. No authorize call is needed. |
The flow
- 01Create.
POST /v1/collectionswith the account number and bank code. ReadnextAction.type. - 02Answer each step. For every
birthdayorotp, callPOST /v1/collections/{reference}/authorize. The response is the updated collection, with the next step if there is one. - 03Wait for the final status. After the last step the status is
pendinguntil the bank settles.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | A birthday, a code or a redirect is needed. |
| pending | All steps answered. The bank is settling the debit. |
| successful | The account was debited. Final. |
| failed | Wrong 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
| 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. |
| Authorize | 400 INVALID_OTP_OR_PIN | The code was wrong. | The collection keeps waiting. Let the customer try again. |
Every error uses the shape on the errors page.