Credifin API: Automate your Direct Debit

Strategy: choosing the right logic

In CollectOnline, a case (also called file) represents a complete collection process. Through the Recover API you create these cases and manage them from your own system. In this documentation we combine the logic of the front-end system with concrete API examples, so you can set up your connection step by step.

When setting up your link, you make a fundamental choice: how do you group invoices into a file? There are two methods.

Option A: Invoice logic.

Use this method if you rely on CollectOnline's standard business rules. The system then automatically determines whether to create a new file or add an invoice to a current file.

The main rules:

Legal status: Is a file already in the legal phase (e.g. with the bailiff)? Then the system automatically creates a new file.
Amicable status: Is an amicable file already in progress against the same debtor from the same client? Then a new invoice, credit note or payment will be added to that existing file.
Payment arrangement: Is there an active payment arrangement? Then a new invoice will be attached to the same file.
Legislation: Rules such as Book XIX and Wki are automatically applied by the system.

Option B: Case logic.

Use this method if you want full control over filing yourself.

With dossier logic, a unique reference number is required when creating a dossier. As developer, you determine exactly which financial transactions (invoices, credit notes, payments) are linked to which file. In doing so, you deliberately overrule CollectOnline's standard business logic.

Note that if you use file logic, then you are responsible for the correct mapping of all financial rules and the correct application of relevant legislation (such as Book XIX and Wki).

Best practice: preferably start with invoice logic, unless you have very specific proprietary filing or complex internal logic that you want to port 1-to-1 to CollectOnline.

Authentication and access

To use the API, you need an API key. The type of key determines which endpoints you can access.

Type API keys

Collection API key: Full access to all endpoints.
Creditor API key: Limited access, only to your own files and data.
Bailiff API key: Access specific bailiff functions, such as legal proceedings, fees and third-party funds.

Creating API key

Log in to CollectOnline.
In the menu, go to Settings → Web Service Documentation.
Click Create API Key (or Overwrite if you want to refresh an existing key).
Copy the key via Copy API Key. This is your secret authentication key.
Note the Base URL above the key. You will use this in all your requests.

Authentication in your request

You include the API key in the header of each request.

Header Example (HTTP):
Api-Key: your-unique-api-key

Base URL example:
https://jouwbedrijf.collectonline.eu/api/

Connection testing

You can test your connection via cURL or Postman.

Example via cURL (command line):
curl -H 'Api-Key: your-unique-api-key' https://jouwbedrijf.collectonline.eu/api/debtor

Example via Postman:

Method: GET
URL: https://jouwbedrijf.collectonline.eu/api/debtor
Header key: Api-Key
Header value: your-api-key-here

Example responses and error codes

Success Example (simplified):
{
'status': 'success',
'data': [ { 'uuid': 'debtor-uuid', 'name': 'Example Debtor' } ]
}

Invalid or missing API key (401 Unauthorized):
{
'status': 'error',
'code': 401,
'message': 'Unauthorized: invalid or missing API key'
}

Best practice:

Always use a separate API key per environment (for example, test and production).
Never store your API key in front-end code or public repositories.
Limit the privileges of a Creditor API key to what is strictly necessary.

Legislation and compliance rules

The system supports specific consumer protection legislation in Belgium and the Netherlands. Much of this logic is automatically enforced, especially if you use invoice logic.

Book XIX (Belgium)

Book XIX of the Code of Economic Law regulates amicable recovery from Belgian consumers. Among other things, the law prescribes mandatory waiting periods, notifications and forms of communication.

Application in the API
When you create a file or invoice, the system checks, among other things:

Is the debtor a Belgian consumer?
Does the legislation apply to the principal?

If so, mandatory fields and deadlines are enforced. For proper control, one of the things you use in your JSON are these fields:

