AutoCollect

Introduction

The AutoCollect API is for customers who wants to be in charge of their scheduled payments. Set up a payment plan, link payment periods to it and attach your debtors. After this AutoCollect will suffice the payments over the set up periods and will notify when a payment is successful.

Currently it is possible to handle payments via a direct debit without interaction with the debtor, or via iDEAL where a link is send to the debtor's e-mail or phonenumber.

1.1 Version control

Version Author Date Status
0.1.0 (Alpha) MaV 2017-01-25 Initial version.
0.2.0 (Alpha) MaV 2017-03-14 Added error codes.

1.2 Connectivity

The URL to be used is: https://autocollectapi.cmpayments.com/

1.3 Definition

In this documentation we will describe the following entities:

  1. Check out

    Container with information of a product that is desired to be paid for by a debtor.

  2. Debtor

    Person who is charged by the merchant for a given amount over a given set of periods.

  3. Group

    In the dashboard multiple debtors are shown via a group view. A group needs to consist at least one debtor.

  4. Payment plan

    A plan of how a group must be handled. Here can be described what the first payment method is. Or when the first period is taking place and what the interval for follow-up periods is.

  5. Period

    Date and time of when a transaction should take place for a given debtor. The relationship between a debtor and a period is one-to-many, and needs to be present when creating a new debtor.

  6. Transaction

    Container with information of the owed amount that should be paid by an end-user during one period.

  7. Transaction payment

    Container with information over a payment attempt for a linked transaction. Note: There can be multiple payments linked to one transaction, but only one payment can be successful.

2 Payment plans

This chapter given an overview of all requests to create or retrieve details of payment plans.

2.1 Create a monthly payment plan

It is possible to set up a payment plan, where each month a period is started. Create one payment plan by calling the following URL via the HTTP-POST method.
POST /v1.0/payment-plans

2.1.1 Request

Name Level Format Length Mandatory Description
period_type 1 String 7 Yes The type of the period.
  • Possible value is Monthly.
first_period_year 1 Integer 4 No Number of the year the first period must take place.
  • When left out of the request, the best first possible year is selected.
first_period_month 1 Integer 2 No Number of the month the first period must take place.
  • When left out of the request, the first period is when the first transaction via a check-out or debtor is made.
first_period_day 1 Integer 2 No Number of the day the first period must take place.
  • When left out of the request, the best possible day, depending on the payment method, is selected.
number_of_periods 1 Integer 1 Yes The total number of periods.
  • When the total amount is 100 and there are four period dates, each transaction will have an amount of 25.
periods 1 Array - Yes List of payment periods.
payments 2 Array - Yes List of payment methods and the sequences they are used in.
  • It cannot contain zero items.
payment_method 3 String 11 Yes Method of the transaction payment
  • Possible values are DirectDebit, iDEAL.
delivery_method 3 String 5 No Method of how the payment notification is delivered to the debtor.
  • Possible values are Email, SMS.
  • Must be NULL or left out of the request for the payment method DirectDebit.
delivery_time 3 Time 5 No Time when the payment notification needs to be delivered.
  • Requires the time format hh:mm.
  • Where hh is the number of complete hours (00 - 23).
  • Where mm is the number of complete minutes (00 - 59).
  • Must be NULL or left out of the request for the payment method DirectDebit.

2.1.2 Response

After a successful request, the HTTP status code 201 Created will be returned.

Name Level Format Length Description
payment_plan_id 1 String 40 Unique identifier of the payment plan.
period_type 1 String 7 The type of the period.
  • Possible value is Manually , Monthly.
number_of_periods 1 Integer 1 The total number of periods.
  • When the total amount is 100 and there are four period dates, each transaction will have an amount of 25.
periods 1 Array - List of payment periods.
period_date 2 Date 10 Date of the payment period.
  • Can be NULL when no starting period or month is given at the request
payments 2 Array - List of payments in the sequences of follow-up.
  • E.g. the first value in the array is the method of the payment’s first attempt. The second is the method of the first follow-up payment after the original attempt has failed.
payment_method 3 String 11 Method of the payment
  • Possible values are DirectDebit, iDEAL.
delivery_method 3 String 5 Method of how the payment notification is delivered to the debtor.
  • Possible values are Email, SMS.
  • Is NULL when the payment method does not support the delivery of the payment notification.
