1. Create a mandate
To initiate a mandate, you need to use the Mandate:Create API.
Be sure to check out the API recipe for a simple, step-by-step code example that walks you through the process and helps you get started with this API quickly.
1.1 API reference
The mandate:create API reference, including the option to execute real-time requests, can be found at:
https://developer.pay.nl/reference/post_directdebits-mandates#/
1.2 Authentication
Authentication occurs via Basic Authentication using:
Token code (AT-…) as the username and API token (hash of 40 characters) as the password or Service ID (SL-…) as the username and the secret as the password. You can find the Token code and the API token under the "Merchant" -> "Company information" tab in the PAY. Admin Panel.
You can find the Service ID and the secret under the tab "Settings" -> "Sales locations" in the PAY. Admin Panel. The Service ID is the unique reference of the sales location and starts with SL-… You can find the corresponding secret by clicking on the data icon of the relevant sales location. The secret, a 40- character hash, is displayed at the top of the popup.
1.3 Request
{
"serviceId": "SL-####-####",
"reference": "AX12345-TRA-6789",
"description": "gym membership",
"processDate": "2025-01-01",
"customer": {
"ipAddress": "213.126.82.230",
"email": "[email protected]",
"bankAccount": {
"iban": "NL69INGB0123456789",
"bic": "INGBNL2A",
"owner": "John Doe"
}
},
"amount": {
"value": 10,
"currency": "EUR"
},
"type": "SINGLE",
"stats": {
"info": "info1",
"tool": "tool1",
"extra1": "extra11",
"extra2": "extra21",
"extra3": "extra31",
"object": "object1"
}
}{
"serviceId": "SL-####-####",
"reference": "AX12345-TRA-6789",
"description": "gym membership",
"processDate": "2025-01-01",
"customer": {
"ipAddress": "213.126.82.230",
"email": "[email protected]",
"bankAccount": {
"iban": "NL69INGB0123456789",
"bic": "INGBNL2A",
"owner": "John Doe"
}
},
"amount": {
"value": 10,
"currency": "EUR"
},
"type": "RECURRING",
"interval": {
"period": "month",
"quantity": 12,
"value": 1
},
"stats": {
"info": "info1",
"tool": "tool1",
"extra1": "extra11",
"extra2": "extra21",
"extra3": "extra31",
"object": "object1"
}
}{
"serviceId": "SL-####-####",
"reference": "AX12345-TRA-6789",
"description": "gym membership",
"processDate": "2025-01-01",
"customer": {
"ipAddress": "213.126.82.230",
"email": "[email protected]",
"bankAccount": {
"iban": "NL69INGB0123456789",
"bic": "INGBNL2A",
"owner": "John Doe"
}
},
"amount": {
"value": 10,
"currency": "EUR"
},
"type": "FLEXIBLE",
"stats": {
"info": "info1",
"tool": "tool1",
"extra1": "extra11",
"extra2": "extra21",
"extra3": "extra31",
"object": "object1"
}
}1.4 Response
{
"code": "IO-####-####-####",
"serviceId": "SL-####-####",
"reference": "AX12345-TRA-6789",
"description": "gym membership",
"processDate": "2025-01-01",
"exchangeUrl": null,
"type": "RECURRING",
"interval": {
"value": 1,
"quantity": 12,
"period": "month"
},
"amount": {
"value": 4999,
"currency": "EUR"
},
"customer": {
"email": "[email protected]",
"ipAddress": "139.130.4.5",
"bankAccount": {
"iban": "NL69INGB0123456789",
"bic": "INGBNL2A",
"owner": "John Doe"
}
},
"service": {
"code": "SL-####-####",
"name": "Fictional Super Gym New York."
},
"merchant": {
"code": "M-####-####",
"name": "Fictional Super Gym.",
"status": "ACTIVE",
"incorporationCountry": "NL"
},
"stats": {
"info": "info1",
"tool": "tool1",
"object": "object1",
"extra1": "extra11",
"extra2": "extra21",
"extra3": "extra31",
"domainId": null
},
"lastDirectDebitDate": "2025-02-01T10:58:52+01:00",
"nextDirectDebitDate": "2025-02-01T10:58:52+01:00",
"actualDirectDebitDate": "2025-02-01T10:58:52+01:00",
"createdAt": "2025-01-01T01:58:52+00:00",
"createdBy": "AT-####-####",
"modifiedAt": "2025-01-01T01:58:52+00:00",
"modifiedBy": "AT-####-####",
"deletedAt": null,
"deletedBy": null,
"_links": [
{
"href": "\\/directdebits\\/mandates/IO-####-####-####",
"rel": "details",
"type": "GET"
},
{
"href": "\\/directdebits\\/mandates",
"rel": "self",
"type": "POST"
}
]
}1.5 Identifying the first DirectDebit from the mandate (DirectDebit:id)
To identify the first DirectDebits id(IL-), you need to check the Exchange call Incassopending. The returned payload will include the mandateId(IO) as the reference for the corresponding DirectDebit (IL). All available exchange calls for DirectDebits can be find here.
{
"action": "incassopending",
"pincode": "",
"website_location_id": "1",
"website_id": "1",
"program_id": "202521",
"promotor_id": "",
"tool": "tool",
"info": "info",
"object": "object",
"domain_id": "0",
"ip_address": "10.11.12.13",
"amount": "12.50",
"extra1": "",
"extra2": "",
"extra3": "",
"secret": "",
"enduser_id": "0",
"payment_session_id": "00000000000X0000",
"payment_profile_id": "10",
"product_id": "",
"payment_method_id": "4",
"order_id": "50101000003X34f0",
"incasso_id": "30749455",
"mandateId": "IO-1234-1234-1234",
"referenceId": "IL-1234-1234-1234"
}Important: a mandate is considered active only after the first DirectDebit has been successfully processed and the funds have been deducted from the customer’s bank account. All subsequent direct debits using this mandate depend on this initial successful transaction.
Updated 5 days ago