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.
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. |
The URL to be used is: https://autocollectapi.cmpayments.com/
In this documentation we will describe the following entities:
Check out
Container with information of a product that is desired to be paid for by a debtor.
Debtor
Person who is charged by the merchant for a given amount over a given set of periods.
Group
In the dashboard multiple debtors are shown via a group view. A group needs to consist at least one debtor.
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.
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.
Transaction
Container with information of the owed amount that should be paid by an end-user during one period.
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.
This chapter given an overview of all requests to create or retrieve details of payment plans.
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
period_type | 1 | String | 7 | Yes | The type of the period.
|
first_period_year | 1 | Integer | 4 | No | Number of the year the first period must take place.
|
first_period_month | 1 | Integer | 2 | No | Number of the month the first period must take place.
|
first_period_day | 1 | Integer | 2 | No | Number of the day the first period must take place.
|
number_of_periods | 1 | Integer | 1 | Yes | The total number of periods.
|
periods | 1 | Array | - | Yes | List of payment periods. |
payments | 2 | Array | - | Yes | List of payment methods and the sequences they are used in.
|
payment_method | 3 | String | 11 | Yes | Method of the transaction payment
|
delivery_method | 3 | String | 5 | No | Method of how the payment notification is delivered to the debtor.
|
delivery_time | 3 | Time | 5 | No | Time when the payment notification needs to be delivered.
|
{ "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" } ] } ] }
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.
|
number_of_periods | 1 | Integer | 1 | The total number of periods.
|
periods | 1 | Array | - | List of payment periods. |
period_date | 2 | Date | 10 | Date of the payment period.
|
payments | 2 | Array | - | List of payments in the sequences of follow-up.
|
payment_method | 3 | String | 11 | Method of the payment
|
delivery_method | 3 | String | 5 | Method of how the payment notification is delivered to the debtor.
|
delivery_time | 3 | Time | 5 | Time when the payment notification needs to be delivered.
|
{ "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" } ] } ] }
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
period_type | 1 | String | 7 | Yes | The type of the period.
|
number_of_periods | 1 | Integer | 1 | Yes | The total number of periods.
|
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.
|
payment_method | 3 | String | 11 | Yes | Method of the transaction payment
|
delivery_method | 3 | String | 5 | No | Method of how the payment notification is delivered to the debtor.
|
delivery_time | 3 | Time | 5 | No | Time when the payment notification needs to be delivered.
|
{ "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" } ] } ] }
After a successful request, the HTTP status code 201 Created will be returned. See chapter 2.1.2 for the response parameters.
{ "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" } ] } ] }
Retrieve all existing payment plans by calling the following URL via HTTP-GET method.
GET | /v1.0/payment-plans |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 2.1.2 for the response parameters.
[ { "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" } ] } ] } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 2.1.2 for the response parameters.
{ "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" } ] } ] }
This chapter gives an overview of all the requests to create or retrieve details of a group.
Create one group by calling the following URL via the HTTP-POST method.
POST | /v1.0/groups |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
reference | 1 | String | 255 | Yes | Own reference of the group.
|
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.
|
currency | 1 | String | 3 | Yes | Currency for each transaction.
|
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.
|
page_content_settings | 1 | Object | 1 | No | Object with content settings used within the payment page.
|
title | 2 | String | 100 | No | Title of the payment page.
|
content | 2 | String | - | No | Content to inform the debtor about the payment.
|
product_description | 2 | String | 100 | No | Description of the product.
|
header_color | 2 | String | 7 | No | Hexadecimal value of a color used for the headers within the payment page.
|
button_color | 2 | String | 7 | No | Hexadecimal value of a color used for the buttons within the payment page.
|
logo_url | 2 | String | - | No | URL of the merchant’s own logo.
|
redirect_url | 2 | String | - | No | URL of the merchant where the debtor is going to be redirected.
|
payment_content_settings | 1 | Object | 1 | No | Object with content settings used within the payments.
|
description | 2 | String | 35 | No | Summary description of the payment displayed on the debtor’s bank account.
|
mail_content_settings | 1 | Object | 1 | No | Object with content settings used within the mail follow-up messages.
|
title | 2 | String | - | No | Title of the follow-up mail.
|
content | 2 | String | - | No | Content of the follow-up mail, to remind the debtor about an unpaid payment.
|
sms_content_settings | 1 | Object | 1 | No | Object with content settings used within the SMS follow-up messages.
|
sender | 2 | String | 11 | No | Sender of the SMS follow-up message.
|
content | 2 | String | - | No | Content of the follow-up SMS, to remind the debtor about an unpaid payment.
|
return_urls | 1 | Object | 1 | No | Object with URLs used to return a debtor back, during a checkout flow.
|
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. |
{ "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/" } }
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.
|
transaction_fee | 1 | Decimal | 6,2 | Amount of the fee per transaction.
|
currency | 1 | String | 3 | Currency for each transaction.
|
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.
|
page_content_settings | 1 | Object | 1 | Object with settings used within the payment page.
|
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.
|
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.
|
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.
|
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. |
{ "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/" } }
Retrieve all existing groups by calling the following URL via HTTP-GET method.
GET | /v1.0/groups |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 3.1.2 for the response parameters.
[ { "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/" } } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 3.1.2 for the response parameters.
{ "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/" } }
This chapter gives an overview of all the existing requests to create or retrieve details of a checkout.
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
payment_plan_id | 1 | String | 40 | No | Unique identifier of an existing payment plan.
|
reference | 1 | String | 255 | Yes | Own unique reference of the debtor. |
name | 1 | String | 255 | No | Name of the debtor.
|
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. |
1 | String | 255 | No | Email address of the debtor. | |
currency | 1 | String | 3 | Yes | Currency for each transaction.
|
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.
|
transaction_fee | 1 | Decimal | 6,2 | No | Amount of the fee per transaction.
|
callback_url | 1 | String | - | No | URL of the merchant where status notifications are send to.
|
page_content_settings | 1 | Object | 1 | No | Object with content settings used within the payment page.
|
title | 2 | String | 100 | No | Title of the payment page.
|
content | 2 | String | - | No | Content to inform the debtor about the payment.
|
product_description | 2 | String | 100 | No | Description of the product.
|
header_color | 2 | String | 7 | No | Hexadecimal value of a color used for the headers within the payment page.
|
button_color | 2 | String | 7 | No | Hexadecimal value of a color used for the buttons within the payment page.
|
logo_url | 2 | String | - | No | URL of the merchant’s own logo.
|
redirect_url | 2 | String | - | No | URL of the merchant where the debtor is going to be redirected.
|
{ "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/" } }
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. |
1 | String | 255 | Email address of the debtor. | |
currency | 1 | String | 3 | Currency for each transaction.
|
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.
|
transaction_fee | 1 | Decimal | 6,2 | Amount of the fee per transaction.
|
callback_url | 1 | String | - | URL of the merchant where status notifications are send to.
|
page_content_settings | 1 | Object | 1 | Object with settings used within the payment page and possible follow-up messages.
|
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. |
{ "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" }
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 4.1.2 for the response parameters.
[ { "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" } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 4.1.2 for the response parameters.
{ "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" }
This chapter gives an overview of all the existing requests to create or retrieve details of a debtor.
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
payment_plan_id | 1 | String | 40 | No | Unique identifier of an existing payment plan.
|
reference | 1 | String | 255 | Yes | Own unique reference of the debtor. |
name | 1 | String | 255 | No | Name of the debtor.
|
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.
|
1 | String | 255 | No | Email address of the debtor. | |
currency | 1 | String | 3 | Yes | Currency for each transaction.
|
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.
|
transaction_fee | 1 | Decimal | 6,2 | No | Amount of the fee per transaction.
|
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.
|
page_content_settings | 1 | Object | 1 | No | Object with settings used within the payment page.
|
title | 2 | String | 100 | No | Title of the payment page.
|
content | 2 | String | - | No | Content to inform the debtor about the payment.
|
product_description | 2 | String | 100 | No | Description of the product.
|
header_color | 2 | String | 7 | No | Hexadecimal value of a color used for the headers within the payment page.
|
button_color | 2 | String | 7 | No | Hexadecimal value of a color used for the buttons within the payment page.
|
logo_url | 2 | String | - | No | URL of the merchant’s own logo.
|
redirect_url | 2 | String | - | No | URL of the merchant where the debtor is going to be redirected.
|
[ { "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/" } } ]
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.
|
bic | 1 | String | 50 | BIC of the given IBAN. |
phone_number | 1 | String | 13 | Phone number of the debtor, in an MSISDN format.
|
1 | String | 255 | Email address of the debtor | |
currency | 1 | String | 3 | Currency for each transaction.
|
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.
|
transaction_fee | 1 | Decimal | 6,2 | Amount of the fee per transaction.
|
no_direct_debit | 1 | Boolean | 5 | TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
|
callback_url | 1 | String | - | URL of the merchant where status notifications are send to.
|
page_content_settings | 1 | Object | 1 | Object with settings used within the payment page and possible follow-up messages.
|
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. |
[ { "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/" } } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.
[ { "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/" } } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.
{ "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/" } }
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
name | 1 | String | 255 | No | Name of the debtor.
|
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.
|
1 | String | 255 | No | Email address of the debtor
|
{ "name": "John Smith", "iban": "NL80CMPT0000000001", "bic": "CMPTNL2A", "phone_number": "0031600000000", "email": "[email protected]", }
After a successful request, the HTTP status code 201 Created will be returned. See chapter 5.1.2 for the response parameters.
{ "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/" } }
This chapter gives an overview of all the existing requests to create or retrieve details of a transaction.
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 |
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.
|
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.
|
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 |
amount | 1 | Decimal | 6,2 | Amount that needs to be collected from the debtor, for this transaction.
|
fee | 1 | Decimal | 6,2 | Amount of the fee for this transaction.
|
currency | 1 | String | 3 | Currency of the transaction.
|
last_status | 1 | String | 50 | Status of the transaction payment.
|
last_status_on | 1 | DateTime UTC | 25 | Date and time of when the status is last updated, in an ISO8601 format.
|
[ { "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" } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 6.1.1 for the response parameters.
{ "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" }
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 |
After a successful request, the HTTP status code 204 No Content will be returned. With no content in the response body.
This chapter gives an overview of all the existing requests to create or retrieve details of one or more transaction payments.
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 |
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
payment_method | 1 | String | 50 | Yes | Method of the transaction payment.
|
delivery_method | 1 | String | 5 | No | Delivery method of the payment URL.
|
{ "payment_method": "iDEAL", "delivery_method": "SMS" }
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.
|
delivery_method | 1 | String | 5 | Delivery method of the payment URL.
|
status | 1 | String | 50 | Status of the transaction payment.
|
status_updated_on | 2 | DateTime UTC | 25 | Date and time of when the status is last updated. |
{ "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" }
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 7.1.2 for the response parameters.
[ { "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" } ]
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 |
After a successful request, the HTTP status code 200 OK will be returned. See chapter 7.1.2 for the response parameters.
{ "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" }
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
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
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
value | 1 | String | 255 | No | Value to search for in the entity.
|
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.
|
payment_status | 2 | String | 50 | No | Status of a transaction payment linked to the debtor.
|
number_of_periods | 2 | Integer | 1 | No | Number of periods required to collect the total amount from the debtor.
|
{ "value": "John", "debtor": { "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B", "payment_status": "Pending", "number_of_periods": 1 } }
After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.
[ { "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/" } } ]
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
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
value | 1 | String | 255 | No | Value to search for in the entity.
|
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.
|
payment_method | 2 | String | 50 | No | Method of the last transaction payment linked to the transaction.
|
payment_status | 2 | String | 50 | No | Status of a last transaction payment linked to the transaction.
|
{ "value": "John", "transaction": { "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B", "payment_method": "DirectDebit" "payment_status": "Pending", } }
After a successful request, the HTTP status code 200 OK will be returned. See chapter 6.1.1 for the response parameters.
[ { "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" } ]
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
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
Name | Level | Format | Length | Mandatory | Description |
---|---|---|---|---|---|
value | 1 | String | 255 | No | Value to search for in the entity.
|
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.
|
payment_status | 2 | String | 50 | No | Status of a transaction payment linked to the debtor.
|
number_of_periods | 2 | Integer | 1 | No | Number of periods required to collect the total amount from the debtor.
|
{ "value": "John", "debtor": { "group_id": "AGR-A6A918EB-4D20-481A-B57F-7A0EF92EBC0B", "payment_status": "Pending", "number_of_periods": 1 } }
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.
|
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. |
[ { "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, } ] } ] } ]
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.
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.
|
start | Integer | 10 | No | Number of the first item.
|
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. |
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.
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.
|
group_id | 1 | String | 40 | Unique identifier of the group. |
{ "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" }
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.
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.
|
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).
{ "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]" } }
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 |
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.
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": 1, "reasons": [ "The request is not supported" ] }
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. |
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:
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 |
In the token request the following two headers are required:
Name | Description |
---|---|
Content-Type | Type of the content.
|
X-CM-MERCHANT | Unique reference of your account at AutoCollect.
|
Content-Type: application/x-www-form-urlencoded X-CM-MERCHANT: AMR-90193629-E5A7-4D48-9E99-45C3355D8F41
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.
|
username | Yes | Username of your account at AutoCollect.
|
password | Yes | Hashed value of your password of your AutoCollect account.
|
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):
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:
grant_type=password&username=Username&password=37c18a252859f604cac45555a2d1ee78bd88f66c014aca6b96893425d790e7e6
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.
|
expires_in | 1 | Integer | 1 | Number of seconds before the access token is not valid anymore.
|
{ "access_token": "jDsU7dNY5mhT_PTK4_7hg5H1iQFTZ8PBKTGXQLst9kwTLqczogFu9PxNzGZ92mVUuL07fzf-p8ugMbbxhDYUZeR_TY9vhyn0YMzuFwPU8vC1NivNeu6aEi1lMcdcWc_9DhdZP03GP6FPFVeovclD2nG9rciqtuuOjrmORdrSuM0h8wnpcEzMhvfYiypj8_wEzc69cG6q907JsPGdShjkMzkQJVbv0JDU53y-gIMJ3D5kTDMMpgyQo1X7MUyiXg1BbHzbjuY8KvhUyVd-KprrhMgyU5jblORCBsD4NCsiPO0", "token_type": "bearer", "expires_in": 1800 }
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.
Name | Description |
---|---|
token_type | Type of the access token.
|
access_token | Value of the access token.
|
Authorization: bearer jDsU7dNY5mhT_PTK4_7hg5H1iQFTZ8PBKTGXQLst9kwTLqczogFu9PxNzGZ92mVUuL07fzf-p8ugMbbxhDYUZeR_TY9vhyn0YMzuFwPU8vC1NivNeu6aEi1lMcdcWc_9DhdZP03GP6FPFVeovclD2nG9rciqtuuOjrmORdrSuM0h8wnpcEzMhvfYiypj8_wEzc69cG6q907JsPGdShjkMzkQJVbv0JDU53y-gIMJ3D5kTDMMpgyQo1X7MUyiXg1BbHzbjuY8KvhUyVd-KprrhMgyU5jblORCBsD4NCsiPO0
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 |
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. |