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.

This documentation site has been deprecated as of September 8, 2025, and will no longer receive updates. Please refer to the new documentation site at https://docs.squadco.com.

The authorization key is sent via the request header as Bearer Token Authorization

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.

The flow is as follows

  1. Creating a Mandate on an account

  2. Account Holder approving the mandate on the account

  3. Debiting the account using the created mandate

GET BANK LIST

GET https://sandbox-api-d.squadco.com/transaction/mandate/banklists

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.

RESPONSE

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": [
        {
            "bank_name": "ACCESS BANK PLC",
            "bank_code": "044",
            "isActive": true
        },
        {
            "bank_name": "KEYSTONE BANK PLC",
            "bank_code": "082",
            "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": "FIRST CITY MONUMENT BANK PLC",
            "bank_code": "214",
            "isActive": true
        },
        {
            "bank_name": "GUARANTY TRUST BANK PLC",
            "bank_code": "058",
            "isActive": true
        },
        {
            "bank_name": "Kuda Microfinance Bank",
            "bank_code": "672",
            "isActive": true
        },
        {
            "bank_name": "9 Payment Service Bank",
            "bank_code": "802",
            "isActive": true
        }
    ]
}

CREATE MANDATE

POSThttps://sandbox-api-d.squadco.com/transaction/mandate/create

This endpoint allows you to create a mandate for an account

Request Body

Name
Type
Description

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 details

address*

String

Customer address

phone*

Integer

Customer phone number, must match with BVN details

Sample Request

Sample Response

Webhook Notification For Mandate Creation

Note: 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

On the Production environment, the customer must transfer N50 from the account to be mandated to any of the provided account numbers

Webhook Notification for Approved Mandate

DEBIT MANDATE

POSThttps://sandbox-api-d.squadco.com/transaction/mandate/debit

This endpoint allows you to debit an account where a mandate has been created

Debits can only occur once a day

Request Body

Name
Type
Description

amount*

Integer

Amount to be debitte from account

mandate_id*

Integer

mandate_id gotten in response from Creating the Mandate

transaction_reference*

Integer

Unique reference for each transaction

narration*

String

narration of debit

pass_charge*

Boolean

Pass charges to customers by setting to True

customer_email*

email

customer email address to be notified

Sample Request

Sample Response

Webhook Notification

Cancel Mandate

POSThttps://sandbox-api-d.squadco.com/transaction/mandate/cancel

This endpoint allows you to cancel a mandate on the account

Request Body

Name
Type
Description

mandateIds*

Object

mandateIdsis a object where a single or multiple mandate Ids can be passed

Sample Request

Sample Response

GET MANDATE BY REF

GEThttps://sandbox-api-d.squadco.com/transaction/mandate/get-mandates/:Ref

This endpoint allows you to get details of a mandate by passing the Reference of that mandate

Sample Response

PreviousPayment LinkNextRefund API

Last updated

Was this helpful?