Create Mandate
The Direct Debit endpoint lets you create a standing mandate on a customers account method which allows you perform a direct debit on the account within the approved mandate period.
1 - Get customer details
To initiate a mandate on an account, you'll need to pass information such as customer information, startDate, endDate, etc.
Please find below the request parameters for the endpoint.
Field | Mandatory | type | Description |
---|---|---|---|
amount | Yes | string | The total of the amount that would be deducted during the course of the mandate. I.e if you intend to deduct β¦10,000 every month for 3 months, the mandate amount would be β¦30,000. |
description | Yes | string | The reason why the mandate is being created. |
startDate | Yes | string | This must be a future date and canβt be the same date as the date the request was made. |
endDate | Yes | string | After this date, a direct debit can't be made again using the mandate reference. |
businessAddress | Yes | string | Your business address. |
customer | Yes | object | The customer whose account would be debited. |
customer.accountNumber | Yes | string | The customer's account number from which the amounts would be debited. |
customer.accountName | Yes | string | The customer's account name. |
customer.bankCode | Yes | string | The customer's bank code. To get the bank code please see the list banks endpoint codes for more details. |
customer.address | Yes | string | The customer's address. |
customer.email | Yes | string | The customer's email address. |
customer.phone | Yes | string | The customer's email phone number. |
currency | Yes | string | Currently, the only accepted currency is NGN. |
2 - Create Mandate
After collecting the necessary details to create a mandate. Make a POST request to our create mandate endpoint.
Endpoint:
{{host}}/mandate-mgt/mandates/
curl --location 'https://api.fincra.com/mandate-mgt/mandates/' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>' \
--header 'Content-Type: application/json' \
Here's a sample payload to initialize a mandate:
{
"amount": 72500.00,
"description": "config spirit rest l6ets test",
"startDate": "2024-04-26",
"endDate": "2024-10-31",
"businessAddress": "YOung blood",
"customer": {
"accountNumber": "0051762787",
"accountName": "Stan Lee",
"bankCode": "998",
"address": "Local Address, Lagos",
"email": "[email protected]",
"phone": "08030607376"
},
"currency": "NGN"
}
If the API call is successful, Fincra returns the following response:
{
"amount": 72500,
"description": "Subscription",
"responseDescription": "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 \"0008787867\" with GTBank. This payment will trigger the authentication of your mandate. Thank You",
"startDate": "2024-04-05T00:00:00.000Z",
"endDate": "2024-10-31T00:00:00.000Z",
"status": "initiated",
"reference": "mr_0788b7b-767da-7878-8886-dc0788cd",
"createdAt": "2024-04-04T08:04:05.474Z"
}
Note: For a mandate to be in effect, the account owner would have to authorize the mandate request by sending β¦50 from the account provided when creating a mandate, to the account returned in the responseDescription
field as seen above. Without this being done, the mandate can note be in effect.
3 - Get Mandate Status/Info
You can confirm mandate status by calling the get mandate info endpoint.
Endpoint:
{{host}}/mandate-mgt/mandates/reference/{{reference}}
curl --location 'https://api.fincra.com/mandate-mgt/mandates/reference/{{reference}}' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>' \
Here's the api response:
{
"amount": 72500,
"description": "Recurring loan repayment",
"responseDescription": "",
"startDate": "2024-04-04T00:00:00.000Z",
"endDate": "2024-10-31T00:00:00.000Z",
"status": "approved",
"reference": "mr_9dcere51-49f0-8347-9051-438783748",
"createdAt": "2024-04-03T09:56:34.812Z"
}
{
"message": "Mandate not found",
"error": "Not Found",
"statusCode": 404
}
4 - Receive and validate webhook notification
Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the mandate. Read our guide on securing and validating the webhook notification on your end.
Webhook response:
{
"event": "mandate.approved",
"data": {
"amount": 15000,
"description": "DD program",
"responseDescription": "",
"startDate": "2024-05-17T00:00:00.000Z",
"endDate": "2024-05-18T00:00:00.000Z",
"status": "approved",
"reference": "mr_b995e8cf-f8be-49c7-8555-35a421f75fe7",
"createdAt": "2024-05-16T11:44:33.000Z"
}
}
Updated 6 months ago