delivery_time 3 Time 5 Time when the payment notification needs to be delivered.
  • Requires the time format hh:mm.
  • Where hh is the number of complete hours (00 - 23).
  • Where mm is the number of complete minutes (00 - 59).
  • Is NULL when the payment method does not support the delivery of the payment notification.
2.2 Create a payment plan with specified dates

It is possible to set up a payment plan, where the period dates are pre-defined by the merchant. Create one payment plan by calling the following URL via the HTTP-POST method.
POST /v1.0/payment-plans
2.2.1 Request
Name Level Format Length Mandatory Description
period_type 1 String 7 Yes The type of the period.
  • Possible value is Manually.
number_of_periods 1 Integer 1 Yes The total number of periods.
  • When the total amount is 100 and there are four period dates, each transaction will have an amount of 25.
periods 1 Array - Yes List of payment periods.
period_date 2 Date 10 Yes Date of the payment period.
payments 2 Array - Yes List of payment methods and the sequences they are used in.
  • It cannot contain zero items.
payment_method 3 String 11 Yes Method of the transaction payment
  • Possible values are DirectDebit, iDEAL.
delivery_method 3 String 5 No Method of how the payment notification is delivered to the debtor.
  • Possible values are Email, SMS.
  • Must be NULL or left out of the request for the payment method DirectDebit.
delivery_time 3 Time 5 No Time when the payment notification needs to be delivered.
  • Requires the time format hh:mm.
  • Where hh is the number of complete hours (00 - 23).
  • Where mm is the number of complete minutes (00 - 59).
  • Must be NULL or left out of the request for the payment method DirectDebit.
2.2.2 Response

After a successful request, the HTTP status code 201 Created will be returned. See chapter 2.1.2 for the response parameters.

2.3 Retrieve all payment plans

Retrieve all existing payment plans by calling the following URL via HTTP-GET method.
GET /v1.0/payment-plans
2.3.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 2.1.2 for the response parameters.

2.4 Retrieve a payment plan

Retrieve an existing payment plan by calling the following URL via HTTP-GET method. The last parameter in the URL is the identifier of the payment plan.
GET /v1.0/payment-plans/APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1
2.4.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 2.1.2 for the response parameters.

3 Groups

This chapter gives an overview of all the requests to create or retrieve details of a group.

3.1 Creating a group

Create one group by calling the following URL via the HTTP-POST method.
POST /v1.0/groups
3.1.1 Request
Name Level Format Length Mandatory Description
reference 1 String 255 Yes Own reference of the group.
  • Reference is not mandatory to be unique within AutoCollect.
payment_plan_id 1 String 40 Yes Unique identifier of an existing payment plan.
transaction_fee 1 Decimal 6,2 No Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
  • When left NULL, the transaction fee on merchant level is used.
currency 1 String 3 Yes Currency for each transaction.
  • Possible value is EUR.
locale 1 String 5 Yes Preferred language and region setting, in an ISO15897 format.
page_content_settings 1 Object 1 No Object with content settings used within the payment page.
  • Can be left out of the request to use the default settings.
title 2 String 100 No Title of the payment page.
  • Can be NULL or left out of the request to use the default settings.
content 2 String - No Content to inform the debtor about the payment.
  • Can be NULL or left out of the request to use the default settings.
product_description 2 String 100 No Description of the product.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
  • Can be NULL or left out of the request to use the default settings.
header_color 2 String 7 No Hexadecimal value of a color used for the headers within the payment page.
  • Can be NULL or left out of the request to use the default settings.
button_color 2 String 7 No Hexadecimal value of a color used for the buttons within the payment page.
  • Can be NULL or left out of the request to use the default settings.
logo_url 2 String - No URL of the merchant’s own logo.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL or left out of the request to show no logo on the check out or follow-up payment pages.
redirect_url 2 String - No URL of the merchant where the debtor is going to be redirected.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL or left out of the request when no redirect is required/possible.
payment_content_settings 1 Object 1 No Object with content settings used within the payments.
  • Can be left out of the request to use the default settings.
description 2 String 35 No Summary description of the payment displayed on the debtor’s bank account.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
  • Can be NULL or left out of the request to use the default settings.
mail_content_settings 1 Object 1 No Object with content settings used within the mail follow-up messages.
  • Can be left out of the request to use the default settings.
title 2 String - No Title of the follow-up mail.
  • Can be NULL or left out of the request to use the default settings.
content 2 String - No Content of the follow-up mail, to remind the debtor about an unpaid payment.
  • Can be NULL or left out of the request to use the default settings.
