Create A Mandate

To create a mandate on Monnify, you’ll need to call the create mandate endpoint, see specifications below(remember to also add the authentication header).

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

HTTP Method: POST

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

Sample Request

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

Sample Response

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "responseMessage": "Your request for creating a mandate is submitted. An authorization instruction will be sent to the customer email.",
        "mandateReference": "unique_ref3xx_02600972",
        "mandateCode": "MTDD|01HW2Q36KZGMXSWN7E76893V42",
        "mandateStatus": "INITIATED"
    }
}

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

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	M	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
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
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