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 (Beta) MaV 2017-03-14 Added error codes.
1.0.0 MaV 2017-04-03 Added authentication.

1.2 Connectivity

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.

Code Examples:

EXAMPLE
{
  "period_type": "Monthly",
  "first_period_year": 2017,
  "first_period_month": 1,
  "first_period_day": 31,
  "number_of_periods": 4,
  "periods": [
    {
      "payments": [
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "payments": [
        {
          "payment_method": "DirectDebit"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "payments": [
        {
          "payment_method": "DirectDebit"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    }
  ]
}

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.

Code Examples:

EXAMPLE
{
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "period_type": "Monthly",
  "number_of_periods": 4,
  "periods": [
    {
      "period_date": "2017-01-31",
      "payments": [
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-02-28",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-03-31",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-04-30",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    }
  ]
}
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.

Code Examples:

EXAMPLE
{
  "period_type": "Manually",
  "number_of_periods": 2,
  "periods": [
    {
      "period_date": "2017-01-10",
      "payments": [
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-03-10",
      "payments": [
        {
          "payment_method": "DirectDebit"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    }	  
  ]
}
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.

Code Examples:

EXAMPLE
{
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "period_type": "Monthly",
  "number_of_periods": 4,
  "periods": [
    {
      "period_date": "2017-01-31",
      "payments": [
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-02-28",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-03-31",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-04-30",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    }
  ]
}
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.

Code Examples:

EXAMPLE
[
  {
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "period_type": "Monthly",
    "number_of_periods": 4,
    "periods": [
      {
        "period_date": "2017-01-31",
        "payments": [
          {
            "payment_method": "iDEAL",
            "delivery_method": "Email",
            "delivery_time": "12:00"
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "SMS",
            "delivery_time": "12:00"
          }
        ]
      },
      {
        "period_date": "2017-02-28",
        "payments": [
          {
            "payment_method": "DirectDebit",
            "delivery_method": null,
            "delivery_time": null
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "Email",
            "delivery_time": "12:00"
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "SMS",
            "delivery_time": "12:00"
          }
        ]
      },
      {
        "period_date": "2017-03-31",
        "payments": [
          {
            "payment_method": "DirectDebit",
            "delivery_method": null,
            "delivery_time": null
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "Email",
            "delivery_time": "12:00"
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "SMS",
            "delivery_time": "12:00"
          }
        ]
      },
      {
        "period_date": "2017-04-30",
        "payments": [
          {
            "payment_method": "DirectDebit",
            "delivery_method": null,
            "delivery_time": null
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "Email",
            "delivery_time": "12:00"
          },
          {
            "payment_method": "iDEAL",
            "delivery_method": "SMS",
            "delivery_time": "12:00"
          }
        ]
      }
    ]
  }
]
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.

Code Examples:

EXAMPLE
{
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "period_type": "Monthly",
  "number_of_periods": 4,
  "periods": [
    {
      "period_date": "2017-01-31",
      "payments": [
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-02-28",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-03-31",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    },
    {
      "period_date": "2017-04-30",
      "payments": [
        {
          "payment_method": "DirectDebit",
          "delivery_method": null,
          "delivery_time": null
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "Email",
          "delivery_time": "12:00"
        },
        {
          "payment_method": "iDEAL",
          "delivery_method": "SMS",
          "delivery_time": "12:00"
        }
      ]
    }
  ]
}

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.
callback_url 1 String - No URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting 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 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.
return_urls 1 Object 1 No Object with URLs used to return a debtor back, during a checkout flow.
  • Can be left out of the request to use the default settings.
success_url 2 String - No URL for a successful checkout.
failure_url 2 String - No URL for a failed checkout.
cancel_url 2 String - No URL for a cancelled checkout.

Code Examples:

EXAMPLE
{
  "reference": "Group reference one",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "transaction_fee": 2.50,
  "currency": "EUR",
  "locale": "nl-NL",
  "callback_url": "https://www.own-website.com/callback/"
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "payment_content_settings": {
    "description": "Merchant name - OWN-DEBTOR-REF",
  },
  "mail_content_settings": {
    "title": "Your own title",
    "content": "Mail content to inform the debtor",
  },
  "sms_content_settings": {
    "sender": "MERCHANT",
    "content": "SMS content to inform the debtor"
  },
  "return_urls": {
    "success_url": "https://www.own-website.com/success/",
    "failure_url": "https://www.own-website.com/failure/",
    "cancel_url": "https://www.own-website.com/cancel/"
  }
}
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 1 String 5 Preferred language and region setting, in an ISO15897 format.
number_of_debtors 1 Integer 10 Number of debtors linked to the group.
callback_url 1 String - URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting is used.
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.
return_urls 1 Object 1 Object with URLs used to return a debtor back, during a checkout flow.
  • Can be left out of the request to use the default settings.
success_url 2 String - URL for a successful checkout.
failure_url 2 String - URL for a failed checkout.
cancel_url 2 String - URL for a cancelled checkout.

Code Examples:

EXAMPLE
{
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "Group reference one",
  "transaction_fee": 2.50,
  "currency": "EUR",
  "locale": "nl-NL",
  "number_of_debtors": 1,
  "callback_url": "https://www.own-website.com/callback/"
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "payment_content_settings": {
    "description": "Merchant name - OWN-DEBTOR-REF",
  },
  "mail_content_settings": {
    "title": "Your own title",
    "content": "Mail content to inform the debtor",
  },
  "sms_content_settings": {
    "sender": "MERCHANT",
    "content": "SMS content to inform the debtor"
  },
  "return_urls": {
    "success_url": "https://www.own-website.com/success/",
    "failure_url": "https://www.own-website.com/failure/",
    "cancel_url": "https://www.own-website.com/cancel/"
  }
}
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.

Code Examples:

EXAMPLE
[
  {
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "Group reference one",
    "transaction_fee": 2.50,
    "currency": "EUR",
    "locale": "nl-NL",
    "number_of_debtors": 1,
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    },
    "payment_content_settings": {
      "description": "Merchant name - OWN-DEBTOR-REF",
    },
    "mail_content_settings": {
      "title": "Your own title",
      "content": "Mail content to inform the debtor",
    },
    "sms_content_settings": {
      "sender": "MERCHANT",
      "content": "SMS content to inform the debtor"
    },
    "return_urls": {
      "success_url": "https://www.own-website.com/success/",
      "failure_url": "https://www.own-website.com/failure/",
      "cancel_url": "https://www.own-website.com/cancel/"
    }
  }
]
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.

Code Examples:

EXAMPLE
{
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "Group reference one",
  "transaction_fee": 2.50,
  "currency": "EUR",
  "locale": "nl-NL",
  "number_of_debtors": 1,
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "payment_content_settings": {
    "description": "Merchant name - OWN-DEBTOR-REF",
  },
  "mail_content_settings": {
    "title": "Your own title",
    "content": "Mail content to inform the debtor",
  },
  "sms_content_settings": {
    "sender": "MERCHANT",
    "content": "SMS content to inform the debtor"
  },
  "return_urls": {
    "success_url": "https://www.own-website.com/success/",
    "failure_url": "https://www.own-website.com/failure/",
    "cancel_url": "https://www.own-website.com/cancel/"
  }
}

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 MSISDN format.
email 1 String 255 No Email address of the debtor.
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.
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.
callback_url 1 String - No URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting 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.

Code Examples:

EXAMPLE
{
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "OWN-DEBTOR-REF",
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
  "currency": "EUR",
  "locale": "nl-NL",
  "total_amount": 13.37,
  "transaction_fee": 2.50,
  "callback_url": "https://www.own-website.com/callback/"
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  }
}
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 MSISDN 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.
callback_url 1 String - URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting is 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.
check_out_url 1 String 255 URL of the check out page.

Code Examples:

EXAMPLE
{
  "check_out_id": "ACH-08EF0371-239E-4C71-BE91-467ACC560D5C",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "OWN-DEBTOR-REF",
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
  "currency": "EUR",
  "locale": "nl-NL",
  "total_amount": 13.37,
  "transaction_fee": 2.50,
  "callback_url": "https://www.own-website.com/callback/"
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "check_out_url": "https://autocollect.cmpayments.com/debtor/check-out/ACH-08EF0371-239E-4C71-BE91-467ACC560D5C"
}
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.

Code Examples:

EXAMPLE
[
  {
    "check_out_id": "ACH-08EF0371-239E-4C71-BE91-467ACC560D5C",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "OWN-DEBTOR-REF",
    "name": "John Smith",
    "iban": "NL80CMPT0000000001",
    "bic": "CMPTNL2A",
    "phone_number": "0031600000000",
    "email": "[email protected]",
    "currency": "EUR",
    "locale": "nl-NL",
    "total_amount": 13.37,
    "transaction_fee": 2.50,
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    },
    "check_out_url": "https://autocollect.cmpayments.com/debtor/check-out/ACH-08EF0371-239E-4C71-BE91-467ACC560D5C"
  }
]
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.

Code Examples:

EXAMPLE
{
  "check_out_id": "ACH-08EF0371-239E-4C71-BE91-467ACC560D5C",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "OWN-DEBTOR-REF",
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
  "currency": "EUR",
  "locale": "nl-NL",
  "total_amount": 13.37,
  "transaction_fee": 2.50,
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "check_out_url": "https://autocollect.cmpayments.com/debtor/check-out/ACH-08EF0371-239E-4C71-BE91-467ACC560D5C"
}

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.

POST /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 MSISDN format.
  • Can be NULL when a valid IBAN is given.
email 1 String 255 No Email address of the debtor.
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.
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 1 Boolean 5 Yes TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
callback_url 1 String - No URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting is 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.

Code Examples:

EXAMPLE
[
  {
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "OWN-DEBTOR-REF",
    "name": "John Smith",
    "iban": "NL80CMPT0000000001",
    "bic": "CMPTNL2A",
    "phone_number": "0031600000000",
    "email": "[email protected]",
    "currency": "EUR",
    "locale": "nl-NL",
    "total_amount": 13.37,
    "transaction_fee": 2.50,
    "no_direct_debit": false,
    "callback_url": "https://www.own-website.com/callback/",
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    }
  }
]
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 MSISDN 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.
callback_url 1 String - URL of the merchant where status notifications are send to.
  • Can only contain an absolute URL with the HTTP or HTTPS protocol
  • When left out the request, the group setting is 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.

Code Examples:

EXAMPLE
[
  {
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "OWN-DEBTOR-REF",
    "name": "John Smith",
    "iban": "NL80CMPT0000000001",
    "bic": "CMPTNL2A",
    "phone_number": "0031600000000",
    "email": "[email protected]",
    "currency": "EUR",
    "locale": "nl-NL",
    "total_amount": 13.37,
    "transaction_fee": 2.50,
    "no_direct_debit": false,
    "callback_url": "https://www.own-website.com/callback/"
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    }
  }
]
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.

Code Examples:

EXAMPLE
[
  {
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "OWN-DEBTOR-REF",
    "name": "John Smith",
    "iban": "NL80CMPT0000000001",
    "bic": "CMPTNL2A",
    "phone_number": "0031600000000",
    "email": "[email protected]",
    "currency": "EUR",
    "locale": "nl-NL",
    "total_amount": 13.37,
    "transaction_fee": 2.50,
    "no_direct_debit": false,
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    }
  }
]
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.

Code Examples:

EXAMPLE
{
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "OWN-DEBTOR-REF",
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
  "currency": "EUR",
  "locale": "nl-NL",
  "total_amount": 13.37,
  "transaction_fee": 2.50,
  "no_direct_debit": false,
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  }
}
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 MSISDN 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.

Code Examples:

EXAMPLE
{
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
}
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.

Code Examples:

EXAMPLE
{
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "reference": "OWN-DEBTOR-REF",
  "name": "John Smith",
  "iban": "NL80CMPT0000000001",
  "bic": "CMPTNL2A",
  "phone_number": "0031600000000",
  "email": "[email protected]",
  "currency": "EUR",
  "locale": "nl-NL",
  "total_amount": 13.37,
  "transaction_fee": 2.50,
  "no_direct_debit": false,
  "page_content_settings": {
    "title": "Your own title",
    "content": "Page content to inform the debtor",
    "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  }
}

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 MSISDN 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 listed in chapter 16.
  • 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.

Code Examples:

EXAMPLE
[
  {
    "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "period_date": "2017-01-01T12:00:00+00:00",
    "debtor_name": "John Smith",
    "debtor_iban": "NL80CMPT0000000001",
    "debtor_bic": "CMPTNL2A",
    "debtor_phone_number": "0031600000000",
    "debtor_email": "[email protected]",
    "amount": 13.37,
    "fee": 2.50,
    "currency": "EUR",
    "last_status": "Pending",
    "last_status_on": "2017-01-01T12:00:00+00:00"
  }
]
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.

Code Examples:

EXAMPLE
{
  "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "period_date": "2017-01-01T12:00:00+00:00",
  "debtor_name": "John Smith",
  "debtor_iban": "NL80CMPT0000000001",
  "debtor_bic": "CMPTNL2A",
  "debtor_phone_number": "0031600000000",
  "debtor_email": "[email protected]",
  "amount": 13.37,
  "fee": 2.50,
  "currency": "EUR",
  "last_status": "Pending",
  "last_status_on": "2017-01-01T12:00:00+00:00"
}
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.

Code Examples:

EXAMPLE
{
  "payment_method": "iDEAL",
  "delivery_method": "SMS"
}
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 MSISDN 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 listed in chapter 16.
status_updated_on 2 DateTime UTC 25 Date and time of when the status is last updated.

Code Examples:

EXAMPLE
{
  "transaction_payment_id": "ATP-5CFF20B2-82E5-4713-9289-1D93EFC33407",
  "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "debtor_name": "John Smith",
  "debtor_iban": "NL80CMPT0000000001",
  "debtor_bic": "CMPTNL2A",
  "debtor_phone_number": "0031600000000",
  "debtor_email": "[email protected]",
  "started_on": "2017-01-01T12:00:00+00:00",
  "payment_method": "iDEAL",
  "delivery_method": "SMS"
  "status": "Pending",
  "status_updated_on": "2017-01-01T12:00:00+00:00"
}
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.

Code Examples:

EXAMPLE
[
  {
    "transaction_payment_id": "ATP-5CFF20B2-82E5-4713-9289-1D93EFC33407",
    "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "debtor_name": "John Smith",
    "debtor_iban": "NL80CMPT0000000001",
    "debtor_bic": "CMPTNL2A",
    "debtor_phone_number": "0031600000000",
    "debtor_email": "[email protected]",
    "started_on": "2017-01-01T12:00:00+00:00",
    "payment_method": "iDEAL",
    "delivery_method": "SMS"
    "status": "Pending",
    "status_updated_on": "2017-01-01T12:00:00+00:00"
  }
]
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.

Code Examples:

EXAMPLE
{
  "transaction_payment_id": "ATP-5CFF20B2-82E5-4713-9289-1D93EFC33407",
  "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "debtor_name": "John Smith",
  "debtor_iban": "NL80CMPT0000000001",
  "debtor_bic": "CMPTNL2A",
  "debtor_phone_number": "0031600000000",
  "debtor_email": "[email protected]",
  "started_on": "2017-01-01T12:00:00+00:00",
  "payment_method": "iDEAL",
  "delivery_method": "SMS"
  "status": "Pending",
  "status_updated_on": "2017-01-01T12:00:00+00:00"
}

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.

Please note that search functionalities are currently not supported

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

Please note that search functionalities are currently not supported

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.

Code Examples:

EXAMPLE
{
  "value": "John",
  "debtor": {
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_status": "Pending",
    "number_of_periods": 1
  }
}
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.

Code Examples:

EXAMPLE
[
  {
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "reference": "OWN-DEBTOR-REF",
    "name": "John Smith",
    "iban": "NL80CMPT0000000001",
    "bic": "CMPTNL2A",
    "phone_number": "0031600000000",
    "email": "[email protected]",
    "currency": "EUR",
    "locale": "nl-NL",
    "total_amount": 13.37,
    "transaction_fee": 2.50,
    "no_direct_debit": false,
    "page_content_settings": {
      "title": "Your own title",
      "content": "Page content to inform the debtor",
      "product_description": "Product payment – Reference: OWN-DEBTOR-REF",
      "header_color": "#259BDB",
      "button_color": "#FF6633",
      "logo_url": "https://www.own-website.com/logo.png",
      "redirect_url": "https://www.own-website.com/redirect/"
    }
  }
]
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

Please note that search functionalities are currently not supported

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.

Code Examples:

EXAMPLE
{
  "value": "John",
  "transaction": {
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_method": "DirectDebit"
    "payment_status": "Pending",
  }
}
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.

Code Examples:

EXAMPLE
[
  {
    "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
    "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
    "period_date": "2017-01-01T12:00:00+00:00",
    "debtor_name": "John Smith",
    "debtor_iban": "NL80CMPT0000000001",
    "debtor_bic": "CMPTNL2A",
    "debtor_phone_number": "0031600000000",
    "debtor_email": "[email protected]",
    "amount": 13.37,
    "fee": 2.50,
    "currency": "EUR",
    "last_status": "DirectDebit",
    "last_status_on": "2017-01-01T12:00:00+00:00"
  }
]

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.

Please note that summary functionalities are currently not supported

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

Please note that summary functionalities are currently not supported

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.

Code Examples:

EXAMPLE
{
  "value": "John",
  "debtor": {
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "payment_status": "Pending",
    "number_of_periods": 1
  }
}
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.

Code Examples:

EXAMPLE
[
  {
    "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B",
    "periods": [
      {
        "number_of_periods": 1,
        "number_of_transactions": 1,
        "amount_of_transactions": 13.37,
        "payment_statuses" [
          {
            "payment_status": "Pending"
            "number_of_transactions": 1,
            "amount_of_transactions": 13.37,
          }
        ]
      }
    ]
  }
]

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 6.2) or Retrieve a transaction payment (see chapter 7.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.
check_out_id 1 String 40 Unique identifier of the check-out.
  • Can be NULL when no check out is used
group_id 1 String 40 Unique identifier of the group.

Code Examples:

EXAMPLE
{
  "payment_id": "ATP-5CFF20B2-82E5-4713-9289-1D93EFC33407",
  "transaction_id": "ATR-AA24ECB0-4970-4F3C-8A23-BF62C2950FAC",
  "debtor_id": "ADB-C2DDCF60-130F-46CC-AB00-FB2183B73AF3",
  "check_out_id": "ACH-08EF0371-239E-4C71-BE91-467ACC560D5C",
  "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B"
}
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
DEBTOR_NAME Name of the debtor.
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).

Code Examples:

EXAMPLE
{
  "reference": "Group reference one",
  "payment_plan_id": "APP-E3FE0E5D-8255-4436-BDAA-629E650FFDC1",
  "transaction_fee": 2.50,
  "currency": "EUR",
  "locale": "nl-NL",
  "page_content_settings": {
    "title": "Your own title",
    "content": "Their is an open payment of [PERIOD_AMOUNT] to be paid to [MERCHANT_NAME]",
    "product_description": "Payment [PERIOD_NUMBER] of [NUMBER_OF_PERIODS] – Reference: [MERCHANT_REFERENCE]",
    "header_color": "#259BDB",
    "button_color": "#FF6633",
    "logo_url": "https://www.own-website.com/logo.png",
    "redirect_url": "https://www.own-website.com/redirect/"
  },
  "payment_content_settings": {
    "description": "[MERCHANT_NAME] - [MERCHANT_REFERENCE]",
  },
  "mail_content_settings": {
    "title": "Open payment at [MERCHANT_NAME]",
    "content": "Mail content to inform the debtor",
  },
  "sms_content_settings": {
    "sender": "MERCHANT",
    "content": "Dear [DEBTOR_NAME], their is an open payment of [PERIOD_AMOUNT] to be paid to [MERCHANT_NAME]. Please click the link to finalize the payment: [PAYMENT_URL]"
  }
}
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 Array - List of reasons why the error has occurred.

Code Examples:

EXAMPLE
{
  "code": 1,
  "reasons": [
    "The request is not supported"
  ]
}
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.
207 Unsupported content-type Used content-type is not supported for the made request.

14 Authentication

For authentication, the OAuth 2.0 protocol is used. This means every request send to the API needs to have an access token. Which results into two steps to setup authentication:

  • Retrieve an access token.
  • Perform the request with the access token.
14.1 Retrieve an access token

A token needs to be acquired before resources can be retrieved, stored or altered. This can be done by calling the following URL via the HTTP-POST method.

POST /v1.0/token
14.1.1 Headers

In the token request the following two headers are required:

Name Description
Content-Type Type of the content.
  • Value must be application/x-www-form-urlencoded.
X-CM-MERCHANT Unique reference of your account at AutoCollect.
  • Is delivered by the account manager, together with the unique secret key (for hashing purposes), username and password.

Code Examples:

EXAMPLE
Content-Type: application/x-www-form-urlencoded
X-CM-MERCHANT: AMR-90193629-E5A7-4D48-9E99-45C3355D8F41
14.1.2 Request

The content of the request must be a key-value pair list separated by the &-character between each key-value pair. The following keys are required within the request.

Name Mandatory Description
grant_type Yes oAuth2.0 type to indicate which grant method is being used.
  • Value must be password
username Yes Username of your account at AutoCollect.
  • Is delivered by the account manager, together with the merchant reference, unique secret key (for hashing purposes) and password.
password Yes Hashed value of your password of your AutoCollect account.
  • Password is delivered in plain text by the account manager, together with the merchant reference, unique secret key (for hashing purposes) and username.
  • See section below on how to hash the plain-text password

Hash the password

The password is received in plain-text by the account manager but needs to a SHA256 hash calculated value when sending in a token request. This hash value is calculated over the plain-text password concatenated with the secret key. For example we have the password value Password and the secret key SUPER-SECRET. This will result in the concatenated string (Please note that the concatenated value is case-sensitive):

  • PasswordSUPER-SECRET

Over this concatenated string, the SHA256 hash has to be calculated and used as the password value in the token request. For the example the following SHA256 hash value is calculated:

  • 37c18a252859f604cac45555a2d1ee78bd88f66c014aca6b96893425d790e7e6

Code Examples:

EXAMPLE
grant_type=password&username=Username&password=37c18a252859f604cac45555a2d1ee78bd88f66c014aca6b96893425d790e7e6
14.1.3 Response

When the token request is valid, a response with an access token is returned. This access token is, by default, valid for 30 minutes.

Name Level Format Length Description
access_token 1 String - Value of the access token, which is required for each subsequent request.
token_type 1 String - Type of the access token.
  • Possible value is bearer.
expires_in 1 Integer 1 Number of seconds before the access token is not valid anymore.
  • Default value Is set to 1800 seconds.

Code Examples:

EXAMPLE
{
  "access_token": "jDsU7dNY5mhT_PTK4_7hg5H1iQFTZ8PBKTGXQLst9kwTLqczogFu9PxNzGZ92mVUuL07fzf-p8ugMbbxhDYUZeR_TY9vhyn0YMzuFwPU8vC1NivNeu6aEi1lMcdcWc_9DhdZP03GP6FPFVeovclD2nG9rciqtuuOjrmORdrSuM0h8wnpcEzMhvfYiypj8_wEzc69cG6q907JsPGdShjkMzkQJVbv0JDU53y-gIMJ3D5kTDMMpgyQo1X7MUyiXg1BbHzbjuY8KvhUyVd-KprrhMgyU5jblORCBsD4NCsiPO0",
  "token_type": "bearer",
  "expires_in": 1800
}
14.2 Perform the request

After a valid token request, an access token is returned. This token must appear in the Authorization header of subsequent requests to the API in the following format.

  • Authorization: [token_type] [access_token]
Name Description
token_type Type of the access token.
  • Value is received after a valid token request.
  • Possible value is bearer.
access_token Value of the access token.
  • Value is received after a valid token request.

Code Examples:

EXAMPLE
Authorization: bearer jDsU7dNY5mhT_PTK4_7hg5H1iQFTZ8PBKTGXQLst9kwTLqczogFu9PxNzGZ92mVUuL07fzf-p8ugMbbxhDYUZeR_TY9vhyn0YMzuFwPU8vC1NivNeu6aEi1lMcdcWc_9DhdZP03GP6FPFVeovclD2nG9rciqtuuOjrmORdrSuM0h8wnpcEzMhvfYiypj8_wEzc69cG6q907JsPGdShjkMzkQJVbv0JDU53y-gIMJ3D5kTDMMpgyQo1X7MUyiXg1BbHzbjuY8KvhUyVd-KprrhMgyU5jblORCBsD4NCsiPO0

15 Test IBANs

It is possible to do test transactions so no actual direct debit is performed. To simulate various scenario's the following IBANs can be used. Each specific IBAN result in a specific scenario:

Test IBAN Scenario SEPA code
NL80CMPT0000000001 Success -
NL53CMPT0000000002 Reversed AC01
NL26CMPT0000000003 Reversed AC04
NL96CMPT0000000004 Reversed AC06
NL69CMPT0000000005 Reversed AC13
NL42CMPT0000000006 Reversed AG01
NL15CMPT0000000007 Reversed AG02
NL85CMPT0000000008 Reversed AGNT
NL58CMPT0000000009 Reversed AM04
NL31CMPT0000000010 Reversed AM05
NL04CMPT0000000011 Reversed BE04
NL74CMPT0000000012 Reversed BE05
NL47CMPT0000000013 Reversed CURR
NL20CMPT0000000014 Reversed CUST
NL90CMPT0000000015 Reversed CUTA
NL63CMPT0000000016 Reversed DUPL
NL36CMPT0000000017 Reversed FF01
NL09CMPT0000000018 Reversed FF05
NL79CMPT0000000019 Reversed FOCR
NL52CMPT0000000020 Reversed MD01
NL25CMPT0000000021 Reversed MD02
NL95CMPT0000000022 Reversed MD06
NL68CMPT0000000023 Reversed MD07
NL41CMPT0000000024 Reversed MS02
NL14CMPT0000000025 Reversed MS03
NL84CMPT0000000026 Reversed PC01
NL57CMPT0000000027 Reversed PC02
NL30CMPT0000000028 Reversed PC03
NL03CMPT0000000029 Reversed RC01
NL73CMPT0000000030 Reversed RR01
NL46CMPT0000000031 Reversed RR02
NL19CMPT0000000032 Reversed RR03
NL89CMPT0000000033 Reversed RR04
NL62CMPT0000000034 Reversed R001
NL35CMPT0000000035 Reversed R002
NL08CMPT0000000036 Reversed R003
NL78CMPT0000000037 Reversed R004
NL51CMPT0000000038 Reversed SL01
NL24CMPT0000000039 Reversed TECH
NL94CMPT0000000040 Reversed TM01
NL67CMPT0000000041 Reversed UPAY

16 Payment statuses

Below is a list of possible payment statuses that can be returned by the API for a transaction or a transaction payment

Payment status Description
Pending Waiting to be send to debtor (iDEAL) or bank (direct debit).
Send Only iDEAL, message send to debtor via SMS or e-mail.
Initialized Send to bank only (direct debit). Or redirect to bank payment page (iDEAL).
Expired Only iDEAL when the debtor has not finished the payment flow on the bank payment page.
Failed Payment failed. Reasons can be blocked bank account (direct debit), invalid bank account (direct debit), payment rejected at bank payment page (iDEAL), etc.
Cancelled Manual set by AutoCollect. Exception.
Finalized Payment successful.
NotApplicable Manual set by AutoCollect. Exception.