Introduction

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

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

4.3 Retrieve a check-out

Retrieve an existing check out by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the check out.

5.3 Retrieve a debtor

Retrieve an existing debtor by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the debtor.

5.4 Update a debtor

Update several parts of an existing debtor by calling the following URL via the HTTP-PATCH method. The third parameter in the URL is the identifier of the group. The last parameter in the URL is the identifier of the debtor.

6 Transactions

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

6.1 Retrieve all transactions

Retrieve all transactions linked to a specific debtor, by calling the following URL via the HTTP-GET method. The third parameter in the URL is the identifier of the group. The second-last parameter in the URL is the identifier of the debtor.

10 Pagination

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

10.1 Request

To override the default pagination, use the following query string. This example returns the items 0 to 99.

-

?limit=100&start=0

The following parameters can occur within the URL:

Name

Format

Length

Mandatory

Description

limit

Integer

3

No

Maximum number of items returned.

When the limit is not within the query string, the default value 100 is used.

start

Integer

10

No

Number of the first item.

When the start is not within the query string, the default value 0 is used.

10.2 Response

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

Name

Format

Length

Description

pagination_limit

Integer

36

Maximum number of items returned.

pagination_start

Integer

36

Number of the start item.

pagination_total_items

Integer

255

Number of the total items.

11 Status notifications

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

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

11.2 Response

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

12 Placeholders

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

Placeholder

Description

DEBTOR_NAME

Name of the debtor.

MERCHANT_NAME

Name of the merchant.

MERCHANT_REFERENCE

Reference, generated by the merchant, linked to the check-out or debtor.

NUMBER_OF_PERIODS

Number of payment periods, required to collect the total amount.

PAYMENT_URL

URL of the payment page, where the debtor can finalize an open payment.

PERIOD_AMOUNT

Transaction amount of the payment period.

Will be presented in the currency format.

PERIOD_NUMBER

Number of the payment period.

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

Code Examples:

14.1.2 Request

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

Name

Mandatory

Description

grant_type

Yes

oAuth2.0 type to indicate which grant method is being used.

Value must be password

username

Yes

Username of your account at AutoCollect.

Is delivered by the account manager, together with the merchant reference, unique secret key (for hashing purposes) and password.

password

Yes

Hashed value of your password of your AutoCollect account.

Password is delivered in plain text by the account manager, together with the merchant reference, unique secret key (for hashing purposes) and username.

See section below on how to hash the plain-text password

Hash the password

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

PasswordSUPER-SECRET

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