sms_content_settings 1 Object 1 No Object with content settings used within the SMS follow-up messages.
  • Can be left out of the request to use the default settings.
sender 2 String 11 No Sender of the SMS follow-up message.
  • Can be left out of the request to use the default settings.
content 2 String - No Content of the follow-up SMS, to remind the debtor about an unpaid payment.
  • Can be NULL or left out of the request to use the default settings.
debtors 1 Array - No List of debtors.
  • Can be left out the requst when the need is to add debtors at a later stage.
reference 2 String 255 Yes Own unique reference of the debtor.
name 2 String 255 No Name of the debtor.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
iban 2 String 34 No IBAN of the debtor.
  • Can be NULL when a valid phone number is present and the no_direct_debit tag is one.
bic 2 String 50 No BIC of the given IBAN.
phone_number 2 String 13 No Phone number of the debtor, in an ISO20022 format.
  • Can be NULL when a valid IBAN is given.
email 2 String 255 No Email address of the debtor
currency 2 String 3 No Currency for each transaction.
  • Possible value is EUR.
locale 2 String 5 No Preferred language and region setting, in an ISO15897 format.
total_amount 2 Decimal 6,2 Yes Total amount that needs to be collected from the debtor.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
no_direct_debit 2 Boolean 5 No TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
  • When leaving this tag out of the request, the default value FALSE will be used.
3.1.2 Response

After a successful request, the HTTP status code 201 OK will be returned.

Name Level Format Length Description
group_id 1 String 40 Unique identifier of the group.
payment_plan_id 1 String 40 Unique identifier of the payment plan.
reference 1 String 255 Own reference of the group.
  • Reference is not mandatory to be unique within AutoCollect.
transaction_fee 1 Decimal 6,2 Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
  • Can be NULL when no value was given at the create request.
currency 1 String 3 Currency for each transaction.
  • Possible value is EUR.
locale 2 String 5 Preferred language and region setting, in an ISO15897 format.
number_of_debtors 1 Integer 10 Number of debtors linked to the group.
page_content_settings 1 Object 1 Object with settings used within the payment page.
  • Is NULL when no settings are set.
title 2 String 100 Title of the payment page.
content 2 String - Content to inform the debtor about the payment.
product_description 2 String 100 Description of the product.
header_color 2 String 7 Hexadecimal value of a color used for the headers within the payment page.
button_color 2 String 7 Hexadecimal value of a color used for the buttons within the payment page.
logo_url 2 String - URL of the merchant’s own logo.
redirect_url 2 String - URL of the merchant where the debtor is going to be redirected.
payment_content_settings 1 Object 1 Object with content settings used within the payments.
  • Is NULL when no settings are set.
description 2 String - Summary description of the payment displayed on the debtor’s bank account.
mail_content_settings 1 Object 1 Object with content settings used within the mail follow-up messages.
  • Is NULL when no settings are set.
title 2 String 100 Title of the follow-up e-mail.
content 2 String - Content of the follow-up e-mail, to remind the debtor about an unpaid payment.
sms_content_settings 1 Object 1 Object with content settings used within the SMS follow-up messages.
sender 2 String 11 Sender of the SMS follow-up message.
content 2 String - Content of the follow-up SMS, to remind the debtor about an unpaid payment.
3.2 Retrieve all groups

Retrieve all existing groups by calling the following URL via HTTP-GET method.
GET /v1.0/groups
3.2.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 3.1.2 for the response parameters.

3.3 Retrieve a group

Retrieve an existing group by calling the following URL via HTTP-GET method. The last parameter in the URL is the identifier of the group.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B
3.3.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 3.1.2 for the response parameters.

4 Check outs

This chapter gives an overview of all the existing requests to create or retrieve details of a checkout.

4.1 Create a check out

Create one check out by calling the following URL via the HTTP-POST method.
POST /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/check-outs
4.1.1 Request
Name Level Format Length Mandatory Description
payment_plan_id 1 String 40 No Unique identifier of an existing payment plan.
  • Can be NULL or left out of the request to use the group settings.
reference 1 String 255 Yes Own unique reference of the debtor.
name 1 String 255 No Name of the debtor.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
iban 1 String 34 No IBAN of the debtor.
bic 1 String 50 No BIC of the given IBAN.
phone_number 1 String 13 No Phone number of the debtor, in an ISO20022 format.
email 1 String 255 No Email address of the debtor.
currency 1 String 3 No Currency for each transaction.
  • Possible value is EUR.
