# Direct Debit Authorize recurring debits on a customer's bank account so you can pull funds whenever you need to — without asking them to log in or approve each charge. *** Cards expire. Customers forget to pay. Checkout links go ignored. If you're running a lending business, a subscription platform, or anything that needs to collect money from the same person on a regular basis, you need a payment method that doesn't depend on the customer showing up every time. That's what direct debit solves. Instead of charging a card or sending a payment link, you get a one-time authorization to debit the customer's bank account directly. Once the authorization is active, you can pull funds from their account on demand — for loan repayments, subscription renewals, or any recurring obligation — without the customer lifting a finger. On Tendar, the Direct Debit API lets you create a debit authorization, have the customer approve it through a secure bank consent flow, and then charge the authorized account whenever you need to. The entire flow is backed by Paystack and works with all major Nigerian banks. Think of it as giving your application a standing instruction on the customer's bank account: "I'm allowed to debit this account for up to this amount, whenever I need to." ## Before you begin To use the Direct Debit API, you need: 1. **An active Tendar account** with a valid API key. 2. **A registered user** — direct debits are tied to users. The user must already exist in your company's user directory on Tendar. 3. **A payment service configured** — your company needs at least one active payment provider (currently Paystack) with valid API keys set up on the Tendar dashboard. If you haven't configured one, Tendar defaults to Paystack. 4. **An active subscription** — all direct debit endpoints require that your company has a current subscription. 5. **The customer's bank account details** — you'll need the account number and bank code for the bank account the customer wants to authorize. ## How direct debit works The direct debit flow has three stages: **create**, **authorize**, and **verify**. Each stage plays a specific role, and understanding them will help you build a smooth experience for your customers. {% stepper %} {% step %} ### Create a direct debit To set up a direct debit, send a `POST` request with the customer's `user_id`, their bank `account` details, a physical `address`, and a `checkout` object containing redirect URLs. ```http POST /direct-debit/create ``` ```json { "user_id": "usr-cheltgfnqt", "currency": "NGN", "checkout": { "success_url": "https://yourapp.com/direct-debit/success", "cancel_url": "https://yourapp.com/direct-debit/cancel" }, "account": { "account_number": "0337780258", "bank_code": "058" }, "address": { "state": "Lagos", "city": "Ikosi", "street": "26, Mabinuori Street" }, "payment_service": "" } ``` | Field | Type | Required | Description | | ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | Yes | The Tendar user ID of the customer whose bank account you want to authorize. | | `currency` | string | Yes | The currency for the authorization. Currently supports `NGN`. | | `checkout.success_url` | string | Yes | Where to redirect the customer after they approve the debit authorization on their bank's page. | | `checkout.cancel_url` | string | No | Where to redirect the customer if they cancel the consent flow. | | `account.account_number` | string | Yes | The customer's bank account number. | | `account.bank_code` | string | Yes | The bank code identifying the customer's bank (e.g., `058` for GTBank, `044` for Access Bank). Use the [List Banks](#list-supported-banks) endpoint to get valid codes. | | `address.state` | string | Yes | The customer's state of residence. | | `address.city` | string | Yes | The customer's city. | | `address.street` | string | Yes | The customer's street address. | | `payment_service` | string | No | Which payment provider to use. Leave empty to use your company's default (currently Paystack). | When the request succeeds, Tendar does the following behind the scenes: 1. **Validates the user** — confirms the user exists under your company and retrieves their email address. 2. **Resolves the payment provider** — determines which payment service to use based on your request or your company's default configuration. 3. **Initiates the authorization** — sends the bank account details and the customer's address to the payment provider, which sets up a debit mandate on the bank account. 4. **Returns a checkout URL** — the response includes a `checkout.url` where the customer must go to approve the authorization. Here's what the response looks like: ```json { "data": { "created_at": "2024-07-03T20:24:00.071Z", "updated_at": "2024-07-03T20:24:00.071Z", "id": "6685b3603025edcdd17c19b6", "user": "660f7665740ffdf6498d05f5", "user_id": "usr-cheltgfnqt", "default": false, "payment_service": "paystack", "currency": "NGN", "status": "pending_consent", "account": { "last_4_digits": "", "card_type": "", "bank": "", "exp_month": "", "exp_year": "", "country_code": "", "email": "john@example.com", "account_name": "", "account_number": "0337780258", "bank_code": "058" }, "signature": "", "service_ref": "k61x9dic2bh80hd", "checkout": { "success_url": "https://yourapp.com/direct-debit/success", "cancel_url": "https://yourapp.com/direct-debit/cancel", "url": "https://link.paystack.com/ouk15knn4rgk8ie" }, "message": "", "address": { "state": "Lagos", "city": "Ikosi", "street": "26, Mabinuori Street" } }, "error": false, "message": "Direct debit created successfully" } ``` Notice the `status` is `pending_consent`. The direct debit exists, but it's not active yet — the customer still needs to approve it. The `account` details are mostly empty because the bank hasn't confirmed the authorization yet. **What to do next:** Redirect your customer to the `checkout.url`. This takes them to a secure page (hosted by the payment provider) where they'll review the debit mandate and approve it with their bank. {% endstep %} {% step %} ### Customer approves the authorization This step happens entirely outside your application. The customer is taken to a consent page — typically hosted by Paystack and the customer's bank — where they review the details of the debit mandate and give their approval. The consent flow usually involves: 1. **Reviewing the mandate details** — the customer sees which account will be debited, the name of the business requesting authorization, and the terms of the mandate. 2. **Authenticating with their bank** — depending on the bank, the customer may need to enter an OTP sent to their phone, answer security questions, or approve the request through their bank's mobile app. 3. **Confirming the authorization** — once authenticated, the customer approves the mandate. After the customer completes the consent flow: 1. They are redirected to your `success_url` (or `cancel_url` if they declined). 2. The payment provider sends a webhook to Tendar notifying it that the authorization is complete. You don't need to call any API during this step. Just make sure your `success_url` shows the customer a confirmation message (e.g., "Bank account authorized successfully" or "Processing your authorization..."). {% hint style="info" %} If the customer starts the authorization flow but never completes it, the direct debit record sits in a `pending_consent` state. Tendar automatically cleans up these orphaned authorizations — any direct debit that remains unverified after 24 hours is deleted. You don't need to handle this yourself. {% endhint %} {% endstep %} {% step %} ### Tendar verifies and activates the direct debit When Tendar receives the webhook from the payment provider, it automatically: 1. **Verifies the authorization** — confirms that the bank consent was successfully completed and the mandate is active. 2. **Extracts the account details** — pulls the last 4 digits of the account number, the bank name, the account holder's name, expiry information, and country code from the provider's response. 3. **Stores the token** — saves a reusable token that allows future debits against this bank account without the customer re-approving. 4. **Checks for duplicates** — if the customer already has an active direct debit with the same signature (i.e., the same bank account and mandate), the new one is marked as `cancelled` with the message "direct debit already exists." This prevents duplicate authorizations. 5. **Sets the default** — if this is the customer's first active direct debit, it is automatically set as the default. 6. **Sends a webhook** — fires a `direct-debit.active` or `direct-debit.cancelled` event to your company's registered webhook URL, depending on the outcome. After verification, the direct debit object looks like this: ```json { "id": "6685be5f5ef3e0931e082ad6", "user": "6685bb34af274480e2251d85", "user_id": "usr-hnlfkizfoc", "default": true, "payment_service": "paystack", "currency": "NGN", "status": "active", "account": { "last_4_digits": "0258", "card_type": "mandate", "bank": "Guaranty Trust Bank", "exp_month": "7", "exp_year": "2034", "country_code": "NG", "email": "john@example.com", "account_name": "JOHN DOE" }, "signature": "SIG_eSRls0xZ252VL2575Uxb", "service_ref": "itu3semg6d10m0c", "message": "" } ``` The direct debit is now `active` and ready to be charged. {% endstep %} {% endstepper %} ## How direct debit differs from card tokenization If you've already read the [Card Tokenization](https://docs.tendar.co/documentation/recollection/broken-reference) guide, you might wonder why you'd use direct debit instead of — or in addition to — a saved card. Here's the key difference: | | Card | Direct Debit | | ------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | | **What's authorized** | A credit or debit card | A bank account | | **How it's authorized** | Customer enters card details on a checkout page | Customer approves a mandate through their bank's consent flow | | **Expiry** | Cards expire (and customers may not update them) | Bank accounts don't expire — the mandate is valid for years (typically 10) | | **Bank account details needed** | No | Yes — you need the account number and bank code upfront | | **Address required** | No | Yes — the customer's physical address is required for the mandate | | **Best for** | One-off charges, customers with cards | Recurring collections, customers who prefer bank-account-based payments | In practice, many businesses set up both a card and a direct debit for each customer. The card serves as the primary payment method, and the direct debit acts as a fallback — if the card charge fails (expired card, insufficient funds on the card), you can fall back to debiting the bank account. ## List supported banks Not every bank supports direct debit mandates. Before creating a direct debit, you may want to show your customer a list of supported banks so they can confirm their bank is eligible. ```http GET /direct-debit/bank/list ``` You can filter by country using the `country` query parameter (defaults to `nigeria`): ```http GET /direct-debit/bank/list?country=nigeria ``` The response returns an array of banks with their names and codes: ```json { "data": [ { "name": "Access Bank", "code": "044" }, { "name": "First Bank of Nigeria", "code": "011" }, { "name": "Guaranty Trust Bank", "code": "058" }, { "name": "United Bank For Africa", "code": "033" }, { "name": "Zenith Bank", "code": "057" } ], "error": false, "message": "Banks fetched successfully" } ``` {% hint style="info" %} Use the `code` value as the `bank_code` when creating a direct debit. Display the `name` to your customer in a dropdown or selection list so they can pick their bank. {% endhint %} The full list includes over 20 major Nigerian banks — Access Bank, Ecobank, FCMB, Fidelity Bank, First Bank, GTBank, Heritage Bank, Jaiz Bank, Keystone Bank, Polaris Bank, PremiumTrust Bank, Providus Bank, Stanbic IBTC, Standard Chartered, Sterling Bank, Suntrust Bank, Titan Bank, UBA, Union Bank, Unity Bank, Wema Bank, Zenith Bank, Globus Bank, and Citibank Nigeria. ## Managing direct debits Once a direct debit is created and activated, you have full control over listing, fetching, setting defaults, and deleting them. ### List a customer's direct debits Retrieve all direct debits belonging to a specific user. The response excludes sensitive fields like the token, checkout details, and address. ```http GET /direct-debit/list/:user_id ``` You can filter results by passing query parameters: | Parameter | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------ | | `status` | string | Filter by status. Use `status=active` to get only active authorizations. | | `sort-created_at` | string | Sort by creation date. Use `asc` or `desc`. | Example response: ```json { "data": [ { "created_at": "2024-07-03T21:10:55.238Z", "updated_at": "2024-07-03T21:12:20.789Z", "id": "6685be5f5ef3e0931e082ad6", "user": "6685bb34af274480e2251d85", "user_id": "usr-hnlfkizfoc", "default": false, "payment_service": "paystack", "currency": "NGN", "status": "active", "account": { "last_4_digits": "5157", "card_type": "mandate", "bank": "Zenith Bank", "exp_month": "7", "exp_year": "2034", "country_code": "NG", "email": "john@example.com", "account_name": "JOHN DOE" }, "signature": "SIG_eSRls0xZ252VL2575Uxb", "service_ref": "jlisfayntsfadcg", "message": "" }, { "created_at": "2024-07-03T20:57:34.872Z", "updated_at": "2024-07-03T20:58:21.259Z", "id": "6685bb3e98173a7a55a87680", "user": "6685bb34af274480e2251d85", "user_id": "usr-hnlfkizfoc", "default": true, "payment_service": "paystack", "currency": "NGN", "status": "active", "account": { "last_4_digits": "0258", "card_type": "mandate", "bank": "Guaranty Trust Bank", "exp_month": "7", "exp_year": "2034", "country_code": "NG", "email": "john@example.com", "account_name": "JOHN DOE" }, "signature": "", "service_ref": "itu3semg6d10m0c", "message": "" } ], "error": false, "message": "Direct debits fetched successfully" } ``` ### Fetch a single direct debit Retrieve a specific direct debit by its ID. ```http GET /direct-debit/fetch/:id ``` The response includes the full direct debit object (minus the token, checkout, and address fields): ```json { "data": { "created_at": "2024-07-03T21:10:55.238Z", "updated_at": "2024-07-03T21:12:20.789Z", "id": "6685be5f5ef3e0931e082ad6", "user": "6685bb34af274480e2251d85", "user_id": "usr-hnlfkizfoc", "default": false, "payment_service": "paystack", "currency": "NGN", "status": "active", "account": { "last_4_digits": "5157", "card_type": "mandate", "bank": "Zenith Bank", "exp_month": "7", "exp_year": "2034", "country_code": "NG", "email": "john@example.com", "account_name": "JOHN DOE" }, "signature": "SIG_eSRls0xZ252VL2575Uxb", "service_ref": "jlisfayntsfadcg", "message": "" }, "error": false, "message": "Direct debit fetched successfully" } ``` ### Set a default direct debit When a customer has multiple active direct debits, you can designate one as the default. The default direct debit is the one that gets charged when you don't specify a direct debit ID in a charge or recollection request. ```http PUT /direct-debit/default/set/:id ``` Only active direct debits can be set as default. If the authorization hasn't been verified yet or has been cancelled, the request will fail with a `400` error. When you set a new default, the previous default is automatically unset — there's always exactly one default direct debit per customer. ### Delete a direct debit Remove a direct debit authorization from a customer's account. This deletes the record from Tendar and revokes the mandate with the payment provider, so the bank account can no longer be debited. ```http DELETE /direct-debit/delete/:id ``` By default, you cannot delete a customer's default direct debit — this prevents accidentally removing the authorization your automated charges depend on. If you really need to delete the default, pass the `delete_default=true` query parameter: ```http DELETE /direct-debit/delete/:id?delete_default=true ``` When a direct debit is deleted, Tendar also sends a deauthorization request to the payment provider in the background, revoking the mandate token so it can no longer be used for debits. ## Charging a direct debit Once a direct debit is active, you can debit the customer's bank account. There are two ways to do this: ### Through a recollection The most common use case. When recording a loan repayment, set `payment_channel` to `"direct_debit"` and optionally pass the direct debit ID. Tendar debits the bank account and applies the repayment to the loan in a single step. ```json POST /recollection/create { "loan": "6685d6600defdf0d7eea6699", "amount": 3500, "with_provider": true, "payment_channel": "direct_debit", "direct_debit": "6685be5f5ef3e0931e082ad6", "callback_url": "https://yourapp.com/webhooks/tendar" } ``` If you omit the `direct_debit` field, Tendar charges the customer's default direct debit. See [Recollect Loan](https://docs.tendar.co/documentation/recollection/broken-reference) for the full recollection flow. ### Through a collect plan If you're using the [Collect](https://docs.tendar.co/documentation/recollection/broken-reference) feature for installment-based collections, Tendar can automatically debit the customer's bank account on the scheduled dates using the mandates set up within the collect plan. You don't need to initiate individual charges — the system handles it. ## The direct debit lifecycle A direct debit goes through several statuses during its lifetime. Understanding these will help you build the right UI and handle edge cases: | Status | What it means | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending_consent` | The direct debit has been created, but the customer hasn't approved the mandate yet. They need to visit the `checkout.url` and complete the bank consent flow. | | `pending_validation` | The customer has approved the mandate, but Tendar is still verifying the authorization with the payment provider. This is a transient state. | | `active` | The mandate is fully verified and the direct debit is ready to be charged. This is the only status from which charges can be initiated. | | `expired` | The mandate has passed its expiry date (typically 10 years from creation). A new direct debit needs to be created. | | `cancelled` | The direct debit was cancelled — either because it was a duplicate of an existing authorization, or because the bank rejected the mandate. Check the `message` field for details. | ``` pending_consent → pending_validation → active ↓ expired / cancelled ``` ## Webhooks The Direct Debit API sends webhook events at key moments in the authorization lifecycle. These are delivered to your company's registered webhook URL. \| Event | When it fires | |---|---|---| | `direct-debit.active` | The mandate has been verified by the bank and the direct debit is ready for charges. | | `direct-debit.cancelled` | The mandate was cancelled — either a duplicate was detected or the bank rejected the authorization. | | `direct-debit.pending_validation` | The customer completed the consent flow, and Tendar is verifying the mandate. | | `direct-debit.pending_consent` | The direct debit was created and is awaiting customer approval. | The webhook payload contains the full direct debit object (excluding the token, checkout details, and raw account number), so you can update your UI or trigger downstream workflows without making an additional API call. ### Example webhook payload ```json { "event": "direct-debit.active", "data": { "id": "6685be5f5ef3e0931e082ad6", "user": "6685bb34af274480e2251d85", "user_id": "usr-hnlfkizfoc", "default": true, "payment_service": "paystack", "currency": "NGN", "status": "active", "account": { "last_4_digits": "0258", "card_type": "mandate", "bank": "Guaranty Trust Bank", "exp_month": "7", "exp_year": "2034", "country_code": "NG", "email": "john@example.com", "account_name": "JOHN DOE" }, "signature": "SIG_eSRls0xZ252VL2575Uxb", "service_ref": "itu3semg6d10m0c", "message": "" } } ``` ## Understanding the direct debit object Here's a breakdown of every field on the direct debit object and what it means: | Field | Type | Description | | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The unique identifier for this direct debit record. | | `user` | string | The internal user ID (MongoDB ObjectId). | | `user_id` | string | The Tendar user ID (e.g., `usr-cheltgfnqt`). | | `default` | boolean | Whether this is the customer's default direct debit. | | `payment_service` | string | The payment provider used to create the mandate (currently `paystack`). | | `currency` | string | The currency associated with the direct debit (e.g., `NGN`). | | `status` | string | The current status of the authorization. One of `pending_consent`, `pending_validation`, `active`, `expired`, or `cancelled`. | | `account.last_4_digits` | string | The last 4 digits of the bank account number. Populated after verification. | | `account.card_type` | string | Always `mandate` for direct debits. | | `account.bank` | string | The name of the customer's bank (e.g., "Guaranty Trust Bank"). | | `account.exp_month` | string | The month the mandate expires. | | `account.exp_year` | string | The year the mandate expires (typically 10 years from creation). | | `account.country_code` | string | The 2-letter country code (e.g., `NG`). | | `account.email` | string | The email address associated with the authorization (pulled from the user record). | | `account.account_name` | string | The name on the bank account, as returned by the bank. | | `signature` | string | A unique identifier for this specific mandate, used for deduplication. | | `service_ref` | string | The payment provider's reference for the mandate. | | `checkout` | object | Contains `success_url`, `cancel_url`, and the hosted `url` for the consent flow. Only present before verification. | | `address` | object | The customer's address submitted during creation. Contains `state`, `city`, and `street`. Only present before verification. | | `message` | string | A status message — empty when everything is normal, contains an explanation when something went wrong (e.g., "direct debit already exists"). | ## Error handling Here are the errors you're most likely to encounter when working with the Direct Debit API, and how to resolve them: | Error | HTTP Status | Cause | Resolution | | ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `user not found` | 404 | The `user_id` doesn't match any user in your company. | Verify the user ID and ensure the user has been created under your company. | | `payment service key not found` | 400 | No payment provider keys are configured for your company. | Set up a payment service (Paystack) on the Tendar dashboard. | | `company not found` | 404 | The company associated with your API key doesn't exist. | Check your API key and company configuration. | | `direct debit not found` | 404 | The direct debit ID doesn't exist or doesn't belong to your company. | Verify the direct debit ID. | | `direct debit not active` | 400 | You attempted to charge or set as default a direct debit that isn't in `active` status. | Wait for the customer to complete the consent flow, or check if the mandate was rejected. | | `default direct debit cannot be deleted` | 400 | You tried to delete the customer's default direct debit without explicitly allowing it. | Pass `delete_default=true` as a query parameter, or set a different direct debit as default first. | | `direct debit already exists` | — | The customer already has an active direct debit with the same signature (same bank account mandate). | The existing authorization is still valid. The duplicate record is marked as cancelled. No action needed. | ## Security and compliance The Direct Debit API is designed with security at its core: * **Bank credentials never pass through your server.** The customer authenticates directly with their bank through the provider's hosted consent page. Your application never sees passwords, OTPs, or security answers. * **Tokens are stored securely** and scoped to your company. A token from one company cannot be used by another. * **Deauthorization on delete.** When you delete a direct debit, Tendar revokes the mandate with the payment provider — the token becomes permanently unusable. * **Orphaned authorizations are auto-cleaned.** If a customer starts the consent flow but doesn't complete it within 24 hours, the pending direct debit record is automatically deleted. * **Duplicate detection.** If a customer tries to authorize the same bank account twice, Tendar detects the duplicate and cancels the new record instead of creating a second active mandate. ## Putting it all together Here's a typical integration flow for setting up and using direct debit: {% stepper %} {% step %} ### Show supported banks Call `GET /direct-debit/bank/list` and display the results in a dropdown so the customer can select their bank. {% endstep %} {% step %} ### Collect account details Ask the customer for their bank account number, and collect their address (state, city, street). Your UI should make it clear that they're authorizing your business to debit their account. {% endstep %} {% step %} ### Create the direct debit Call `POST /direct-debit/create` with the customer's `user_id`, `account`, `address`, and `checkout` URLs. You'll get back a `checkout.url`. {% endstep %} {% step %} ### Redirect the customer Send the customer to the `checkout.url`. They'll land on a bank consent page where they review the mandate details and authenticate with their bank. {% endstep %} {% step %} ### Wait for the webhook Tendar receives the provider's webhook, verifies the mandate, saves the token, and fires a `direct-debit.active` event to your webhook URL. Update your UI to show the direct debit as active. {% endstep %} {% step %} ### Display the saved authorization Call `GET /direct-debit/list/:user_id?status=active` to show the customer their authorized accounts. Display the bank name, last 4 digits, and account holder name — never the full account number. {% endstep %} {% step %} ### Charge when needed Use the direct debit ID in a [recollection](https://docs.tendar.co/documentation/recollection/broken-reference) (`payment_channel: "direct_debit"`) or let a [collect](https://docs.tendar.co/documentation/recollection/broken-reference) plan debit the account automatically on schedule. {% endstep %} {% step %} ### Let the customer manage their authorizations Provide UI to set a different default (`PUT /direct-debit/default/set/:id`) or revoke an authorization (`DELETE /direct-debit/delete/:id`). {% endstep %} {% endstepper %} ## Next steps * [Recollect Loan](https://docs.tendar.co/documentation/recollection/broken-reference) — Charge an authorized bank account to record a loan repayment. * [Card Tokenization](https://docs.tendar.co/documentation/recollection/broken-reference) — Save customer cards as an alternative (or complement) to direct debit. * [Accept Payments](https://docs.tendar.co/documentation/recollection/broken-reference) — Initialize one-time payment sessions. * [Collect](https://docs.tendar.co/documentation/recollection/broken-reference) — Automate installment-based collections with mandates and scheduled debits. * [Virtual Accounts](https://docs.tendar.co/documentation/recollection/broken-reference) — Create dedicated bank accounts for inbound transfers.