firstReminderDate: Date of the first reminder.
firstReminderMethod: Shipping method of the first reminder.
firstReminderInterval: Interval period between reminders.
SME: Indication of whether the creditor is an SME (affects the cost ceiling).
BookXIXDefaultEnabled: Enables the default Book XIX logic.
BookXIXSubstractCost: Setting for settlement of costs.

Example Book XIX payload fragment:
{
'country': 'BE',
'debtorType': 'consumer',
'firstReminderDate': '2026-03-01',
'firstReminderMethod': 'EMAIL',
'firstReminderInterval': 14,
'SME': true,
'BookXIXDefaultEnabled': true,
'BookXIXSubstractCost': false
}

Wki (Netherlands)

The Quality Collection Services Act (Wki) applies to claims against consumers and sole proprietors (EZ, VOF, private individual) for files you create from Oct. 1, 2024.

Arithmetic rules Wki:

Collection fees (WIK) may only be charged once for every 6 consecutive invoices or installments.
It is calculated based on the highest invoice amount within that range of 6.
After the 7th installment, a new series starts, where again one charge may be made.
On a new file, the system checks whether the debtor already had an invoice with the same client in the past 6 months so that the graduated scale is applied correctly.

Practical Wki example (installment invoices):
You send 6 monthly installments of 100 euros to the same debtor. The API charges one collection fee on 100 euros for that series of 6. From installment 7 a new series starts.

Important:

Are you using invoice logic? Then CollectOnline automatically applies the rules of Book XIX and Wki.
Are you using file logic? Then you are responsible for the correct application of Book XIX and Wki, including proper passing of dates, country codes and debtor type.

Best practice: with each file, send at least the country, type of debtor (consumer or business) and the relevant invoice and reminder dates. This allows the API to directly test whether Book XIX or Wki should be active.

Data standards (best practices)

Always use established ISO standards to avoid import errors. This way you avoid format discussions and the API validates your data better.

Language: lowercase, ISO 639-1 (for example: nl, fr, de, en, it).
Country: capital letters, ISO 3166-1 (for example: BE, NL, LU).
Currency: uppercase letters, ISO 4217 with 3 characters (for example: EUR, GBP, USD). If you do not include a value, EUR is used.
Date: Format YYYY-MM-DD (for example: 2026-03-15).
Date and time: Format YYYY-MM-DD UU:mm:ss.

Example combination in an invoice payload:
{
'language': 'nl',
'country': 'NL',
'currency': 'EUR',
'invoiceDate': '2026-03-15',
'dueDate': '2026-03-30',
'createdAt': '2026-03-15 10:30:00'
}

Best practice: validate these formats already in your own application before you send a request. This will prevent unnecessary error messages and repeated calls.

Roadmap: end-to-end integration

Below you can see the workflow for building a complete file through the API. This process works based on UUIDs for each entity.

Step 1: Identify or create entities

Before you can enroll an invoice, the parties involved must exist and have a UUID.

A. Debtor (Debtor).

Create: POST /api/debtor
Search: GET /api/debtor
Address retrieval: GET /api/debtor/{debtor}/address
Contact retrieval: GET /api/debtor/{debtor}/contact

Example request (POST /api/debtor):
{
'externalReference': 'DEB-1001',
'name': 'Example Debtor BV',
'country': 'NL',
'language': 'nl',
'email': 'debiteur@example.com'
}

Result: you receive a Debtor UUID.

B. Principal (Creditor).

Create: POST /api/creditor
Search: GET /api/creditor

Sample request (POST /api/creditor):
{
'externalReference': 'CRED-2001',
'name': 'Your Company BV',
'country': 'NL',
'language': 'nl'
}

Result: you receive a Creditor UUID.

C. File (Case)

Create: POST /api/file
Search: GET /api/file

Sample request (POST /api/file, file logic):
{
'externalReference': 'DOS-3001',
'debtor': 'debtor-uuid',
'creditor': 'creditor-uuid',
'country': 'NL',
'debtorType': 'consumer'
}

Result: you receive a File UUID.

