Debit Mandates

1.0 AUTHORIZATION

Authorization to the APIs below requires an access token. To get more info on how to generate this access token, click on Generating Access Token

2.0 BASE URL

All requests to the Wallet API in the test environment must be done using the web API URL below.

Test Environment: https://api-devapps.vfdbank.systems/vtech-mandate/api/v2/directdebit

LIVE Environment: https://api-apps.vfdbank.systems/vtech-mandate/api/v2/directdebit

3.1 DEBIT MANDATE APIS

You have two options for collections via debit mandate. These options can both create a debit mandate

1. DIRECT-MANDATE CREATE API : With this API, the payer's bank will typically contact the payer directly to confirm approval of the mandate. It also requires the payer's signature and a witness information.
2. E-MANDATE CREATE API: With this API, an account number that needs to be funded with N50 is returned. The payer is meant to fund this account number to confirm approval of the mandate. It does not require the payer's signature and a witness information.

3.1.1 HOW TO USE THE DIRECT-MANDATE CREATE API

1. The developer calls the DIRECT-MANDATE CREATE API to set up the debit mandate on the customer's bank account
2. The developer should then call the MANDATE-APPROVAL-STATUS API to confirm the status of the created mandate
3. If the status returned from calling the MANDATE-APPROVAL-STATUS API is Bank Approved, the developer can then proceed to call the ACCOUNT DEBIT API to debit the customer's bank account where the mandate was setup

3.1.2 DIRECT-MANDATE CREATE API

API Context: /mandate/setup

Description: This endpoint is used to setup a debit mandate on a customer's bank account.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "reference": "rosapay-202308191",
    "payerBank": "000007",
    "payerAccountNumber": "6170778639",
    "payerBvn": "222222222228",
    "payerAddress": "5, Ade Street, Lagos",
    "payerPhone": "09019056987",
    "payerEmailAddress": "odtest@gmail.com",
    "receiverBank": "999999",
    "receiverBvn": "22222222222",
    "receiverAccountNumber": "1001556881",
    "amount": "1000",
    "startDate": "02 June 2023",
    "endDate": "17 July 2023",
    "frequency": "1",
    "witnessName": "Joe Adams",
    "witnessAddress": "12, John Street, Lagos",
    "witnessOccupation": "Software Engineer",
    "payerSignature": "",
    "witnessSignature": ""
}

Field	Description	Status
reference	Unique Reference for transaction, Reference should have wallet Name as Prefix e.g rosapay-202308191	Mandatory
payerAccountNummber	This is the account to initiate payment	Mandatory
payerBank	Payer's bank Code	Mandatory
payerBvn	Payer's BVN	Mandatory
payerAddress	Payer's Address	Mandatory
payerPhone	Payer's Phone	Mandatory
payerEmailAddress	Payer's Email Address	Mandatory
payerAccountname	Payer Account Name	Mandatory
receiverAccountNumber	This is the account to receive payment	Mandatory
receiverBank	Receiver's bank Code	Mandatory
amount	maximum debit amount	Mandatory
startDate	Mandate Start Date e.g 02 June 2023 (Must be in this date format)	Mandatory
endDate	Mandate End Date e.g 17 July 2023 (Must be in this date format)	Mandatory
frequency	The type of debit reoccurrence, can be daily (if you pass 1), weekly(if you pass 2) or monthly(if you pass 3)	Mandatory
witnessName	Name of Witness	Mandatory
witnessAddress	Witness House address	Mandatory
witnessOccupation	Witness Occupation	Mandatory
payerSignature	Payer's Signature base64 Picture Image	Mandatory
witnessSignature	Witness Signature base64 Picture Image	Mandatory

info

It's important to note that in the dev environment, the mandate should only be created with a test VFD account as the payerAccountNumber and receiverAccountNumber as creating a mandate on other bank accounts is not supported in dev

info

It's also important to note that mandates can only be setup on a commercial bank as the payerBank in the live environment.

info

It's also important to note that the least amount when creating a mandate is NGN1,000.

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Mandate Created Successfully",
    "data": {
        "mandateCode": "RC1203338/1/19062023163120"
    }
}

SAMPLE FAILED RESPONSE

{
    "status": "99",
    "message": "Invalid Payer Account Number"
}

SAMPLE REFERENCE EXIST RESPONSE

{
    "status": "98",
    "message": "Mandate Reference Exist"
}

SAMPLE SIGNATURE RESPONSE

{
    "status": "99",
    "message": "Witness Signature must be in base64"
}

3.1.3 HOW TO USE THE E-MANDATE CREATE API

1. The developer calls the E-MANDATE CREATE API to setup the debit mandate on the customer's bank account
2. The developer should then call the MANDATE-APPROVAL-STATUS API to confirm the status of the created mandate
3. If the status returned from calling the MANDATE-APPROVAL-STATUS API is Bank Approved, the developer can then proceed to call the ACCOUNT DEBIT API to debit the customer's bank account where the mandate was setup

3.1.4 E-MANDATE CREATE API

API Context: /mandate/setup?e-mandate=true

