Direct Debit APIs

Direct Debit is a payment method that lets an account holder authorize a lender to take money from their bank account for services as they fall due, similar in effect to a debit card but backed by a standing authorization. It’s well suited to recurring payments on fixed dates and amounts (loan repayments, insurance premiums, subscriptions) as well as variable recurring payments on different dates.

The Direct Debit APIs let you, as a service provider, generate digital debit mandate instructions on your customers’ bank accounts, then create, activate, and debit those mandates.

How it works

A mandate instruction is a digital version of a physical instruction signed by the account holder. Once generated, it’s sent automatically to the customer’s bank for review and approval; the bank contacts the account owner to authorize the mandate, which typically takes 24 to 48 hours. Each initiated mandate gets a unique mandate code, which you use to initiate direct debit transactions against that account.

End to end, a mandate typically takes at least 2 hours to move from activation to being available for debits.

The Direct Debit process

1. Mandate creation

Create the mandate through the API. As soon as it’s created, tell the customer how to activate it: best practice is to notify them in-app, by email, and by SMS.

2. Mandate activation

The customer activates the mandate by transferring ₦50 (or ₦100 for banks with a ₦100 minimum transfer) to a designated NIBSS-operated account. They have 168 hours (7 days) to do this, or the mandate is automatically canceled. As soon as the activation amount is received, the mandate is activated, though it isn’t yet available for debit.

Customers activate mandates by transferring to one of these accounts:

Bank	Account number	How to send
Fidelity Bank Plc	9020025928	USSD, mobile app, or internet banking
Paystack-Titan	9880218357	Mobile app or internet banking

3. Setup for debit

NIBSS runs backend processing to prepare the account for debit, which can take up to 2 hours. If you attempt a debit before this completes, you’ll get an error such as “do not honor.”

4. Transactions

Once set up for debit is complete, you can initiate debit transactions against the mandate using its mandate code.

Understanding mandate statuses

Status	Description
Pending Mandate Activation	The mandate has just been created and is waiting on the customer’s activation transfer.
Pending	The customer’s ₦50 activation transfer has been received. The system then attempts a ₦100 debit to confirm sufficient funds, retrying until successful. You can inspect each transaction attempt for a failure description to help guide the customer.

Common transaction failure descriptions:

Description	What it means
Do Not Honor	The customer has a restriction on their account, or their bank couldn’t process the transaction at that moment. Wait an hour or two after the notification email from dd.lendsqr.com before contacting the customer.
Insufficient Funds	The account doesn’t have enough funds. Ask the customer to fund their account so the mandate can activate.

For the admin-console view of mandate statuses on a specific loan, see Understanding mandate statuses.

Questions about a specific mandate or integration? Email [email protected].