Step 2: Invoice creation

You link the invoice (POST /api/invoice) in one of two ways.

Method 1: Through the debtor (debtor based)

Mandatory field: Debtor (UUID). The system looks for the correct file with it itself based on the invoice logic.

Example:
{
'debtor': 'debtor-uuid',
'invoiceNumber': '2026-0001',
'amount': 250.00,
'currency': 'EUR',
'invoiceDate': '2026-03-01',
'dueDate': '2026-03-31'
}

Method 2: Through the file (file-based).

Required fields: File (UUID) and Creditor (UUID). The invoice will be hard linked to the specific file you designate.

Example:
{
'file': 'file-uuid',
'creditor': 'creditor-uuid',
'invoiceNumber': '2026-0002',
'amount': 500.00,
'currency': 'EUR',
'invoiceDate': '2026-03-05',
'dueDate': '2026-03-20'
}

Result: you receive an Invoice UUID.

Sample installment invoices (Wki scenario).

For a series of 6 monthly installments, send 6 invoices with the same file or debtor. The API guards that collection fees are calculated only once per series.

Example first installment:
{
'file': 'file-uuid',
'invoiceNumber': 'TERM-001',
'amount': 100.00,
'isInstallment': true,
'installmentSeries': 'ABO-2026-01'
}

Example second installment:
{
'file': 'file-uuid',
'invoiceNumber': 'TERM-002',
'amount': 100.00,
'isInstallment': true,
'installmentSeries': 'ABO-2026-01'
}

Step 3: Follow-up actions and enrichment

Add payment

Endpoint: POST /api/payment
Via Debtor UUID (field: debtor) or File UUID (field: file)

Example:
{
'file': 'file-uuid',
'amount': 100.00,
'paymentDate': '2026-03-10',
'method': 'BANK_TRANSFER'
}

Result: you receive a Payment UUID.

Adding metadata to file

Endpoint: POST /api/file/{dossier}/meta
Retrieve all meta fields: GET /api/file/{dossier}/meta

Example:
{
'key': 'internalSegment',
'value': 'high-risk'
}

Adding attachments

To file: POST /api/file/{dossier}/attachment
To invoice: POST /api/invoice/{invoice}/attachment (for example, the original PDF)

Result: you receive an Attachment UUID.

Creating a credit note

Endpoint: POST /api/creditnote
Via Debtor UUID (field: debtor) or File UUID (field: file)

Example:
{
'file': 'file-uuid',
'originalInvoice': 'invoice-uuid',
'amount': 50.00,
'reason': 'Discount agreed with customer'
}

Best practice: build an internal flow in which you always check whether debtor, creditor and file exist (and have a valid UUID) before creating an invoice or payment. This way you keep your data model clean and avoid loose invoices without useful context.

Help and complete reference

This guide covers the most important workflows for your integration. For the complete list of available endpoints, parameters and response codes, use the interactive documentation in the portal.

Where can you find the technical details?

Log in to CollectOnline.
Go to Settings → Web Service Documentation.
Open the Swagger or OpenAPI documentation.

There you can:

Viewing all endpoints and HTTP methods.
View exact JSON schemas for requests and responses.
Test live calls with your own API key.

Common HTTP status codes

200 OK: Request successful, data present.
201 Created: New resource created successfully (for example, debtor, file, invoice).
400 Bad Request: Request is invalid, for example due to missing or incorrectly formatted fields.
401 Unauthorized: API key is missing or invalid.
403 Forbidden: API key is valid, but does not have permissions for this endpoint.
404 Not Found: The requested resource or endpoint does not exist.
500 Internal Server Error: Something went wrong on the server side.

Example 400 error response:
{
'status': 'error',
'code': 400,
'message': 'Validation failed',
'errors': {
'invoiceDate': 'Invalid date format, expected YYYY-MM-DD',
'amount': 'Amount must be greater than 0'
}
}