Description: This endpoint is used to setup a debit mandate on a customer's bank account.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

Query Parameters	Description	Required
e-mandate	This determines if the merchant wants to create an e-mandate. Must be true	Mandatory

SAMPLE REQUEST

{
    "reference": "rosapay-202308191",
    "payerBank": "999999",
    "payerAccountNumber": "1001555949",
    "payerPhone": "09019056987",
    "payerEmailAddress": "test@gmail.com",
    "payerAddress":"5, Johnson Street, Ikeja, Lagos",
    "receiverBank": "999999",
    "receiverAccountNumber": "1001556551",
    "amount": "1000",
    "startDate": "02 June 2023",
    "endDate": "17 July 2023",
    "frequency": "1"
}

Field	Description	Status
reference	Unique Reference for transaction, Reference should have wallet Name as Prefix e.g rosapay-202308191	Mandatory
payerAddress	Payer's address	Mandatory
payerAccountNumber	This is the account to initiate payment	Mandatory
payerBank	Payer's bank Code	Mandatory
payerPhone	Payer's Phone	Mandatory
payerEmailAddress	Payer's Email Address	Mandatory
receiverAccountNumber	This is the account to receive payment	Mandatory
receiverBank	Receiver's bank Code	Mandatory
amount	maximum debit amount	Mandatory
startDate	Mandate Start Date e.g 02 June 2023 (Must be in this date format)	Mandatory
endDate	Mandate End Date e.g 17 July 2023 (Must be in this date format)	Mandatory
frequency	The type of debit reoccurrence, can be daily (if you pass 1), weekly(if you pass 2) or monthly(if you pass 3)	Mandatory

info

It's important to note that in the live environment, the account the E-mandate is being set up on must be used for the N50 funding. This funding acts as the customer's approval of the mandate. Also note that the funding must be done within 7 days to prevent the mandate from expiring.

info

It's also important to note that mandates can only be setup on a commercial bank as the payerBank in the live environment. But the receiverBank can be a commercial bank or a non-commercial bank in both the live and test environments.

SAMPLE RESPONSE

{ 
    "status":"00",
    "message":"Welcome to NIBSS e-mandate authentication service, a seamless and convenient authentication experience. Kindly proceed with a token payment of N50:00 into account number \"1000000000\" with PAYSTACK - TITAN, Account name is NIGERIA INTERBANK SETTLEMENT SYSTEM PLC. Note: The payment should be done from the account on which the mandate is setup. This payment will trigger the authentication of your mandate. Thank You",
    "data": {
        "mandateCode":"RC1000000/1111/0001110111"
        }
   }

SAMPLE FAILED RESPONSE

{
    "status": "99",
    "message": "Invalid Payer Account Number"
}

SAMPLE REFERENCE EXIST RESPONSE

{
    "status": "98",
    "message": "Mandate Reference Exist"
}

3.1.5 TEST MANDATE PAYER AND RECEIVER ACCOUNTS

S/N	Bank Code	Account Number
1	000002	1111111103
2	000006	1111111111

4.0 ACCOUNT DEBIT

API Context : /account/debit

Description: This endpoint allows you debit the customer's account.

API METHOD: POST

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

SAMPLE REQUEST

{
    "amount": "1000",
    "narration": "mandate test via nibsseasypay",
    "mandateReference": "rosapay-2023089819319021212",
    "transactionReference": "rosapay-202308981931902"
}

Field	Description	Status
amount	Amount to debit (must not be greater than the amount specified on mandate creation)	Mandatory
narration	Narration of transactions	Optional
mandateReference	Reference used in mandate creation e.g rosapay-2023089819319021212	Mandatory
transactionReference	Unique Reference for transaction, Reference should have wallet Name as Prefix e.g rosapay-202308981931902	Mandatory

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Mandate Account Transfer",
    "data": {
        "sessionId": "99999903232323200620230840476432023",
        "paymentReference": "BAAS-DD-2023062008452",
        "mandateCode": "RC1203338/1/19062023163120"
    }
}

SAMPLE INVALID RESPONSE

{
    "status": "108",
    "message": "Invalid Reference!"
}

4.1 ACCOUNT BALANCE

API Context : /account/balance?reference={reference}

Description: This endpoint allows you get the payer's account balance of a created mandate.

API METHOD: GET

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

Query Parameters	Description	Required
reference	Reference used in mandate creation	Mandatory

SAMPLE RESPONSE

{
    "status": "200",
    "message": "Account Balance Retrieval For - John Doe",
    "data": {
        "accountNo": "1001573671",
        "availableBalance": "5000",
        "sessionId": "099090322109909032210990903221"
    }
}

SAMPLE INVALID RESPONSE

{
    "status": "108",
    "message": "Invalid Reference!"
}

4.2 MANDATE APPROVAL STATUS QUERY

API Context : /mandate/status

Description: This endpoint is used to view the approval status of a mandate.

API METHOD: GET

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

QUERY PARAMETERS

reference	test-aqwsd111111dfegt

Field	Description	Status
Reference	Reference used in mandate creation	Mandatory