locale 1 String 5 No Preferred language and region setting, in an ISO15897 format.
total_amount 1 Decimal 6,2 Yes Total amount that needs to be collected from the debtor.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
transaction_fee 1 Decimal 6,2 No Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
  • When left NULL, the transaction fee of the group is used.
page_content_settings 1 Object 1 No Object with content settings used within the payment page.
  • Can be left out of the request to use the group settings.
title 2 String 100 No Title of the payment page.
  • Can be NULL or left out of the request to use the group settings.
content 2 String - No Content to inform the debtor about the payment.
  • Can be NULL or left out of the request to use the group settings.
product_description 2 String 100 No Description of the product.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
  • Can be NULL or left out of the request to use the group settings.
header_color 2 String 7 No Hexadecimal value of a color used for the headers within the payment page.
  • Can be NULL or left out of the request to use the group settings.
button_color 2 String 7 No Hexadecimal value of a color used for the buttons within the payment page.
  • Can be NULL or left out of the request to use the group settings.
logo_url 2 String - No URL of the merchant’s own logo.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL or left out of the request to show no logo on the check out or follow-up payment pages.
redirect_url 2 String - No URL of the merchant where the debtor is going to be redirected.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL or left out of the request when no redirect is required/possible.
4.1.2 Response

After a successful request, the HTTP status code 201 Created will be returned.

Name Level Format Length Description
check_out_id 1 String 40 Unique identifier of the check out.
group_id 1 String 40 Unique identifier of an existing group.
payment_plan_id 1 String 40 Unique identifier of an existing payment plan.
reference 1 String 255 Own unique reference of the debtor.
name 1 String 255 Name of the debtor.
iban 1 String 34 IBAN of the debtor.
bic 1 String 50 BIC of the given IBAN.
phone_number 1 String 13 Phone number of the debtor, in an ISO20022 format.
email 1 String 255 Email address of the debtor.
currency 1 String 3 Currency for each transaction.
  • Possible value is EUR.
locale 1 String 5 Preferred language and region setting, in an ISO15897 format.
total_amount 1 Decimal 6,2 Total amount that needs to be collected from the debtor.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
transaction_fee 1 Decimal 6,2 Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
page_content_settings 1 Object 1 Object with settings used within the payment page and possible follow-up messages.
  • Is NULL when no settings are set.
title 2 String 100 Title of the payment page.
content 2 String - Content to inform the debtor about the payment.
product_description 2 String 100 Description of the product.
header_color 2 String 7 Hexadecimal value of a color used for the headers within the payment page.
button_color 2 String 7 Hexadecimal value of a color used for the buttons within the payment page.
logo_url 2 String - URL of the merchant’s own logo.
redirect_url 2 String - URL of the merchant where the debtor is going to be redirected.
check_out_url 1 String 255 URL of the check out page.
4.2 Retrieve all check outs

Retrieve all check outs linked to a specific group, by calling the following URL via the HTTP-GET method. The second-last parameter in the URL is the identifier of the group.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/check-outs
4.2.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 4.1.2 for the response parameters.

4.3 Retrieve a check-out

Retrieve an existing check out by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the check out.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/check-outs/ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3
4.3.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 4.1.2 for the response parameters.

5 Debtors

This chapter gives an overview of all the existing requests to create or retrieve details of a debtor.

5.1 Create a or multiple debtors

Create one or multiple debtors by calling the following URL via the HTTP-POST method. The second-last parameter in the URL is the identifier of the group.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/debtors
5.1.1 Request
Name Level Format Length Mandatory Description
payment_plan_id 1 String 40 No Unique identifier of an existing payment plan.
  • Can be NULL or left out of the request to use the group settings.
reference 1 String 255 Yes Own unique reference of the debtor.
name 1 String 255 No Name of the debtor.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
iban 1 String 34 No IBAN of the debtor.
  • Can be NULL when a valid phone number is present and the no_direct_debit tag is one.
bic 1 String 50 No BIC of the given IBAN.
phone_number 1 String 13 No Phone number of the debtor, in an ISO20022 format.
  • Can be NULL when a valid IBAN is given.
email 1 String 255 No Email address of the debtor.
currency 1 String 3 No Currency for each transaction.
  • Possible value is EUR.
locale 1 String 5 No Preferred language and region setting, in an ISO15897 format.
total_amount 1 Decimal 6,2 Yes Total amount that needs to be collected from the debtor.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
transaction_fee 1 Decimal 6,2 No Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
  • When left NULL, the transaction fee of the group is used.
