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 | MaV | 2017-01-25 | Initial version. |
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.
|
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.
|
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.
|
After a successful request, the HTTP status code 201 Created will be returned. See chapter 2.1.2 for the response parameters.
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.
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.
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. |
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.
|
debtors | 1 | Array | - | No | List of debtors.
|
reference | 2 | String | 255 | Yes | Own unique reference of the debtor. |
name | 2 | String | 255 | No | Name of the debtor.
|
iban | 2 | String | 34 | No | IBAN of the debtor.
|
bic | 2 | String | 50 | No | BIC of the given IBAN. |
phone_number | 2 | String | 13 | No | Phone number of the debtor, in an ISO20022 format.
|
2 | String | 255 | No | Email address of the debtor | |
currency | 2 | String | 3 | No | Currency for each transaction.
|
locale | 2 | String | 5 | No | Preferred language and region setting, in an ISO15897 format. |
total_amount | 2 | Decimal | 6,2 | Yes | Total amount that needs to be collected from the debtor.
|
no_direct_debit | 2 | Boolean | 5 | No | TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
|
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 | 2 | String | 5 | Preferred language and region setting, in an ISO15897 format. |
number_of_debtors | 1 | Integer | 10 | Number of debtors linked to the group. |
page_content_settings | 1 | Object | 1 | Object with settings used within the payment page.
|
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. |
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.
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.
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 ISO20022 format. |
1 | String | 255 | No | Email address of the debtor. | |
currency | 1 | String | 3 | No | Currency for each transaction.
|
locale | 1 | String | 5 | No | Preferred language and region setting, in an ISO15897 format. |
total_amount | 1 | Decimal | 6,2 | Yes | Total amount that needs to be collected from the debtor.
|
transaction_fee | 1 | Decimal | 6,2 | No | Amount of the fee per transaction.
|
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.
|
After a successful request, the HTTP status code 201 Created will be returned.
Name | Level | Format | Length | Description |
---|---|---|---|---|
check_out_id | 1 | String | 40 | Unique identifier of the check out. |
group_id | 1 | String | 40 | Unique identifier of an existing group. |
payment_plan_id | 1 | String | 40 | Unique identifier of an existing payment plan. |
reference | 1 | String | 255 | Own unique reference of the debtor. |
name | 1 | String | 255 | Name of the debtor. |
iban | 1 | String | 34 | IBAN of the debtor. |
bic | 1 | String | 50 | BIC of the given IBAN. |
phone_number | 1 | String | 13 | Phone number of the debtor, in an ISO20022 format. |
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.
|
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. |
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.
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.
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.
GET | /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 ISO20022 format.
|
1 | String | 255 | No | Email address of the debtor. | |
currency | 1 | String | 3 | No | Currency for each transaction.
|
locale | 1 | String | 5 | No | Preferred language and region setting, in an ISO15897 format. |
total_amount | 1 | Decimal | 6,2 | Yes | Total amount that needs to be collected from the debtor.
|
transaction_fee | 1 | Decimal | 6,2 | No | Amount of the fee per transaction.
|
no_direct_debit | 2 | Boolean | 5 | Yes | TRUE for skipping DirectDebit as the first payment method. Regardless of the payment plan setup.
|
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.
|
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 ISO20022 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.
|
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. |
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.
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.
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 ISO20022 format.
|
1 | String | 255 | No | Email address of the debtor
|
After a successful request, the HTTP status code 201 Created will be returned. See chapter 5.1.2 for the response parameters.
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 ISO20022 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.
|
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.
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.
|
After a successful request, the HTTP status code 201 Created will be returned.
Name | Level | Format | Length | Description |
---|---|---|---|---|
transaction_payment_id | 1 | String | 40 | Unique identifier of the payment. |
transaction_id | 1 | String | 40 | Unique identifier of the transaction. |
debtor_id | 1 | String | 40 | Unique identifier of the debtor. |
group_id | 1 | String | 40 | Unique identifier of the group. |
payment_plan_id | 1 | String | 40 | Unique identifier of the payment plan. |
debtor_name | 1 | String | 255 | Name of the debtor. |
debtor_iban | 1 | String | 34 | IBAN of the debtor. |
debtor_bic | 1 | String | 50 | BIC of the given IBAN. |
debtor_phone_number | 1 | String | 13 | Phone number of the debtor, in an ISO20022 format. |
debtor_email | 1 | String | 255 | Email address of the debtor |
started_on | 1 | DateTime UTC | 25 | Date and time of when the payment is started. |
payment_method | 1 | String | 50 | Method of the transaction payment.
|
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. |
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.
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.
To search within all entity items, the URL needs to be extended with the word search and called via the HTTP-POST method.
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 |
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.
|
After a successful request, the HTTP status code 200 OK will be returned. See chapter 5.1.2 for the response parameters.
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 |
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.
|
After a successful request, the HTTP status code 200 OK will be returned. See chapter 6.1.1 for the response parameters.
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.
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 |
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.
|
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. |
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 5.2) or Retrieve a transaction payment (see chapter 6.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. |
group_id | 1 | String | 40 | Unique identifier of the group. |
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 |
---|---|
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).
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 |