SAMPLE RESPONSE

{
    "status": "200",
    "message": "Mandate Created Successfully",
    "data": {
        "mandateState": "ACTIVE",
        "mandateWorkflowStatus": "MANDATE_APPROVED_BY_BANK",
        "mandateWorkflowStatusDescription": "Bank Approved"
    }
}

4.3 MANDATE DEBIT STATUS QUERY

API Context : /transaction/status

Description: This endpoint is used to view the transaction status of a mandate debit.

API METHOD: GET

REQUEST HEADERS

Key	Value
AccessToken	{{token}}

QUERY PARAMETERS

reference	test-aqwsd111111dfegt

Field	Description	Status
reference	Reference used in mandate debit	Mandatory

SAMPLE RESPONSE

{
    "status": "00",
    "message": "Successful Transaction Retrieval",
    "data": {
        "TxnId": "rosapay-098388438",
        "amount": "1000.00",
        "fromAccount": "1001648379",
        "fromBank": "090110",
        "toAccount": "1001649376",
        "toBank": "090110",
        "mandateReference": "rosapay-202308191509",
        "transactionStatus": "00",
        "transactionDate": "2025-05-28T17:39:11",
        "sessionId": "99999903232323280520251839116472025"
    }
}

note

The transactionStatus represents the mandate debit transaction status

4.4 CODES DESCRIPTION FOR DEBIT MANDATE

4.4.1 This details both the response code and description.

S/N	Description	Code
1	Approved or completed successfully	00
2	Status unknown, please wait for settlement report	01
3	Invalid Sender	03
4	Do not honor	05
5	Dormant Account	06
6	Invalid Account	07
7	Account Name Mismatch	08
8	Request processing in progress	09
9	Invalid transaction	12
10	Invalid Amount	13
11	Invalid Batch Number	14
12	Invalid Session or Record	15
13	Unknown Bank Code	16
14	Invalid Channel	17
15	Wrong Method Call	18
16	No action taken	21
17	Unable to locate record	25
18	Duplicate record	26
19	Format error	30
20	Suspected fraud	34
21	Contact sending bank	35
22	EXPIRED MANDATE	40
23	DEBIT AMOUNT GREATER THAN MANDATE	41
24	PREMATURE MANDATE	42
25	UNAPPROVED MANDATE	43
26	SUSPENDED DELETED MANDATE	44
27	NOT VARIABLE FREQUENCY MANDATE	45
28	NOT VARIABLE AMOUNT MANDATE	46
29	No sufficient funds	51
30	Transaction not permitted to sender	57
31	Transaction not permitted on channel	58
32	Transfer limit Exceeded	61
33	Security violation	63
34	Exceeds withdrawal frequency	65
35	Response received too late	68
36	Unsuccessful Account/Amount block	69
37	Unsuccessful Account/Amount unblock	70
38	Empty Mandate Reference Number	71
39	Beneficiary Bank not available	91
40	Routing error	92
41	Duplicate	94
42	Payment was not completed. Contact the bank.	95
43	System malfunction	96
44	Timeout waiting for response from destination	97
45	Client Disabled	A1
46	Not found	A2
47	Mandate Expired	A3
48	Empty Value	A4
49	Invalid Value	A5
50	Invalid Data Provided	A6
51	Remote IP not Permited	A7
52	Invalid Client id	A8
53	Unable to Process request, please try again	A9
54	Mandate Bank Mismatch	B0
55	Mandate Account Mismatch	B1

4.4.2 This details both the bank name and bank code.

S/N	Bank	Code
1	ACCESS BANK PLC	000014
2	CITI BANK	000009
3	Coronation Merchant Bank	060001
4	EcoBank Plc	000010
5	FBNQUEST Merchant Bank	060002
6	FIDELITY BANK PLC	000007
7	FIRST BANK OF NIGERIA PLC	000016
8	FIRST CITY MONUMENT BANK PLC	000003
9	FSDH MERCHANT BANK	400001
10	Globus Bank Ltd	000027
11	GUARANTY TRUST BANK PLC	000013
12	JAIIZ Bank	000006
13	KEYSTONE BANK PLC	000002
14	Kuda Microfinance Bank	090267
15	LOTUS Bank	000029
16	MAINSTREET BANK PLC	999014
17	OPTIMUS BANK LIMITED	000036
18	PARALLEX BANK	000030
19	POLARIS BANK LIMITED	000008
20	PremiumTrust Bank Limited	000031
21	Providus Bank	000023
22	Rand Merchant Bank	000024
23	Stanbic IBTC	000012
24	STANDARD CHARTERED BANK PLC	000021
25	STERLING BANK PLC	000001
26	SUNTRUST BANK	000022
27	TAJBank Ltd	000026
28	The Alternative Bank Limited	000037
29	TITAN TRUST BANK	000025
30	UBA Plc	000004
31	UNION BANK OF NIGERIA PLC	000018
32	UNITY BANK PLC	000011
33	Wema Bank	000017
34	ZENITH INTERNATIONAL BANK	000015