no_direct_debit 2 Boolean 5 Yes TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
  • When leaving this tag out of the request, the default value FALSE will be used.
page_content_settings 1 Object 1 No Object with settings used within the payment page.
  • Can be left out of the request to use the group settings.
title 2 String 100 No Title of the payment page.
  • Can be NULL or left out of the request to use the group settings.
content 2 String - No Content to inform the debtor about the payment.
  • Can be NULL or left out of the request to use the group settings.
product_description 2 String 100 No Description of the product.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
  • Can be NULL or left out of the request to use the group settings.
header_color 2 String 7 No Hexadecimal value of a color used for the headers within the payment page.
  • Can be NULL or left out of the request to use the group settings.
button_color 2 String 7 No Hexadecimal value of a color used for the buttons within the payment page.
  • Can be NULL or left out of the request to use the group settings.
logo_url 2 String - No URL of the merchant’s own logo.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL to show no logo on the check out or follow-up payment pages.
  • When left out the request, the group setting is used.
redirect_url 2 String - No URL of the merchant where the debtor is going to be redirected.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • Can be NULL when no redirect is required/possible.
  • When left out the request, the group setting is used.
5.1.2 Response

After a successful request, the HTTP status code 201 Created will be returned.

Name Level Format Length Description
debtor_id 1 String 40 Unique identifier of the debtor.
group_id 1 String 40 Unique identifier of the group.
payment_plan_id 1 String 40 Unique identifier of the payment plan.
reference 1 String 255 Own unique reference of the debtor.
name 1 String 255 Name of the debtor.
iban 1 String 34 IBAN of the debtor.
  • Can be NULL when a valid phone number is present and the no_direct_debit tag is one.
bic 1 String 50 BIC of the given IBAN.
phone_number 1 String 13 Phone number of the debtor, in an ISO20022 format.
  • Can be NULL when a valid IBAN is given.
email 1 String 255 Email address of the debtor
currency 1 String 3 Currency for each transaction.
  • Possible value is EUR.
locale 2 String 5 Preferred language and region setting, in an ISO15897 format.
total_amount 1 Decimal 6,2 Total amount that needs to be collected from the debtor.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
transaction_fee 1 Decimal 6,2 Amount of the fee per transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
no_direct_debit 1 Boolean 5 TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
  • When leaving this tag out of the request, the default value FALSE will be used.
page_content_settings 1 Object 1 Object with settings used within the payment page and possible follow-up messages.
  • Is NULL when no settings are set.
title 2 String 100 Title of the payment page.
content 2 String - Content to inform the debtor about the payment.
product_description 2 String 100 Description of the product.
header_color 2 String 7 Hexadecimal value of a color used for the headers within the payment page.
button_color 2 String 7 Hexadecimal value of a color used for the buttons within the payment page.
logo_url 2 String - URL of the merchant’s own logo.
redirect_url 2 String - URL of the merchant where the debtor is going to be redirected.
5.2 Retrieve all debtors

Retrieve all debtors linked to a specific group, by calling the following URL via the HTTP-GET method. The second-last parameter in the URL is the identifier of the group.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/debtors
5.2.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.

5.3 Retrieve a debtor

Retrieve an existing debtor by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the debtor.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/debtors/ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3
5.3.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.

5.4 Update a debtor

Update several parts of an existing debtor by calling the following URL via the HTTP-PATCH method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the debtor.
PATCH /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/debtors/ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3
5.4.1 Request
Name Level Format Length Mandatory Description
name 1 String 255 No Name of the debtor.
  • Can only contain letters, numbers, spacials or the special characters /-?:().,'+
  • When it is empty, NULL or not within the request, the current set value is used.
iban 1 String 34 No IBAN of the debtor.
  • When it is NULL or not within the request, the current set value is used.
  • Can be empty when a valid phone number or email is given or already set.
bic 1 String 50 No BIC of the given IBAN.
  • When it is NULL or not within the request, the current set value is used.
phone_number 1 String 13 No Phone number of the debtor, in an ISO20022 format.
  • When it is NULL or not within the request, the current set value is used.
  • Can be empty when a valid IBAN or email is given or already set.
email 1 String 255 No Email address of the debtor
  • When it is NULL or not within the request, the current set value is used.
  • Can be empty when a valid IBAN or phone number is given or already set.
5.4.2 Response

After a successful request, the HTTP status code 201 Created will be returned. See chapter 5.1.2 for the response parameters.

