Direct Debit
In a nutshell
A business asks a customer to approve a mandate on their bank account. Once the customer approves it, the business can debit the account on a recurring basis.
Direct Debit is a payment channel that lets a business debit a customer’s bank account once the customer has given consent. The business gets that consent by creating a mandate: a request the customer approves once, which lets the business charge their account whenever a payment is due.
Feature availability
This feature is available to businesses in Nigeria only. To enable it on your integration, email [email protected].
How it works
Every Direct Debit integration follows the same steps:
- Create a mandate for the customer
- The customer approves the mandate and completes the activation step their bank requires
- Receive a webhook when the mandate is active
- Charge the customer’s account whenever a payment is due
Each bank sets its own activation step. Some banks ask the customer to make a one-time transfer, and others ask the customer
to confirm the mandate with the bank. Whichever step the bank uses, wait for the direct_debit.authorization.active
event before you charge the customer.
You can create a mandate in three ways:
- Create a mandate via charge: take a payment and create the mandate in one request.
- Initialize transaction: the customer approves the mandate while paying on Paystack Checkout.
- Set up a mandate directly: create a mandate without taking a payment, on our hosted page or in your own UI.
Whichever way you choose, listen for the events in Verify a mandate to know when the mandate is active.
Supported banks
Check that the customer’s bank supports Direct Debit before you create a mandate. To get the list of supported banks, make a GET request to the List BanksAPI endpoint with the available_for_direct_debit query parameter set to true:
1#!/bin/sh2curl https://api.paystack.co/bank?available_for_direct_debit=true3-H "Authorization: Bearer YOUR_SECRET_KEY"4-X GET
1
Note
Check the list periodically for new partner banks. We check the bank code before creating the authorization. If the bank isn’t supported, or isn’t enabled for your business, the request fails with an error such as Bank not supported for direct debit or Direct debit charge not enabled for bank.
Create a mandate via charge
Take a payment and set up the mandate in one flow. Make a POST request to the Create ChargeAPI endpoint with a direct_debit object containing the customer’s account and address:
1#!/bin/sh2curl https://api.paystack.co/charge3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "email": "[email protected]",7 "amount": "1000000",8 "currency": "NGN",9 "direct_debit": {10 "account": { "number": "0123456789", "bank_code": "057" },11 "address": { "street": "126 Joel Ogunnaike", "city": "Ikeja", "state": "Lagos", "country": "NG" },12 "phone": "+2348012345678"13 }14 }'15-X POST
1{2 "status": true,3 "message": "Charge attempted",4 "data": {5 "reference": "dd-charge-8f3a1c",6 "status": "pending_bank_transfer",7 "amount": 1000000,8 "account_number": "1234567890",9 "bank_name": "Test Bank"10 }11}
| Field | Required | Notes |
|---|---|---|
email | Yes | Customer email. |
amount | Yes | Integer, in kobo for NGN. |
currency | No | Defaults to your integration's default currency. |
reference | No | Your unique reference. Auto-generated if omitted. |
direct_debit.account.number | Yes | 10-digit account number. |
direct_debit.account.bank_code | Yes | Bank code, for example 057. |
direct_debit.address.street | Yes | Street. |
direct_debit.address.city | Yes | City. |
direct_debit.address.state | Yes | State. |
direct_debit.address.country | No | Country. |
direct_debit.phone | Sometimes | Customer phone in international format, for example +2348012345678. Required if we don’t already have a phone for this customer. |
The next step depends on the customer’s bank. Check data.status in the response:
data.status | What to do |
|---|---|
pending_bank_transfer | Present account_number, bank_name and amount to the customer to complete the one-time transfer. Once we receive it, the bank activates the mandate, which can take up to 24 hours. |
open_url | Redirect the customer to data.redirect_url to approve the mandate on their bank’s page. Once they approve, we take the payment and activate the mandate. |
Always check data.status. Don’t decide from the bank code, because the step a bank uses can change.
For banks that return open_url, we send the customer to the callback URL set on your dashboard after they approve or cancel. This endpoint doesn’t take a callback_url, so set one on your dashboard. If your dashboard has no callback URL, the request fails with a callback_url is required for this bank error.
When the mandate is active, we send the direct_debit.authorization.active event to your webhook URL. You can also verify the mandate to check its status.
1{2 "status": true,3 "message": "Charge attempted",4 "data": {5 "reference": "7PVGX8MEk85tgeEpVDtD",6 "status": "open_url",7 "redirect_url": "https://redirecturlsample.com"8 }9}
Initialize transaction
To set up a mandate while the customer pays on Paystack Checkout, pass the bank channel with a custom filter to
the Initialize TransactionAPI endpoint:
1curl https://api.paystack.co/transaction/initialize2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"5 "amount": "10000",6 "channels": ["bank"],7 "metadata": {8 "custom_filters": {9 "recurring": true10 }11 }12 }'13-X POST
1{2 "status": true,3 "message": "Authorization URL created",4 "data": {5 "authorization_url": "https://checkout.paystack.com/zcwh3axoir37x7q",6 "access_code": "zcwh3axoir37x7q",7 "reference": "gz8nyit2zd"8 }9}
While completing the transaction, the customer gives us permission to create a mandate that you can use for
later payments. We only create a mandate if the customer’s bank is one of the supported banks for Direct Debit. When the mandate is active,
we send the direct_debit.authorization.active event to your webhook URL. You can also verify the mandate to check its status.
Set up a mandate directly
To create a mandate without taking a payment, issue an authorization request to the customer by using the Initialize AuthorizationAPI endpoint:
1#!/bin/sh2curl https://api.paystack.co/customer/authorization/initialize3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "email": "[email protected]",7 "channel": "direct_debit",8 "callback_url": "http://test.url.com"9 }'10-X POST
1{2 "status": true,3 "message": "Authorization initialized",4 "data": {5 "redirect_url": "https://link.paystack.co/82t4mp5b5mfn51h",6 "access_code": "82t4mp5b5mfn51h",7 "reference": "dfbzfotsrbv4n5s82t4mp5b5mfn51h"8 }9}
The response contains a redirect_url. Redirect the customer to it to approve the mandate. The page guides the customer through
the activation step their bank requires. If you provided a callback_url in your request, we send the customer to that page after they approve the mandate.
For a better UI experience, you can pre-fill some of the customer’s information by adding the account and address objects in your request:
1curl https://api.paystack.co/customer/authorization/initialize \2-H "Authorization: Bearer YOUR_SECRET_KEY" \3-H "Content-Type: application/json" \4-d '{5 "channel": "direct_debit",6 "email": "[email protected]",7 "callback_url": "http://test.url.com",8 "account": {9 "number": "0128034955",10 "bank_code": "058"11 },12 "address": {13 "state": "Lagos",14 "city": "Akoka",15 "street": "17 Beckley Avenue"16 }17 }' \18-X POST
While both the account and address objects are optional, when used, all params in both objects are compulsory. The bank_code in the account object
is the customer’s bank.
You can also control which mandate setup experience the customer gets by passing use_hosted_url in the same request. Set it to false for the non-hosted flow, where you drive the setup steps yourself. Leave it as true, the default, for the hosted flow, where we show the setup on the redirect_url.
For the non-hosted flow, the account and address objects are required. Some banks also need a callback_url. See Banks that return open_url below.
1curl https://api.paystack.co/customer/authorization/initialize \2-H "Authorization: Bearer YOUR_SECRET_KEY" \3-H "Content-Type: application/json" \4-d '{5 "channel": "direct_debit",6 "email": "[email protected]",7 "use_hosted_url": false,8 "callback_url": "https://example.com/direct-debit/complete",9 "account": {10 "number": "0128034955",11 "bank_code": "058"12 },13 "address": {14 "state": "Lagos",15 "city": "Akoka",16 "street": "17 Beckley Avenue"17 }18 }' \19-X POST
For the non-hosted flow, the next step depends on the customer’s bank. Check data.status in the response:
data.status | What to do |
|---|---|
pending_bank_transfer | Present data.transferDetails to the customer to complete the one-time transfer. Once we receive it, the bank activates the mandate, which can take up to 24 hours. |
open_url | Redirect the customer to data.redirect_url to approve the mandate on their bank’s page. See Banks that return open_url below. |
Always check data.status. Don’t decide from the bank code, because the step a bank uses can change.
- Transfer
- Approve on bank’s page
1{2 "status": true,3 "message": "Authorization initialized",4 "data": {5 "reference": "54eyym8uf802ycx",6 "mandate": {7 "id": 3315722,8 "status": "pending",9 "isNew": true10 },11 "transferDetails": {12 "amount": "50.00",13 "account_number": "9880218357",14 "account_name": "NIBSS DIRECT DEBIT",15 "bank_name": "Paystack-Titan"16 },17 "status": "pending_bank_transfer"18 }19}
When the mandate is active, we send the direct_debit.authorization.active event to your webhook URL. You can also verify the mandate to check its status.
Banks that return open_url
When data.status is open_url:
- Save
data.reference, then redirect the customer todata.redirect_urlstraight away. Don’t store the link to send later; start a new setup instead. - The customer approves or cancels the mandate on their bank’s page.
- We send the customer to your
callback_urlwithtrxrefandreferenceadded, for examplehttps://example.com/direct-debit/complete?trxref=54eyym8uf802ycx&reference=54eyym8uf802ycx. The customer comes back to the same URL whether they approved or cancelled. - Verify the mandate, or wait for the webhook, before you treat it as approved. The return to your
callback_urldoesn’t tell you the result. Verifying checks with the bank, so you get the result even if the webhook is delayed.
A callback_url is required for these banks. If you don’t send one, we use the callback URL on your dashboard. If neither is set, the request fails with a callback_url is required for this bank error.
Verify a mandate
We send the following webhook events to your webhook URL to communicate the status of the customer's authorization:
| Event | Description | What to do |
|---|---|---|
direct_debit.authorization.created | We send this when the customer approves your mandate. It doesn't mean that you can charge the customer's account yet. | Save the authorization_code against the customer. |
direct_debit.authorization.active | We send this when the mandate is active. | Start charging the customer's account. |
For banks that return open_url, the mandate is ready to charge as soon as the customer approves it, so direct_debit.authorization.created and direct_debit.authorization.active arrive together. We don’t send an event when the customer cancels or the setup fails. Verify the mandate to check.
Mandate activation
For banks that use the one-time transfer, mandate activation can take up to 24 hours, or longer for some banks. If a mandate stays pending beyond that, you can try triggering an activation charge again, or reach out to [email protected].
- Authorization Created
- Authorization Active
1{2 "event": "direct_debit.authorization.created",3 "status": true,4 "message": "Authorization retrieved successfully",5 "data": {6 "authorization_code": "AUTH_JV4T9Wawdj",7 "active": false,8 "last4": "1234",9 "channel": "direct_debit",10 "card_type": "mandate",11 "bank": "Guaranty Trust Bank",12 "exp_month": 1,13 "exp_year": 2034,14 "country_code": "NG",15 "brand": "Guaranty Trust Bank",16 "reusable": true,17 "signature": "SIG_u8SqR3E6ty2koQ9i5IrI",18 "account_name": "Ravi Demo",19 "customer": {20 "first_name": "Ravi",21 "last_name": "Demo",22 "code": "CUS_g0a2pm2ilthhh62",24 "phone": "",25 "metadata": null,26 "risk_action": "default"27 }28 }29}
If you miss a webhook, verify the mandate by making a request to the Verify AuthorizationAPI endpoint with the reference from the initialization request:
1#!/bin/sh2curl https://api.paystack.co/customer/authorization/verify/:reference3-H "Authorization: Bearer YOUR_SECRET_KEY"4-X GET
1{2 "status": true,3 "message": "Authorization retrieved successfully",4 "data": {5 "authorization_code": "AUTH_JV4T9Wawdj",6 "channel": "direct_debit",7 "bank": "Guaranty Trust Bank",8 "active": true,9 "customer": {10 "code": "CUS_24lze1c8i2zl76y",12 }13 }14}
If the customer hasn’t approved the mandate yet, the response has data.status set to pending. If the setup failed, it’s failed. Treat the mandate as pending until you get the direct_debit.authorization.active event or the response contains the authorization:
- JSON
1{2 "status": true,3 "message": "Direct debit authorization retrieved",4 "data": {5 "reference": "54eyym8uf802ycx",6 "status": "pending"7 }8}
If the setup failed, start a new one with a new reference. A failed reference can’t be used again.
Rate limiting
Calls to the Verify Authorization endpoint are subject to our rate limiting rules.
Retrying a pending authorization
Sometimes a mandate stays in a pending status. For banks that use the one-time transfer, you can trigger an activation charge for the customer. This doesn’t apply to banks that return open_url, because those mandates are active once the customer approves them.
1#!/bin/sh2curl https://api.paystack.co/customer/{id}/directdebit-activation-charge3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "authorization_id" : 10693099177 }'8-X PUT
1{2 "status": true,3 "message": "Mandate is queued for retry"4}
For multiple customers, you can use the Direct Debit Activation ChargeAPI endpoint as shown below:
1#!/bin/sh2curl https://api.paystack.co/directdebit/activation-charge3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "customer_ids": [28958104, 983697220]7 }'8-X PUT
1{2 "status": true,3 "message": "Mandate is queued for retry"4}
Customer's account validation
This request debits NGN 50 from the customer’s account so we can confirm that we can debit it. We refund the NGN 50 once we complete the check.
When the mandate becomes active, we send the direct_debit.authorization.active event to your webhook URL.
Recurring charge
Once a mandate is active, use its authorization_code to debit the customer’s account on a recurring basis. You can debit the customer’s account by passing the authorization_code with the matching email to the charge authorizationAPI endpoint.
1#!/bin/sh2curl https://api.paystack.co/transaction/charge_authorization3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "authorization_code" : "AUTH_JV4T9Wawdj",7 "email": "[email protected]",8 "amount": "10000",9 "currency": "NGN"10 }'11-X POST
1{2 "status": true,3 "message": "Charge attempted",4 "data": {5 "amount": 10000,6 "currency": "NGN",7 "transaction_date": "2023-10-24T12:32:24.000Z",8 "status": "processing",9 "reference": "nl3eljdd6qgbrho",10 "domain": "live",11 "metadata": "",12 "gateway_response": "Transaction in progress",13 "message": null,14 "channel": "direct_debit",15 "ip_address": null,16 "log": null,17 "fees": null,18 "authorization": {19 "authorization_code": "AUTH_JV4T9Wawdj",20 "bin": null,21 "last4": null,22 "exp_month": null,23 "exp_year": null,24 "channel": "direct_debit",25 "card_type": null,26 "bank": "Guaranty Trust Bank",27 "country_code": "NG",28 "brand": null,29 "reusable": true,30 "signature": null,31 "account_name": null32 },33 "customer": {34 "id": 180061682,35 "first_name": "Ravi",36 "last_name": "Demo",38 "customer_code": "CUS_24lze1c8i2zl76y",39 "phone": "",40 "metadata": null,41 "risk_action": "default",42 "international_format_phone": null43 },44 "plan": null,45 "id": 150423859646 }47}
By default, we return a status of processing while we charge the customer’s account. When the charge succeeds, we send the charge.success event to your webhook URL. Only give value to the customer after you receive it, or after you verify the charge with the data.reference from the response.
You can also use the authorization for subscriptions via the Create SubscriptionAPI endpoint.
In cases where the customer has other authorizations, ensure you send the authorization_code for this mandate, otherwise Paystack picks the most recent authorization. Check out our Subscription docs to learn more.
Verify a charge
When the charge succeeds, we send the charge.success event to your webhook URL:
- JSON
1{2 "event": "charge.success",3 "data": {4 "id": 1504238596,5 "domain": "live",6 "status": "success",7 "reference": "nl3eljdd6qgbrho",8 "amount": 10000,9 "message": "madePayment",10 "gateway_response": "Payment successful",11 "paid_at": "2023-10-24T12:32:30.000Z",12 "created_at": "2023-10-24T12:32:24.000Z",13 "channel": "direct_debit",14 "currency": "NGN",15 "ip_address": null,16 "metadata": "",17 "fees_breakdown": null,18 "log": null,19 "fees": 0,20 "fees_split": null,21 "authorization": {22 "authorization_code": "AUTH_JV4T9Wawdj",23 "bin": null,24 "last4": null,25 "exp_month": null,26 "exp_year": null,27 "channel": "direct_debit",28 "card_type": null,29 "bank": "Guaranty Trust Bank",30 "country_code": "NG",31 "brand": null,32 "reusable": true,33 "signature": null,34 "account_name": null35 },36 "customer": {37 "id": 180061682,38 "first_name": "Ravi",39 "last_name": "Demo",41 "customer_code": "CUS_24lze1c8i2zl76y",42 "phone": "",43 "metadata": null,44 "risk_action": "default",45 "international_format_phone": null46 },47 "plan": {},48 "subaccount": {},49 "split": {},50 "order_id": null,51 "paidAt": "2023-10-24T12:32:30.000Z",52 "requested_amount": 10000,53 "pos_transaction_data": null,54 "source": {55 "type": "api",56 "source": "merchant_api",57 "entry_point": "charge",58 "identifier": null59 }60 }61}
If you miss the webhook, make a request to the Verify TransactionAPI endpoint using the reference from the response of your charge request:
1#!/bin/sh2curl https://api.paystack.co/transaction/verify/:reference3-H "Authorization: Bearer YOUR_SECRET_KEY"4-X GET
1{2 "status": true,3 "message": "Verification successful",4 "data": {5 "id": 1504238596,6 "domain": "live",7 "status": "success",8 "reference": "nl3eljdd6qgbrho",9 "receipt_number": null,10 "amount": 10000,11 "message": "madePayment",12 "gateway_response": "Payment successful",13 "paid_at": "2023-10-24T12:32:30.000Z",14 "created_at": "2023-10-24T12:32:24.000Z",15 "channel": "direct_debit",16 "currency": "NGN",17 "ip_address": null,18 "metadata": "",19 "log": null,20 "fees": null,21 "fees_split": null,22 "authorization": {23 "authorization_code": "AUTH_JV4T9Wawdj",24 "bin": null,25 "last4": null,26 "exp_month": null,27 "exp_year": null,28 "channel": "direct_debit",29 "card_type": null,30 "bank": "Guaranty Trust Bank",31 "country_code": "NG",32 "brand": null,33 "reusable": true,34 "signature": null,35 "account_name": null36 },37 "customer": {38 "id": 180061682,39 "first_name": "Dami",40 "last_name": "Olukini",42 "customer_code": "CUS_24lze1c8i2zl76y",43 "phone": "",44 "metadata": null,45 "risk_action": "default",46 "international_format_phone": null47 },48 "plan": null,49 "split": {},50 "order_id": null,51 "paidAt": "2023-10-24T12:32:30.000Z",52 "createdAt": "2023-10-24T12:32:24.000Z",53 "requested_amount": 10000,54 "pos_transaction_data": null,55 "source": null,56 "fees_breakdown": null,57 "transaction_date": "2023-10-24T12:32:24.000Z",58 "plan_object": {},59 "subaccount": {}60 }61}
Deactivate authorization
You might need to deactivate an authorization either after the completion of a transaction or based on a request from your customer. To do this, make a POST request to the Deactivate AuthorizationAPI:
1#!/bin/sh2curl https://api.paystack.co/customer/authorization/deactivate3-H "Authorization: Bearer YOUR_SECRET_KEY"4-H "Content-Type: application/json"5-d '{6 "authorization_code": "AUTH_xxxIjkZVj5"7 }'8-X POST
1{2 "status": true,3 "message": "Authorization has been deactivated"4}