Initiate Direct Debit
This API lets you initiate a debit on an existing mandate.
Let's get started.
1 - Pay with mandate
Ensure the details you provide match those used to create the mandate currently being debited. To proceed, make a POST request to our Initiate Debit on Mandate endpoint.
Endpoint:
{{host}}/mandate-mgt/mandates/payment
curl --location 'https://api.fincra.com/mandate-mgt/mandates/payment' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>' \
--header 'Content-Type: application/json' \
Here's a sample payload to initialize a transaction:
{
"amount": 100,
"description": "Direct debit for loan",
"mandateReference": "mr_9dc12651-49df0-4e4f-9051-5627427d1988",
"reference": "UUreplicda25",
"currency": "NGN",
"bankCode": "999998",
"accountNumber": "0051762787",
"initiatorAccountName": "biao name",
"beneficiaryNarration": "bia mnonso narration"
}
If the API call is successful, Fincra returns the following response:
{
"amount": 100,
"description": "Direct debit for loan",
"mandateReference": "mr_9dc12651-49df0-4e4f-9051-5627427d1988",
"reference": "fcr-p-a9853908bb",
"currency": "NGN",
"bankCode": "999998",
"accountNumber": "0051762787",
"paymentMethods": [
"direct_debit"
],
"defaultPaymentMethod": "direct_debit",
"convertedAmount": 100,
"convertedCurrency": "NGN",
"settlementDestination": "bank_account",
"settlementTime": "next_day",
"scheduledAt": null,
"feeBearer": "customer",
"merchantReference": "MKMDTDEBITTST13",
"businessId": "6157039850139ad6695d8633",
"mandateCode": null,
"payer": {
"accountNumber": "0051762787",
"bankCode": "999998"
},
"paymentLinkId": null,
"redirectUrl": null,
"customUrl": null,
"successMessage": null,
"metadata": null,
"varianceType": null,
"customer": {
"phoneNumber": null
},
"id": 1278613,
"amountReceived": 0,
"isDisabled": false,
"status": "initiated",
"createdAt": "2024-06-24T16:16:06.443Z",
"updatedAt": "2024-06-24T16:16:06.443Z",
"amountExpected": 1100,
"message": null,
"actionRequired": null
}
Note: The mandate reference is the reference that was created and returned when the mandate was initially created. Also, a debit can not be initiated using a mandate whose tenure has ended, or one where the mandate amount has been maximized.
2 - Receive and validate webhook notification
Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the collection. Read our guide on securing and validating the webhook notification on your end.
Webhook response:
{
"event": "direct_debit.success",
"data": {
"amount": 109,
"description": "Direct debit for loan",
"mandateReference": "mr_33WJEHJ8-3cf2-4495-8acc-h87hnin9sh",
"reference": "MKMHJEHHSITT370",
"currency": "NGN",
"bankCode": "044",
"accountNumber": "8923898923",
"paymentMethods": [
"direct_debit"
],
"defaultPaymentMethod": "direct_debit",
"convertedAmount": 109,
"convertedCurrency": "NGN",
"settlementDestination": "bank_account",
"scheduledAt": null,
"feeBearer": "customer",
"merchantReference": "MKMDTDEBITTST10",
"businessId": "8892989jd9j9d38j893",
"mandateCode": "RC1hbsd878/18376/92908497284",
"payer": {
"accountNumber": "8923898923",
"bankCode": "044"
},
"paymentLinkId": null,
"redirectUrl": null,
"customUrl": null,
"successMessage": null,
"metadata": null,
"varianceType": null,
"customer": {
"phoneNumber": null
},
"id": 289389,
"amountReceived": 0,
"isDisabled": false,
"status": "success",
"createdAt": "2024-05-16T11:13:54.960Z",
"updatedAt": "2024-05-16T11:13:54.960Z",
"actionRequired": null
}
}
{
"event": "direct_debit.failed",
"data": {
"amount": 106,
"description": "Direct debit for loan",
"mandateReference": "mr_13u8w794-7595-4ac7-97874-c79bweui3ad6",
"reference": "MKMDTDEBITUHS98",
"currency": "NGN",
"bankCode": "232",
"accountNumber": "09028389823",
"paymentMethods": [
"direct_debit"
],
"defaultPaymentMethod": "direct_debit",
"convertedAmount": 106,
"convertedCurrency": "NGN",
"settlementDestination": "bank_account",
"scheduledAt": null,
"feeBearer": "customer",
"merchantReference": "MKMDTDEBITTST07",
"businessId": "283999389898293unu98c",
"mandateCode": "RC188989832/892389/983289GG",
"payer": {
"accountNumber": "09028389823",
"bankCode": "232"
},
"paymentLinkId": null,
"redirectUrl": null,
"customUrl": null,
"successMessage": null,
"metadata": null,
"varianceType": null,
"customer": {
"phoneNumber": null
},
"id": 23998923,
"amountReceived": 0,
"isDisabled": false,
"status": "failed",
"createdAt": "2024-05-16T11:13:20.332Z",
"updatedAt": "2024-05-16T11:13:20.332Z",
"actionRequired": null
}
}
Updated 2 months ago