6 Transactions

This chapter gives an overview of all the existing requests to create or retrieve details of a transaction.

6.1 Retrieve all transactions

Retrieve all transactions linked to a specific debtor, by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The second-last parameter in the URL is the identifier of the debtor.
GET /v1.0/groups/AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B/debtors/ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3/transactions
6.1.1 Response

After a successful request, the HTTP status code 200 OK will be returned.

Name Level Format Length Description
transaction_id 1 String 40 Unique identifier of the transaction.
  • Can be NULL when the period_date is in the future.
debtor_id 1 String 40 Unique identifier of the debtor.
group_id 1 String 40 Unique identifier of the group.
payment_plan_id 1 String 40 Unique identifier of the payment plan.
period_date 1 DateTime UTC 25 Date and time of the linked period, in an ISO8601 format.
debtor_name 1 String 255 Name of the debtor.
debtor_iban 1 String 34 IBAN of the debtor.
  • Can be NULL when a valid phone number is present and the no_direct_debit tag is one.
debtor_bic 1 String 50 BIC of the given IBAN.
debtor_phone_number 1 String 13 Phone number of the debtor, in an ISO20022 format.
  • Can be NULL when a valid IBAN is given.
debtor_email 1 String 255 Email address of the debtor
amount 1 Decimal 6,2 Amount that needs to be collected from the debtor, for this transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
fee 1 Decimal 6,2 Amount of the fee for this transaction.
  • Maximum precision of two (e.g. 0.12).
  • The dot (.) is the decimal separator, which is not mandatory and can only occur once.
currency 1 String 3 Currency of the transaction.
  • Possible value is EUR.
last_status 1 String 50 Status of the transaction payment.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
  • Can be NULL when the period_date is in the future.
last_status_on 1 DateTime UTC 25 Date and time of when the status is last updated, in an ISO8601 format.
  • Can be NULL when the period_date is in the future.
6.2 Retrieve a transaction

Retrieve an existing transaction by calling the following URL via the HTTP-GET method. The last parameter in the URL is the identifier of the transaction
GET /v1.0/transactions/ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC
6.2.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 6.1.1 for the response parameters.

6.3 Delete a transaction

Delete an existing transaction by calling the following URL via the HTTP-DELETE method. The last parameter in the URL is the identifier of the transaction
DELETE /v1.0/transactions/ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC
6.3.1 Response

After a successful request, the HTTP status code 204 No Content will be returned. With no content in the response body.

7 Transaction payments

This chapter gives an overview of all the existing requests to create or retrieve details of one or more transaction payments.

7.1 Create a transaction payment

Create a new transaction payment by calling the following URL via the HTTP-POST method. The second-last parameter in the URL is the identifier of the transaction.

Note: when performing this request, any open transaction payments are marked to the Cancelled payment status.
POST /v1.0/transactions/ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC/payments
7.1.1 Request
Name Level Format Length Mandatory Description
payment_method 1 String 50 Yes Method of the transaction payment.
  • Possible values are DirectDebit, iDEAL, PaidToMerchant.
delivery_method 1 String 5 No Delivery method of the payment URL.
  • Possible values are EMAIL, SMS.
  • Is required when the payment_method equal to iDEAL. Otherwise it is obsolete and ignored.
7.1.2 Response

After a successful request, the HTTP status code 201 Created will be returned.

Name Level Format Length Description
transaction_payment_id 1 String 40 Unique identifier of the payment.
transaction_id 1 String 40 Unique identifier of the transaction.
debtor_id 1 String 40 Unique identifier of the debtor.
group_id 1 String 40 Unique identifier of the group.
payment_plan_id 1 String 40 Unique identifier of the payment plan.
debtor_name 1 String 255 Name of the debtor.
debtor_iban 1 String 34 IBAN of the debtor.
debtor_bic 1 String 50 BIC of the given IBAN.
debtor_phone_number 1 String 13 Phone number of the debtor, in an ISO20022 format.
debtor_email 1 String 255 Email address of the debtor
started_on 1 DateTime UTC 25 Date and time of when the payment is started.
payment_method 1 String 50 Method of the transaction payment.
  • Possible values are DirectDebit, iDEAL, PaidToMerchant.
delivery_method 1 String 5 Delivery method of the payment URL.
  • Possible values are EMAIL, SMS.
  • Is empty when the payment_method is not iDEAL.
status 1 String 50 Status of the transaction payment.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
status_updated_on 2 DateTime UTC 25 Date and time of when the status is last updated.
7.2 Retrieve all transaction payments

