E-Mandates API
With the REST API for E-Mandates, you can create a legally-binding and automatically recurring payment mandate for the consumer very easily.
The Recurring Mandate flow in short:
- Create a new mandate and redirect the consumer to it.. (Create Method)
- The consumer reviews the Recurring Mandate and accepts it.
- The consumer is returned to you and you can verify the completion of the Recurring Mandate. (Check Method)
- Subsequent recurring payments are performed automatically by DigiWallet on a schedule chosen by you. Or, in case of a manual frequency, you control when to charge the mandate through the (Charge Method)
- You can terminate the Recurring Mandate at any time. (Terminate Method)
For more information and terms contact our sales team at sales@targetmedia.eu.
HTTP Bearer Authentication
This API requires HTTP Bearer authentication (Read more...) This means your requests to this API must always be accompanied by an HTTP header carrying your organization's API key to be accepted.
You can find your organization's unique API token in your Organization Dashboard.
An example of the HTTP header is as follows:
Authorization: Bearer 12a34bc5de67f8g9012345678
RESTful API
This is a RESTful API. This means the API follows the RESTful format for web services (Read more...)
The response format for these API's is in (JSON).
A typical response will be a JSON-encoded array with a status
integer to indicate whether the call was successful or not, and a message
string with a description of what happened.
Beyond these standard elements, an API can return API-specific information. e.g. transactionID
integer for the creation of a transaction. Or a nested errors
array
providing detailed validation errors.
The HTTP response codes of the RESTful API's follow the below logic:
HTTP Status Code | Used in response to |
---|---|
200 (Success) | A successfully processed request that also returns information |
201 (Created) | A successfully processed creation request |
202 (Accepted) | A successfully accepted job request |
400 (Bad Request) | Bad input parameters / validation errors |
401 (Unauthorized) | Bad credentials |
404 (Not Found) | Resource could not be found |
405 (Method Not Allowed) | Method is unsupported in the API |
500 (Internal Server Error) | A problem occurred at DigiWallet's servers |
Create Method Create new mandate request
To create a new mandate request, call the following API through HTTP POST
.
https://api.digiwallet.nl/emandates/mandate-request
With the following parameters (* = required):
Variable | Explanation | Example |
---|---|---|
outletID* |
The ID of the outlet on which you want to register the mandate. A DirectDebit contract must be configured on this outlet. |
12345 |
recurAmount* |
The amount of the subsequent automatic recurring payments in cents. Must be left blank in case the recurFrequency is set to "manual". |
5000 |
recurPayments |
The amount of subsequent automatic recurring payments that DigiWallet needs to perform before the Recurring Mandate is automatically terminated. Leaving this field empty means that the Recurring Mandate does not have a specified lifetime and will run until otherwise terminated. |
5 |
recurFrequency* |
The frequency at which the subsequent automatic recurring payments should be executed. This means that one payment will be executed per (whatever this is set to). The available options are:
* A mandate with manual frequency is not automatically billed by DigiWallet. Instead, it can be billed manually through a separate API call, please refer to the chapter detailing the (Charge Method) |
month |
recurFrequencyUnit* |
The moment that the subsequent automatic recurring payments should be executed. This is in relation to the recurFrequency. Must be left blank in case the recurFrequency is set to "manual" or "day". For more detailed information, please refer to chapter detailing the (Recurrence Frequency) |
25 |
recurDelay* |
The grace period between the initial transaction and the subsequent automatic recurring payments. This is in relation to the recurFrequency. For example if the recurFrequency is month this will add a 1 month delay before the first recurring payment. Setting this to 0 means no grace period is utilized. Use this when your consumer subscribes too closely to your regular billing day, or when you want to give them a promotional offer. |
1 |
description* | Description for the consumer's bank statement. | Subscription to My Magazine |
returnURL* |
The location where your consumer will be returned to after confirming the E-Mandate. A GET parameter will be appended to this redirection: mandateRequestID Example: https://www.myshop.nl/thankYouPage?mandateRequestID=30626804185492 |
https://www.myshop.nl/thankYouPage |
cancelURL |
The location where your consumer will be returned to when they decline the mandate. A GET parameter will be appended to this redirection: mandateRequestID Example: https://www.myshop.nl/cancelPage?mandateRequestID=30626804185492 If left blank, the returnURL will be used in place of the cancelURL. |
https://www.myshop.nl/cancelPage |
reportURL |
The server handler that is called when the mandate request changes status or when a payment under the mandate is executed. This request is performed by means of HTTP POST .Use requests to this handler as a cue to call the relevant Check Method. The parameters provided when a mandate request changes status are:
The parameters provided when a mandate is created (happens at the same time as the request is finalized) or terminated:
Please utilize the relevant Check Method, either for the mandate request or the subsequent transactions, to verify the authenticity of the reportURL callback. |
https://www.myshop.nl/reportMandate |
consumerIP* | IP address of the consumer. | 213.76.8.33 |
consumerEmail |
E-Mail address of the consumer. If provided, will be used to send confirmations to the consumer when accepting the mandate and executing recurring payments. |
test@example.com |
test |
Whether to use the test-mode or not. When using the test connection, no real money will be charged. Note that when you have your outlet set to test-mode through the DigiWallet Dashboard, this parameter will be forced to 1. Remember to turn off this option when the site goes live. The default is, test mode off. |
"1" or "0" |
You will then get a JSON-encoded array response with the following content:
Key | Value |
---|---|
status | 0 |
message | E-Mandate request successfully created |
message | Mandate request successfully created |
mandateRequestID | ID of the created request |
launchURL | URL to redirect your consumer to |
Example raw response
{"status":0,"message":"E-Mandate request successfully created","mandateRequestID":12345,"launchURL":"http://pay.digiwallet.nl/consumer/directdebit-mandate/launch-emandate/50/1d84e48f-9afa-11e8-85c4-b8ca3a793886/0"}
You can now save the mandateRequestID
in your database and redirect your consumer to the launchURL
.
In case of one or more errors, you will get a JSON-encoded array response with the following content:
Key | Value | ||||||
---|---|---|---|---|---|---|---|
status | 1 | ||||||
message | Validation failed | ||||||
errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"recurAmount":["Amount too low, the minimum is set to: 49 - 25 given."],"description":["Description cannot be blank."]}}
Recurrence Frequency Payment scheduling
Because DigiWallet performs the recurring payments automatically for you, this section is dedicated to clarifying how that works.
About the recurFrequencyUnit parameter:
-
When recurFrequency is set to
year
: then the recurFrequencyUnit parameter is the day of the year (1-365). *** -
When recurFrequency is set to
month
: then the recurFrequencyUnit parameter is the day of the month (1-31). * -
When recurFrequency is set to
week
: then the recurFrequencyUnit parameter is the day of the week (1-7). ** -
When recurFrequency is set to
day
: then the recurFrequencyUnit parameter is blank, as it is not required. -
When recurFrequency is set to
manual
: then the recurFrequencyUnit parameter is blank, as it is not required.
Any subsequent payments after that are scheduled normally again.
** For a week frequency, you may specify the day of the week. Please find the numeric equivalents of the day of the week below:
*** Please note that because there is a mandatory waiting time of two days in SEPA DirectDebit, we send the DirectDebit to the bank two days in advance of your chosen payment date. Processing delays at the bank as well as special holidays could cause the transaction to be debited slightly earlier or later, so please plan your schedule with some flexibility.
recurFrequencyUnit | Weekday |
---|---|
1 | Sunday |
2 | Monday |
3 | Tuesday |
4 | Wednesday |
5 | Thursday |
6 | Friday |
7 | Saturday |
Check Method Check mandate request
To check the status of the mandate request, call the following API through HTTP GET
.
https://api.digiwallet.nl/emandates/mandate-request/<outletID>/<mandateRequestID>[/<test>]
The query string parameters are defined as follows (* = required):
Variable | Explanation | Example |
---|---|---|
outletID* | The ID of the outlet on which mandate request was registered. | 39995534 |
mandateRequestID* | The ID of the original mandate request. | 12345678 |
test |
If you have started the transaction in test-mode, call the Check API in test-mode as well. Otherwise your transaction will not be found. Note that when you have your outlet set to test-mode through the DigiWallet Dashboard, this parameter will be forced to 1. Remember to turn off this option when the site goes live. The default is, test mode off. |
1 |
You will then get a JSON-encoded array response with the following content:
Key | Value |
---|---|
status | 0 |
message | Mandate request successfully checked |
mandateRequestStatus |
Current status of the mandate request, options as follows:
|
mandateID |
This field is only present when the mandateRequestStatus is Finalized For example: 54321 |
Example raw response
{"status":0,"message":"Mandate request successfully checked","mandateRequestStatus":"Finalized","mandateID":54321}
In case of one or more errors, you will get a JSON-encoded array response with the following content:
Key | Value | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"mandateRequestID":["There is no mandate request for this ID."]}}
Multiple Signatures Corporate bank accounts
Corporate bank accounts are subject to a secondary signing requirement. This means that after the consumer has finalized the E-Mandate inside the acceptance flow, they still need to separately log in to their online banking environment and accept the mandate again there.
The Pending
status is only returned in this particular case. The E-Mandate will then remain in that status until the consumer finishes the multiple signatures process. DigiWallet checks for this status update periodically and will automatically send you a reportURL callback when the mandate is finalized.
If E-Mandate remains in a Pending state for more than 7 days, it automatically enters the Expired state.
Check Method Check mandate
To check the status of the mandate, call the following API through HTTP GET
.
https://api.digiwallet.nl/emandates/mandate/<outletID>/<mandateID>[/<test>]
The query string parameters are defined as follows (* = required):
Variable | Explanation | Example |
---|---|---|
outletID* | The ID of the outlet on which the original mandate request was registered. | 39995534 |
mandateID* | The ID of the mandate generated through a mandate request. | 12345678 |
test |
If you have started the mandate in test-mode, call the Check API in test-mode as well. Otherwise your mandate will not be found. Note that when you have your outlet set to test-mode through the DigiWallet Dashboard, this parameter will be forced to 1. Remember to turn off this option when the site goes live. The default is, test mode off. |
1 |
You will then get a JSON-encoded array response with the following content:
Key | Value |
---|---|
status | 0 |
message | Mandate successfully checked |
mandateStatus |
Current status of the mandate, options as follows:
|
Example raw response
{"status":0,"message":"Mandate successfully checked","mandateStatus":"Active"}
In case of one or more errors, you will get a JSON-encoded array response with the following content:
Key | Value | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}
Terminate Method Terminate active mandate
To terminate an active mandate, call the following API through HTTP DELETE
.
https://api.digiwallet.nl/emandates/mandate/<outletID>/<mandateID>[/<test>]
The query string parameters are defined as follows (* = required):
Variable | Explanation | Example |
---|---|---|
outletID* | The ID of the outlet on which the original mandate request was registered. | 39995534 |
mandateID* | The ID of the mandate generated through a mandate request. | 12345678 |
test |
If you have started the mandate in test-mode, call the Terminate API in test-mode as well. Otherwise your mandate will not be found. Note that when you have your outlet set to test-mode through the DigiWallet Dashboard, this parameter will be forced to 1. Remember to turn off this option when the site goes live. The default is, test mode off. |
1 |
You will then get a JSON-encoded array response with the following content:
Key | Value |
---|---|
status | 0 |
message | Mandate successfully terminated |
mandateStatus |
New status of the mandate, options as follows:
|
Example raw response
{"status":0,"message":"Mandate successfully terminated","mandateStatus":"Terminated"}
In case of one or more errors, you will get a JSON-encoded array response with the following content:
Key | Value | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}
Charge Method Charge a manual mandate
Only manual frequency mandates can be charged through the Charge Method. Performing a charge takes the information stored in the mandate and creates a DirectDebit transaction.
The reportURL parameter of the original mandate request is also passed on to the DirectDebit transaction. The parameters provided in this callback are the same as in the regular (One-Off DirectDebit API).
Note that beause of the nature of SEPA DirectDebit transations, the regular processing time of 2 working days applies.
To charge an active mandate, call the following API through HTTP POST
.
https://api.digiwallet.nl/emandates/mandate/charge
With the following parameters (* = required):
Variable | Explanation | Example |
---|---|---|
outletID* | The ID of the outlet on which the original mandate request was registered. | 39995534 |
mandateID* | The ID of the mandate generated through a mandate request. | 12345678 |
chargeAmount* | The amount of the manual charge in cents. | 500 |
test |
If you have started the mandate in test-mode, call the Charge API in test-mode as well. Otherwise your mandate will not be found. Note that when you have your outlet set to test-mode through the DigiWallet Dashboard, this parameter will be forced to 1. Remember to turn off this option when the site goes live. The default is, test mode off. |
1 |
You will then get a JSON-encoded array response with the following content:
Key | Value |
---|---|
status | 0 |
message | Mandate successfully charged |
transactionID | ID of the created DirectDebit transaction, e.g.: 12345 |
transactionStatus |
Status of the created DirectDebit transaction, will always be:
|
Example raw response
{"status":0,"message":"Mandate successfully charged","transactionID":12345,"transactionStatus":"Open"}
In case of one or more errors, you will get a JSON-encoded array response with the following content:
Key | Value | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}