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

Creating a Mandate on an account
Account Holder approving the mandate on the account
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

{
    "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"
    }
}

Sample Response

{
    "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"
            }
        ]
    }
}

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"
  }
}

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

{
  "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

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*

customer email address to be notified

Sample Request

{
    "amount": 50000,
    "mandate_id": "sqaudDDa27chviz8nwhv3d6w4gy",
    "transaction_reference": "super32333",
    "narration": "test2004",
    "pass_charge": false,
    "customer_email" : "willia@gmail.com"
}

Sample Response

{
    "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"
        }
    }
}

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

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

{
    "mandateIds": [
        "sqaudDD657al1hrep7m4bc",
        "sqaudDD5c9elxp61u3sju",
        "sqaudDD5c9elxp61u3sju"
    ]
}

Sample Response

{
    "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"
            }
        ]
    }
}

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

{
    "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
        }
    ]
}

PreviousPayment Link NextRefund API

Last updated 4 months ago

hashtagDirect Debit Flow

hashtagGET BANK LIST

hashtagRESPONSE

hashtagCREATE MANDATE

hashtagRequest Body

hashtagSample Request

hashtagSample Response

hashtagWebhook Notification For Mandate Creation

hashtagWebhook Notification for Approved Mandate

hashtagDEBIT MANDATE

hashtagRequest Body

hashtagSample Request

hashtagSample Response

hashtagWebhook Notification

hashtagCancel Mandate

hashtagRequest Body

hashtagSample Request

hashtagSample Response

hashtagGET MANDATE BY REF

hashtagSample Response

Direct Debit Flow

GET BANK LIST

RESPONSE

CREATE MANDATE

Request Body

Sample Request

Sample Response

Webhook Notification For Mandate Creation

Webhook Notification for Approved Mandate

DEBIT MANDATE

Request Body

Sample Request

Sample Response

Webhook Notification

Cancel Mandate

Request Body

Sample Request

Sample Response

GET MANDATE BY REF

Sample Response