Retrieve all transaction payments by calling the following URL via the HTTP-GET method. The second-last parameter in the URL is the identifier of the transaction.
GET /v1.0/transactions/ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC/payments
7.2.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 7.1.2 for the response parameters.

7.3 Retrieve a transaction payment

Retrieve a transaction payment by calling the following URL via the HTTP-GET method. The last parameter in the URL is the identifier of the transaction payment.
GET /v1.0/transactons/ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC/payments/ATP-5CFF20B2-82E5-4713-9289-1D93EFC33407
7.3.1 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 7.1.2 for the response parameters.

8 Search

To search within all entity items, the URL needs to be extended with the word search and called via the HTTP-POST method.

8.1 Search within debtors

To search within all debtors, call the following URL via the HTTP-POST method. The third parameter in the URL is the identifier of the group.
POST /v1.0/debtors/search
8.1.1 Request
Name Level Format Length Mandatory Description
value 1 String 255 No Value to search for in the entity.
  • When left empty or out of the request, it will not be used.
debtor 1 Object - No Object containing debtor specific search values.
group_id 2 String 40 No Unique identifier of the group where to search in.
  • When left empty or out of the request, it will not be used.
payment_status 2 String 50 No Status of a transaction payment linked to the debtor.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
  • When left empty or out of the request, it will not be used.
number_of_periods 2 Integer 1 No Number of periods required to collect the total amount from the debtor.
  • When left empty or out of the request, it will not be used.
8.1.2 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.

8.2 Search within transactions

To search within all transactions, call the following URL via the HTTP-POST method. The second-last parameter in the URL is the identifier of the group
POST /v1.0/transactions/search
8.2.1 Request
Name Level Format Length Mandatory Description
value 1 String 255 No Value to search for in the entity.
  • When left empty or out of the request, it will not be used.
transaction 1 Object - No Object containing transaction specific search values.
group_id 2 String 40 No Unique identifier of the group where to search in.
  • When left empty or out of the request, it will not be used.
payment_method 2 String 50 No Method of the last transaction payment linked to the transaction.
  • Possible values are DirectDebit, iDEAL, Transfer, PaidToMerchant.
  • When left empty or out of the request, it will not be used.
payment_status 2 String 50 No Status of a last transaction payment linked to the transaction.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
  • When left empty or out of the request, it will not be used.
8.2.2 Response

After a successful request, the HTTP status code 200 OK will be returned. See chapter 6.1.1 for the response parameters.

9 Summary

To retrieve a summary of all items within an entity, the URL needs to be extended with the word summary and called via the HTTP-POST method.

9.1 Retrieve a debtor summary

To select a summary of all debtors within a group, call the following URL via the HTTP-POST method. The third parameters in the URL is the identifier of the group.
POST /v1.0/debtors/summary
9.1.1 Request
Name Level Format Length Mandatory Description
value 1 String 255 No Value to search for in the entity.
  • When left empty or out of the request, it will not be used.
debtor 1 Object - No Object containing debtor specific search values.
group_id 2 String 40 No Unique identifier of the group where to search in.
  • When left empty or out of the request, it will not be used.
payment_status 2 String 50 No Status of a transaction payment linked to the debtor.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
  • When left empty or out of the request, it will not be used.
number_of_periods 2 Integer 1 No Number of periods required to collect the total amount from the debtor.
  • When left empty or out of the request, it will not be used.
9.1.2 Response

After a successful request, the HTTP status code 200 OK will be returned.

Name Level Format Length Description
group_id 1 String 40 Unique identifier of the group.
periods 1 Array - List of occurring period details.
number_of_periods 2 Integer 1 Number of periods required to collect the total amount from the debtor.
number_of_transactions 2 Integer 10 Total number of transactions linked to the number of periods.
amount_of_transactions 2 Decimal 6,2 Total amount of transactions linked to the number of periods.
payment_statuses 2 Array - List of occurring payment statuses details.
payment_status 3 String 50 Status of the last transaction payment linked to the summarized transaction.
  • Possible values are Pending, Send, Initialized, Expired, Failed, Cancelled, Finalized, NotApplicable.
number_of_transactions 2 Integer 10 Total number of transactions linked to the payment status.
amount_of_transactions 2 Decimal 6,2 Total amount of transactions linked to the payment status.

10 Pagination

In order to keep performance and responses easier to handler, pagination is used for the requests that uses the HTTP-GET method. And for the search requests.

