Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here

Endpoint URL: {{base_url}}/api/v1/merchant/direct-debit/mandate/create

...

Info

The {{base_url}} for test is https://sandbox.monnify.com but when you go live, it changes to the live url.

Open Flexible

For open flexible use case, you are informing Monnify that the mandate needs to be renewed periodically and you intend to periodically charge the customer a variable amount.

You will need to set the "autoRenew", parameter to true so that Monnify always renews the mandate and would also need to omit the "debitAmount" parameter as shown below

Open Flexible Sample Request

Code Block
languagejson
{
   "contractCode": "797854529434",
   "mandateReference": "test-09-04-24-06",
   "autoRenew": true,
   "customerName": "Ankit Kushwaha",
   "customerPhoneNumber": "1234567890",
   "customerEmailAddress": "ankit.kushwaha@moniepoint.com",
   "customerAddress": "123 Example Street, City, Country",
   "customerAccountNumber": "0051762787",
   "customerAccountBankCode": "998",
   "mandateDescription": "Subscription Fee",
   "mandateStartDate": "2024-04-10T10:15:30",
   "mandateEndDate": "2025-01-19T10:15:30",
   "mandateAmount": 1000
}

Open Fixed

For an open fixed use case, you are informing Monnify that the mandate needs to be renewed periodically and you intend to periodically charge the customer a fixed amount.

You will need to set the "autoRenew", parameter to true so that Monnify always renews the mandate and would also need to set the "debitAmount" to the fixed amount you intend to charge periodically as shown below

Open Fixed Sample Request

Code Block
languagejson
{
   "contractCode": "797854529434",
    "mandateReference": "test-1809-0304-24-1005",
    "autoRenew": true,
   "customerName": "Ankit Kushwaha",
   "customerPhoneNumber": "1234567890",
   "customerEmailAddress": "ankit@gmail.com",
   "customerAddress": "123 Example Street, City, Country",
   "customerAccountNumber": "0051762787",
   "customerAccountBankCode": "998",
   "mandateDescription": "Subscription Fee",
   "mandateStartDate": "2024-04-10T10:15:30",
   "mandateEndDate": "2025-01-19T10:15:30",
   "customerCancellationdebitAmount": 10000
}

Closed Fixed

For a closed fixed use case, you are informing Monnify that the mandate is for a predetermined duration and you intend to periodically charge the customer a fixed amount.

You will need to set the "autoRenew" parameter to false while your predetermined end date is set in the mandateEndDate parameter and would also need to set the "debitAmount" parameter as shown below

Sample Request

Code Block
languagejson
{
   "contractCode": "797854529434",
   "mandateReference": "test-18-03-24-10",
   "autoRenew": false,
   "customerName": "Ankit Kushwaha",
    "customerPhoneNumber": "1234567890",
    "customerEmailAddress": "muhammad.sheraz@moniepoint.com",
    "customerAddress": "123 Example Street, City, Country",
   "customerAccountNumber": "0051762787",
   "customerAccountBankCode": "998",
   "mandateDescription": "Subscription Fee",
   "mandateStartDate": "2024-03-19T10:15:30",
   "mandateEndDate": "2025-01-19T10:15:30",
   "debitAmount": 1000,
   "mandateAmount": 10000
}

Closed Flexible

For closed flexible use case, you are informing Monnify that the mandate is for a predetermined duration and you intend to periodically charge the customer a variable amount.

You will need to set the "autoRenew", parameter to false while your predetermined end date is set in the mandateEndDate parameter and would also need to omit the "debitAmount" parameter as shown below

Sample Request

Code Block
languagejson
{
   "contractCode": "797854529434",
   "mandateReference": "test-18-03-24-10",
"customerAccountName   "autoRenew": false,
   "customerName": "Ankit Kushwaha",
   "customerPhoneNumber": "1234567890",
   "customerEmailAddress": "muhammad.sheraz@moniepoint.com",
   "customerAddress": "123 Example Street, City, Country",
   "customerAccountNumber": "0051762787",

   "customerAccountBankCode": "998",

   "mandateDescription": "Subscription Fee",
    "mandateStartDate": "2024-03-19T10:15:30",
    "mandateEndDate": "2025-01-19T10:15:30",
    "mandateAmount": 10000
}

Sample Response

Code Block
languagejson
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "responseMessage": "Mandate creation  is in progress",
        "mandateReference": "unique_ref3xx_02600972",
        "mandateCode": "MTDD|01HW2Q36KZGMXSWN7E76893V42",
        "mandateStatus": "PENDING"
    }
}

On successful mandate creation, an authorisation email will be sent to the customer’s email address to enable the customer authorise direct debit on his account. Once successfully authorised, merchant can periodically pass debits to the customer’s bank account till the mandate expires.

Field Parameters

Fields

Mandatory or Optional

Description

contractCode

M

The merchant’s Monnify contract code

mandateReference

M

Merchants generated reference to identify a mandate

customerName

M

Name of merchants customer

customerPhoneNumber

M

Phone number of merchants customer

customerEmailAddress

M

Email address of merchants customer

customerAddress

M

Location of merchants customer

accountNumber

M

Customers account number to create a mandate on

accountName

MO

Customers account name for the account to create a mandate on

bankCode

M

The bank code of the account number to create a mandate on

mandateAmount

M

Total lifetime amount debitable on the mandate.

mandateDescription

M

The description of the payment the mandate is associated to

autoRenew

O

This informs Monnify wether the mandate will be renewed once it reaches end date.

mandateStartDate

O

StartDate of Mandate: default to mandate creation date

mandateEndDate

O

EndDate of Mandate: default to mandate creation date

mandateCode

O

Monnify generated mandate identifier

mandateStatus

O

The status of the mandate in request: INITIATED, ACTIVE, CANCELED

mandateAuthorizationLink

O

3Ds link presented to customers for authorization flow returned when the status is requested

paymentReference

M

Merchants unique reference to identify a single direct debit payment

debitAmount

O

Payment amount to be debited from a single debit transaction

narration

M

Description of the single debit

...