Direct Debit
This set of APIs allows you to enable an account number for direct debits up to pre-set amount over a defined period of time without further approval from the account owner
The authorization key is sent via the request header as Bearer Token Authorization
Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f
Direct Debit Flow
The direct debit service works by applying Mandates to an account. A mandate is an authorized instruction that permits an account to be debited up to a specific amount within a defined duration.
Flow Summary
Creating a Mandate on an account
Account Holder approving the mandate on the account
Debiting the account using the created mandate
Get Bank List
This endpoint retrieves a list of all banks for which the Direct Debit service is available. The list returned is dynamic, and mandates can only be created for returned banks
Parameters
Sample BankList Response
{
"status": 200,
"success": true,
"message": "Success",
"data": [
{
"bank_name": "ACCESS BANK PLC",
"bank_code": "044",
"isActive": true
},
{
"bank_name": "ECOBANK NIGERIA PLC",
"bank_code": "050",
"isActive": true
},
{
"bank_name": "FIDELITY BANK PLC",
"bank_code": "070",
"isActive": true
},
{
"bank_name": "FIRST BANK OF NIGERIA PLC",
"bank_code": "011",
"isActive": true
},
{
"bank_name": "GUARANTY TRUST BANK PLC",
"bank_code": "058",
"isActive": true
},
{
"bank_name": "Kuda Microfinance Bank",
"bank_code": "672",
"isActive": true
}
]
}
Create Mandate
This endpoint allows you to create a mandate for an account
Parameters
Create Mandate
mandate_type*
String
The type of mandate to be used, always set to emandate (electronic mandate)
amount*
Integer
The total amount in kobo to be debitted throughout the mandate cycle (expressed in the lowest currency value - kobo). 10000 = 100NGN
account_number*
Integer
The account number of customer to be mandated
bank_code*
String
Unique NIP code that identifies a bank.
description*
String
Merchant description of the transaction
start_date*
date
Start date for the mandate, YYYY-MM-DD
end_date*
date
End date for the mandate, YYYY-MM-DD
customer_email*
String
Email of customer whose account is to be mandated. A notification will be sent to the customer
transaction_reference*
String
Unique reference number for each mandate. Where not provided, the system generates one
customerInformation*
Object
The customerInformation collects relevant customer information for mandate creation
identity*
Object
identity is a nested object inside the customerInformation object where value of type is bvn and number is the customer bvn number
firstName*
String
Customer first name, must match with BVN deatails
lastName*
String
Customer last name, must match with BVN deatails
address*
String
Customer address
phone*
Integer
Customer phone number, must match with BVN details
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"message": "Kindly authorise this mandate by transferring N50.00 from your GTB TESTING to Account Number: "9880218357" Bank: Paystack Titan or Account Number: "9020025928" Bank: Fidelity",
"mandate_id": "sqaudDD63a5fqsowsy57ic0h5eps25k28e",
"mandate_type": "emandate",
"debit_type": "variable",
"status": "initiated",
"approved": false,
"ready_to_debit": false,
"reference": "livepilot0260118",
"account_number": "2473064070",
"description": "20kish pilot slive",
"start_date": "2025-08-27T00:00:00",
"end_date": "2026-01-20T00:00:00",
"date": "2025-08-06T15:19:55.2910043+00:00",
"transfer_destinations": [
{
"bank_name": "Paystack Titan",
"account_number": "9880218357",
"icon": "https://mono-public-bucket.s3.eu-west-2.amazonaws.com/images/paystack-icon.png"
},
{
"bank_name": "Fidelity",
"account_number": "9020025928",
"icon": "https://mono-public-bucket.s3.eu-west-2.amazonaws.com/images/fidelity-bank-icon.png"
}
]
}
}
}
{
"status": 400,
"success": false,
"message": "Customer already exists with the same email address.",
"data": {}
}
Sample Request
{
"mandate_type": "emandate",
"amount": "2000000",
"account_number": "2473064070",
"bank_code": "050",
"description": "20kish pilot slive",
"start_date": "2025-08-27",
"end_date": "2026-01-20",
"customer_email": "willia@gmail.com",
"transaction_reference": "livepilot0260118",
"customerInformation": {
"identity": {
"type": "bvn",
"number": "22984135000"
},
"firstName": "william",
"lastName": "udousoro",
"address": "no 11 claytus street sabo yaba",
"phone": "08132448008"
}
}
Webhook Notification For Mandate Creation
{
"Event": "mandates.approved",
"TransactionRef": "livepilot0260118",
"Body": {
"status": "approved",
"mandate_type": "emandate",
"debit_type": "variable",
"ready_to_debit": false,
"approved": true,
"reference": "livepilot0260118",
"account_name": "william udousoro",
"account_number": "0179088393",
"bank": "GTB TESTING",
"message": "Mandate approved",
"start_date": "2025-08-27T00:00:00Z",
"end_date": "2026-01-20T22:59:59.999Z",
"date": "2025-08-06T12:01:40.416Z",
"amount": 2000000,
"business": "673c6efe9c0a66056f27b19a",
"merchantId": "SBBWRX1Z3S",
"mandate_id": "sqaudDDa27chviz8nwhv3d6w4gy"
}
}
Due to the limitations of the Sandbox environment, 24hours must be allowed to pass after creating the mandate before the Mandate can be debitted. Another Webhook will be sent once the account can be debitted
Webhook Notification for Approved Mandate
{
"Event": "mandates.ready",
"TransactionRef": "livepilot0260118",
"Body": {
"status": "approved",
"mandate_type": "emandate",
"debit_type": "variable",
"ready_to_debit": true,
"approved": true,
"reference": "livepilot0260118",
"account_name": "william udousoro",
"account_number": "0179088393",
"bank": "GTB TESTING",
"message": "Mandate is now ready for debiting",
"start_date": "2025-08-27T00:00:00Z",
"end_date": "2026-01-22T22:59:59.999Z",
"date": "2025-08-04T13:45:28.1Z",
"amount": 20000000,
"business": "673c6efe9c0a66056f27b19a",
"merchantId": "SBBWRX1Z3S",
"mandate_id": "sqaudDD39cf95ohb3702mre87tj23"
}
}
Debit Mandate
This endpoint allows you to debit an account where a mandate has been created
Parameters
Debit Mandate
amount*
Integer
Amount to be debitted from account
mandate_id*
Integer
mandate_id gotten in response from Creating the Mandate
transaction_reference*
Integer
narration of debit
pass_charge*
Boolean
Pass charges to customers by setting to True
customer_email*
customer email address to be notified
Debits can only occur once a day
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"status": "Success",
"aamount": 50000,
"mandate_id": "sqaudDDf99ae9mtizerna8f",
"transaction_reference": "super323",
"date": "2025-08-06T12:00:37.1440078+00:00",
"account": {
"bank_code": "044",
"account_name": "william udousoro",
"account_number": "0179088393"
}
}
}
}
{
"status": 400,
"success": false,
"message": "Mandate on account 0179088393 is not ready for debit.",
"data": {}
}
{
"status": 400,
"success": false,
"message": "Daily debit limit reached for mandate sqaudDDf99ae9mtizerna8f, please try again tomorrow.",
"data": {}
}
{
"status": 400,
"success": false,
"message": "Mandate on account 0179088393 balance is lesser than debit amount.",
"data": {}
}
Sample Request
{
"amount": 50000,
"mandate_id": "sqaudDDa27chviz8nwhv3d6w4gy",
"transaction_reference": "super32333",
"narration": "test2004",
"pass_charge": false,
"customer_email" : "willia@gmail.com"
}
Webhook Notification
{
"Event": "charge_successful",
"TransactionRef": "super32333",
"Body": {
"amount": 50000,
"transaction_ref": "super32333",
"gateway_ref": "super32333_2_2_1",
"transaction_status": "Success",
"email": "williamudousoro@gmail.com",
"merchant_id": "SBBWRX1Z3S",
"currency": "NGN",
"transaction_type": "Bank",
"merchant_amount": 49500,
"created_at": "2025-08-06T13:00:37.128",
"meta": {},
"is_recurring": false
}
}
Cancel Mandate
This endpoint allows you to cancel a mandate on the account
Parameters
Cancel Mandate
mandateIds*
Object
mandateIdsis a object where a single or multiple mandate Ids can be passed
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"canceledMandates": [
"sqaudDDf99ae9mtizerna8f"
],
"failedMandates": []
}
}
}
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"canceledMandates": [],
"failedMandates": [
{
"mandateId": "sqaudDDf99ae9mtizerna8f",
"failureReason": "Mandate already cancelled"
}
]
}
}
}
Sample Request
{
"mandateIds": [
"sqaudDD657al1hrep7m4bc",
"sqaudDD5c9elxp61u3sju",
"sqaudDD5c9elxp61u3sju"
]
}
Get Mandate By Ref
This endpoint allows you to get details of a mandate by passing the Reference of that mandate
Parameters
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": [
{
"start_date": "2025-08-31T00:00:00",
"end_date": "2026-01-22T00:00:00",
"account_number": "0179088393",
"account_name": "william udousoro",
"bankName": "Standard Chartered",
"bank": "068",
"ready_to_debit": true,
"is_approved": true,
"status": "approved",
"merchant_reference": "workinornot242",
"mandate_type": "emandate",
"debit_type": "variable",
"merchant_id": "SBBWRX1Z3S",
"amount": 20000000,
"balance": 20000000,
"total_debited": 0
}
]
}
Go Live
To go live, simply:
- Change the base URL of your endpoints from sandbox-api-d.squadco.com to api-d.squadco.com
- Sign up on our Live Environment
- Complete your KYC
- Use the secret key provided on the dashboard to replace the test keys gotten from the sandbox environment to authenticate your live transactions