10.1 Request

To override the default pagination, use the following query string. This example returns the items 0 to 99.
- ?limit=100&start=0

The following parameters can occur within the URL:

Name Format Length Mandatory Description
limit Integer 3 No Maximum number of items returned.
  • When the limit is not within the query string, the default value 100 is used.
start Integer 10 No Number of the first item.
  • When the start is not within the query string, the default value 0 is used.
10.2 Response

With each request using the HTTP-GET method, three header values are returned in the response. Even when no pagination values are overridden in the request.

Name Format Length Description
pagination_limit Integer 36 Maximum number of items returned.
pagination_start Integer 36 Number of the start item.
pagination_total_items Integer 255 Number of the total items.

11 Status notifications

When the status of a transaction payment is modified, a status notification is triggered. This status notification will send a web request to a pre-setup callback URL via the HTTP-POST method, containing transaction and transaction payment identifiers.

Due to security reasons, only identifiers are send. The merchant is responsible to perform a Retrieve a transaction request (see chapter 5.2) or Retrieve a transaction payment (see chapter 6.3) in order to get details of the modified transaction and/or transaction payment.

11.1 Request
Name Level Format Length Description
payment_id 1 String 40 Unique identifier of the payment.
transaction_id 1 String 40 Unique identifier of the transaction.
debtor_id 1 String 40 Unique identifier of the debtor.
group_id 1 String 40 Unique identifier of the group.
11.2 Response

It is mandatory to response with a HTTP status code 2xx (preferable 204 No Content). When no or a different HTTP status code is returned, a re-schedule of the status notification is set. Several re-schedules are made before the status notification is automatically dropped.

12 Placeholders

It is possible to use placeholders that are replaced by dynamic values. Below is a list of these placeholders.

Placeholder Description
MERCHANT_NAME Name of the merchant.
MERCHANT_REFERENCE Reference, generated by the merchant, linked to the check-out or debtor.
NUMBER_OF_PERIODS Number of payment periods, required to collect the total amount.
PAYMENT_URL URL of the payment page, where the debtor can finalize an open payment.
PERIOD_AMOUNT Transaction amount of the payment period.
  • Will be presented in the currency format.
PERIOD_NUMBER Number of the payment period.

To the right is an example of a “Create a group”-request (see chapter 3.1) with no debtors. Here it is visible that each placeholder must be between the square brackets (The [- and ]-characters).

12.1 Supported parameters

Not every parameter in the requests uses these placeholders. Below is a list of the parameters and requests where placeholders are supported.

Entity Parameter Reference
Group page_content_description -> title Chapter 4.1.2
Group page_content_description -> content Chapter 4.1.2
Group page_content_description -> product_description Chapter 4.1.2
Group payment_content_description -> description Chapter 4.1.2
Group mail_content_description -> title Chapter 4.1.2
Group mail_content_description -> content Chapter 4.1.2
Group sms_content_description -> content Chapter 4.1.2
Check-out page_content_description -> title Chapter 5.1.2
Check-out page_content_description -> content Chapter 5.1.2
Check-out page_content_description -> product_description Chapter 5.1.2
Debtor page_content_description -> title Chapter 6.1.2
Debtor page_content_description -> content Chapter 6.1.2
Debtor page_content_description -> product_description Chapter 6.1.2

13 Error handling

When receiving an HTTP request that is invalid, an error response will return instead of the regular response. With this the corresponding HTTP status code (e.g. 400, 401, 404, etc.) is returned.

13.1 Response
Name Level Format Length Description
code 1 Integer 3 Unique code that resembled the occurred error.
reasons 1 String 255 List of reasons why the error has occurred.
13.2 Error codes
Code Name Description
001 Unknown An unknown error has occurred.
101 Invalid credentials None or incorrectly formatted credentials are given.
102 Unknown credentials Unknown credentials are given.
103 Insufficient rights Credentials with insufficient rights are given.
201 Invalid identifier None or an incorrectly formatted identifier is given.
202 Unknown identifier Unknown identifier is given.
203 Invalid request content None or incorrectly formatted content is given in the body of the request.
204 Invalid parameter One or more parameters are incorrect formatted or empty.
205 Action not available Requested action is (currently) not available.
206 No response content No response content is available in the response. 
{{  vm.toJson(vm.postman.result.response.data) }}
Name Value
Name Value
Api test
Close

Our docs have migrated to our brand new Developers portal
Please use these for the most up to date experience.