Recurring CreditCard API

With the REST API for Recurring CreditCard, you can create an automatically recurring payment mandate for the consumer very easily.

The Recurring Mandate flow in short:

  1. Create a new mandate and redirect the consumer to it.. (Create Method)
  2. The consumer reviews the Recurring Mandate and accepts it.
  3. The consumer is redirected to an initial CreditCard transaction to verify the Recurring Mandate.
  4. Completing this initial CreditCard transaction automatically confirms the Recurring Mandate.
  5. The consumer is returned to you and you can verify the completion of the Recurring Mandate. (Check Method)
  6. 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)
  7. You can terminate the Recurring Mandate at any time. (Terminate Method)

By default, Creditcard is not enabled for your account.
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/creditcard/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 CreditCard contract must be configured on this outlet.
12345
currencyCode Currency code according to ISO 4217
Default value is: EUR
The given currency must be supported in your CreditCard contract.
EUR
initialAmount* The amount of the initial verification transaction in cents. 5000
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:

  • year: Yearly
  • month: Monthly
  • week: Weekly
  • day: Daily
  • manual: Manual*

* 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 performing the initial CreditCard transaction.
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:

  • eventType: The event that caused this callback to be sent out, options are:
    • mandateRequestCreated The request was created
    • mandateRequestAccepted The consumer has accepted the request
    • mandateRequestDeclined The consumer has declined the request
    • mandateRequestFailed The initial CreditCard transaction failed
    • mandateRequestFinalized The request was finalized into an active mandate
    • mandateRequestExpired The request expired after a period of inactivity
  • mandateRequestID: The ID of the mandate request that this request is about.
  • eventDateTime: The date and time that this event occurred, format: YYYY-MM-DD HH:MM:SS.

The parameters provided when a mandate is created (happens at the same time as the request is finalized) or terminated:

  • eventType: The event that caused this callback to be sent out, options are:
    • mandateCreated The request was finalized and the mandate created
    • mandateTerminated The mandate was terminated
  • mandateID: The ID of the mandate that this request is about.
  • mandateRequestID: The ID of the original mandate request that this callback is about.
  • eventDateTime: The date and time that this event occurred, format: YYYY-MM-DD HH:MM:SS.
The parameters provided when the initial CreditCard transaction or subsequent automatic recurring payments are executed are the same as in the regular (One-Off CreditCard API).

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 Mandate request successfully created
mandateRequestID ID of the created request
launchURL URL to redirect your consumer to

Example raw response

{"status":0,"message":"Mandate request successfully created","mandateRequestID":12345,"launchURL":"http://pay.digiwallet.nl/consumer/creditcard-mandate/launch/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 the mandate request enters a Failed status (meaning the consumer cancelled or otherwise failed their initial CreditCard transaction), this does not immediately end the mandate request lifecycle.

Whenever a problem occurs with the initial transaction, the consumer is brought back to the mandate overview first.

From there they can either choose to try again, sending the mandate into an Accepted status again or decline the mandate.

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

Key Value
initialAmount Amount too low, the minimum is set to: 49 - 25 given.
description Description cannot be blank.

Example raw response

{"status":1,"message":"Validation failed","errors":{"initialAmount":["Amount too low, the minimum is set to: 49 - 25 given."],"description":["Description cannot be blank."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

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.
* If for a month frequency you specify a day of the month that does not exist for a particular month, your payment will be executed on the last day of that month. They will not flow over into the next month.

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:

recurFrequencyUnit Weekday
1 Sunday
2 Monday
3 Tuesday
4 Wednesday
5 Thursday
6 Friday
7 Saturday
*** You are correct that a leap-year shift for the year frequency is not supported. Are you looking for a job?

Check Method Check mandate request

To check the status of the mandate request, call the following API through HTTP GET.

https://api.digiwallet.nl/creditcard/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 1
message Mandate request successfully checked
mandateRequestStatus Current status of the mandate request, options as follows:
  • Open
  • Declined
  • Accepted
  • Failed
  • Finalized
  • Expired
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

Key Value
mandateRequestID There is no mandate request for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"mandateRequestID":["There is no mandate request for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

Check Method Check mandate

To check the status of the mandate, call the following API through HTTP GET.

https://api.digiwallet.nl/creditcard/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 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 successfully checked
mandateStatus Current status of the mandate, options as follows:
  • Active
  • Terminated

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

Key Value
mandateID There is no mandate for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

Terminate Method Terminate active mandate

To terminate an active mandate, call the following API through HTTP DELETE.

https://api.digiwallet.nl/creditcard/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 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 successfully terminated
mandateStatus New status of the mandate, options as follows:
  • Terminated

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

Key Value
mandateID There is no mandate for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

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, creates a CreditCard transaction and executes it immediately.

The reportURL parameter of the original mandate request is also passed on to the CreditCard transaction. The parameters provided in this callback are the same as in the regular (One-Off CreditCard API).

To charge an active mandate, call the following API through HTTP POST.

https://api.digiwallet.nl/creditcard/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 CreditCard transaction, e.g.: 12345
transactionStatus Status of the created CreditCard transaction, will be one of:
  • Success
  • Failed
acquirerResponseCode External status code, e.g. 00
acquirerMessage Textual representation of the status code, e.g. "Payment accepted"

Example raw response

{"status":0,"message":"Mandate successfully charged","transactionID":12345,"transactionStatus":"Success","acquirerResponseCode":"00","acquirerMessage":"Payment accepted"}


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

Key Value
mandateID There is no mandate for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"mandateID":["There is no mandate for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.