Direct Debit

In A Nutshell
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:

  1. Create a mandate for the customer
  2. The customer approves the mandate and completes the activation step their bank requires
  3. Receive a webhook when the mandate is active
  4. 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:

  1. Create a mandate via charge: take a payment and create the mandate in one request.
  2. Initialize transaction: the customer approves the mandate while paying on Paystack Checkout.
  3. 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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/bank?available_for_direct_debit=true
3-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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/charge
3-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}
FieldRequiredNotes
emailYesCustomer email.
amountYesInteger, in kobo for NGN.
currencyNoDefaults to your integration's default currency.
referenceNoYour unique reference. Auto-generated if omitted.
direct_debit.account.numberYes10-digit account number.
direct_debit.account.bank_codeYesBank code, for example 057.
direct_debit.address.streetYesStreet.
direct_debit.address.cityYesCity.
direct_debit.address.stateYesState.
direct_debit.address.countryNoCountry.
direct_debit.phoneSometimesCustomer 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.statusWhat to do
pending_bank_transferPresent 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_urlRedirect 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:

Show Response
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "email": "[email protected]",
5 "amount": "10000",
6 "channels": ["bank"],
7 "metadata": {
8 "custom_filters": {
9 "recurring": true
10 }
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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/customer/authorization/initialize
3-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.statusWhat to do
pending_bank_transferPresent 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_urlRedirect 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.

1{
2 "status": true,
3 "message": "Authorization initialized",
4 "data": {
5 "reference": "54eyym8uf802ycx",
6 "mandate": {
7 "id": 3315722,
8 "status": "pending",
9 "isNew": true
10 },
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:

  1. Save data.reference, then redirect the customer to data.redirect_url straight away. Don’t store the link to send later; start a new setup instead.
  2. The customer approves or cancels the mandate on their bank’s page.
  3. We send the customer to your callback_url with trxref and reference added, for example https://example.com/direct-debit/complete?trxref=54eyym8uf802ycx&reference=54eyym8uf802ycx. The customer comes back to the same URL whether they approved or cancelled.
  4. Verify the mandate, or wait for the webhook, before you treat it as approved. The return to your callback_url doesn’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:

EventDescriptionWhat to do
direct_debit.authorization.createdWe 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.activeWe 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].

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",
23 "email": "[email protected]",
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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/customer/authorization/verify/:reference
3-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",
11 "email": "[email protected]"
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:

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.

Show Response
1#!/bin/sh
2curl https://api.paystack.co/customer/{id}/directdebit-activation-charge
3-H "Authorization: Bearer YOUR_SECRET_KEY"
4-H "Content-Type: application/json"
5-d '{
6 "authorization_id" : 1069309917
7 }'
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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/directdebit/activation-charge
3-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.

Show Response
1#!/bin/sh
2curl https://api.paystack.co/transaction/charge_authorization
3-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": null
32 },
33 "customer": {
34 "id": 180061682,
35 "first_name": "Ravi",
36 "last_name": "Demo",
37 "email": "[email protected]",
38 "customer_code": "CUS_24lze1c8i2zl76y",
39 "phone": "",
40 "metadata": null,
41 "risk_action": "default",
42 "international_format_phone": null
43 },
44 "plan": null,
45 "id": 1504238596
46 }
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:

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": null
35 },
36 "customer": {
37 "id": 180061682,
38 "first_name": "Ravi",
39 "last_name": "Demo",
40 "email": "[email protected]",
41 "customer_code": "CUS_24lze1c8i2zl76y",
42 "phone": "",
43 "metadata": null,
44 "risk_action": "default",
45 "international_format_phone": null
46 },
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": null
59 }
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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/transaction/verify/:reference
3-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": null
36 },
37 "customer": {
38 "id": 180061682,
39 "first_name": "Dami",
40 "last_name": "Olukini",
41 "email": "[email protected]",
42 "customer_code": "CUS_24lze1c8i2zl76y",
43 "phone": "",
44 "metadata": null,
45 "risk_action": "default",
46 "international_format_phone": null
47 },
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:

Show Response
1#!/bin/sh
2curl https://api.paystack.co/customer/authorization/deactivate
3-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}