Billink Documentation

The Billink API is designed with a RESTful architecture, offering developers a predictable and efficient way to integrate their applications. The API supports both JSON- and XML-encoded request and response formats, catering to a wide range of integration preferences.

The Billink API provides a robust set of endpoints for managing key operations, including user authorization, order handling, and payment processing. Key features include:

Order Management: Create orders, set orders on hold, and resume them, initiate workflows.
Payments: Create payment sessions, process payments, and track their statuses.
Messaging: Send updates and messages associated with orders.
Status Tracking: Monitor the progress and state of orders and workflows.

Unable to find the endpoint you need?

We are happy to help every business day between 9 a.m. and 8 p.m.

You can reach us directly via the chat, by phone or WhatsApp. All details you can find here.

To facilitate seamless testing and deployment, the Billink API offers two operational modes:

Sandbox Mode: A safe testing environment that allows you to experiment with API features without affecting live production data.
Production Mode: The live environment for real-world operations and customer interactions.

Currently, the API supports single-object operations per request to maintain precision and reliability. Regular updates and enhancements are introduced to improve functionality, so ensure you check the documentation for the latest features and capabilities.

Explore the available endpoints, integrate them into your workflows, and harness the flexibility of the Billink API to streamline your operations.

API URLs

Billink API provides two distinct environments to facilitate development and production operations.

Each environment is accessible via a dedicated URL:

Staging Environment: Use this environment for testing and development purposes.

URL: https://api-staging.billink.nl

Production Environment: Use this environment for live, production-level operations.

URL: https://api.billink.nl

Sandbox:

https://api-staging.billink.nl

Production:

https://api.billink.nl

The Billink API is available in two versions, Legacy API (v1) and Actual API (v2), with distinct data formats and potential differences in endpoint naming:

Actual API (v2)

Format: JSON
Request: Uses JSON for requests.
Response: Returns JSON responses.
Endpoint Naming: Endpoints may differ in naming from the Legacy API. Ensure you reference the appropriate documentation for v2 endpoints.

Legacy API (v1)

Format: XML
Request: Uses XML for requests.
Response: Returns XML responses.
Endpoint Naming: Some endpoints may have different names compared to the Actual API. Refer to the Legacy section of the documentation for specific details.

Important Notes

Backward Compatibility: Both versions coexist, but the Legacy API is primarily maintained for backward compatibility. You should verify compatibility with your application before switching to the Actual API.
Endpoint URLs: Specify the desired version in the endpoint URL:
Legacy API: https://api.example.com/v1/endpoint
Actual API: https://api.example.com/v2/endpoint

Example Request and Response

Actual API:

URL: https://api-staging.billink.nl/v2/client/invoice/credit
Request:

SHELL

 curl --location 'https://api-staging.billink.nl/v2/client/invoice/credit' \
--data '{
  "billinkID": "d38a3439590889df026367bf01ddar621e687b8d278",
  "billinkUsername": "usertest",
  "invoices": [
    {
      "creditAmount": 1.5,
      "description": "test credit",
      "number": "KRKND-0001"
    }
  ]
}'

Response:

JSON

 {
  "result": "MSG",
  "statuses": [
    {
      "code": 200,
      "invoiceNumber": "KRKND-0001",
      "message": "Credit applied: 1.50 EURO.; step restarted."
    }
  ]
}

Legacy API:

URL: https://api-staging.billink.nl/v1/client/credit
Request:

SHELL

 curl --location 'https://api-staging.billink.nl/v1/client/credit' \
--data '<API>
  <VERSION></VERSION>
  <CLIENTUSERNAME></CLIENTUSERNAME>
  <CLIENTID></CLIENTID>
  <ACTION></ACTION>
  <INVOICES>
    <ITEM>
      <INVOICENUMBER></INVOICENUMBER>
      <CREDITAMOUNT></CREDITAMOUNT>
      <DESCRIPTION></DESCRIPTION>
    </ITEM>
  </INVOICES>
</API>'

Response:

XML

<?xml version="1.0" encoding="UTF-8"?>
<API>
  <RESULT>MSG</RESULT>
  <MSG>
    <STATUSES>
      <ITEM>
        <INVOICENUMBER>123456</INVOICENUMBER>
        <MESSAGE>Credit applied: 10.95 EURO.; Order paid.</MESSAGE>
        <CODE>200</CODE>
      </ITEM>
    </STATUSES>
  </MSG>
</API> <?xml version="1.0" encoding="UTF-8"?>
<API>
  <RESULT>MSG</RESULT>
  <MSG>
    <STATUSES>
      <ITEM>
        <INVOICENUMBER>123456</INVOICENUMBER>
        <MESSAGE>Credit applied: 10.95 EURO.; Order paid.</MESSAGE>
        <CODE>200</CODE>
      </ITEM>
    </STATUSES>
  </MSG>
</API>

In Billink API, error responses follow a consistent format. All errors are returned with an HTTP status code 200, which indicates the request was processed but there was an issue with the operation.

The format of the error is as follows:

XML

<?xml version='1.0' encoding='UTF-8' ?>
<API>
    <RESULT>ERROR</RESULT>
    <ERROR>
        <CODE>000</CODE>
        <DESCRIPTION>Error message</DESCRIPTION>
    </ERROR>
</API> <?xml version='1.0' encoding='UTF-8' ?>
<API>
    <RESULT>ERROR</RESULT>
    <ERROR>
        <CODE>000</CODE>
        <DESCRIPTION>Error message</DESCRIPTION>
    </ERROR>
</API>

CODE: A unique error code representing the specific issue.
DESCRIPTION: A detailed description of the error.

These errors might indicate a variety of issues including but not limited to problems with API versioning, client authentication, missing or incorrect parameters, data format issues, and restrictions on actions (such as workflow limitations or invalid operations).

Common Issues:

Client Identification: Errors related to missing or incorrect client username, client id, or API version.
Invoice and Workflow Management: Missing or incorrect invoice numbers or workflow data.
Order Management: Trying to perform actions on orders that are not allowed or are already processed.
Request Limitations: Exceeding request limits (e.g., number of invoices, action frequency).
Parameter Validation: Incorrect or unsupported parameters in requests.

This helps you to easily handle and debug issues by following the provided error code descriptions across all API endpoints.

In the next subsections, you will see errors specific to each endpoint, such as Start Workflow API, Payment API, On Hold API, etc. Each of these subsections includes a list of error codes and their corresponding descriptions to help you understand and resolve issues effectively.

Summary of Check API Error Codes

The error codes in the Check API are designed to handle input validation, business rules enforcement, and system constraints specifically for this endpoint. They help ensure that all submitted data is accurate and adheres to predefined requirements.

Common issues include:

Errors like "Missing" or "Wrong" highlight issues with missing fields or invalid formats (e.g., missing workflow number, wrong postal code format, incorrect country code).
Some codes enforce business-specific rules, such as minimal age for ordering, allowed order amounts, or house number extension limits.
Field-specific validations ensure correctness for critical information like phone numbers, emails, company names, and birth dates.
System-related errors address issues like XML parsing failures, redirection errors, or client/customer not found.

These codes provide clear feedback for resolving errors and ensuring successful API interactions.

All available error codes and messages for Check API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
104	Missing workflow number
105	Wrong workflow number
402	Phone number should be between 9-18 characters, it can contain only digits, spaces, '+', '()' and '-' signs
406	Missing type
407	Wrong type
408	Missing company name
409	Wrong sex format
410	Last name missing
411	Missing Chamber of Commerce number
412	Missing firstname or initials
414	Missing house number
415	Missing postal code
416	Wrong postal code format
417	Missing phone number
418	Wrong birth date format. Expected dd-mm-yyyy
419	Missing email
420	Wrong email format
421	Missing birth date
422	Minimal age for ordering through Billink is 18
424	Wrong house number format
425	Wrong delivery house number format
426	Delivery address not allowed
427	Missing order amount
428	Wrong order amount
429	Amount is bigger than allowed
430	Company name must be between 2 and 50 characters long
431	Housenumber extension must be between 0 and 10 characters long
432	Wrong check type provided
433	Incorrect country code
434	Missing city
435	Wrong paytrust score
601	Errors parsing xml file
603	Redirect Billink API error
607	Client or customer not found
701	Credit check not OK
703	Missing financial arrangement

Summary of Order API Error Codes

The error codes for the Order API mostly focus on missing or incorrect data in the request. These errors are related to validation of the order details and the customer information.

Common issues include:

Missing or incorrect details (e.g., missing workflow number, phone number, email, or company name).
Wrong formats (e.g., incorrect postal code, sex format, or order number).
Validation errors for fields like bank account number, invoice numbers, and Chamber of Commerce number.
Issues with credit checks, age validation, and missing order items.

The codes also handle more specific scenarios such as workflow errors, item code length, amount validation, and IP or country code format errors.

All available error codes and messages for Order API:

Title

Description

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
401	Missing workflow number
402	Workflow with number %id% does not exist
403	Order with number %number% already exists
404	Missing order number
405	Missing date
406	Missing type
407	Wrong type
408	Missing company name
409	Firstname or initials missing
410	Last name missing
411	Missing sex
412	Wrong sex format
413	Missing street
414	Missing house number
415	Missing postal code
416	Missing city
417	Missing phone number
418	Missing email
419	City name should contain only letters, spaces, - and ' signs
420	Incorrect country code, see ISO 3166
421	Missing birth date
422	Wrong IP address format
423	Missing order items
425	Missing bank account number
426	Missing bank account holder
427	Missing chamber of commerce number
428	Item code is too long
429	Wrong format of Chamber of Commerce number, must be between 5 and 25 characters long
430	Wrong BTW value, should be %vat_values%.
431	Wrong vat number format
432	Wrong email format
433	Wrong email2 format
434	Order number not according to validation. Allow only alphanumeric, _ (underscore) and - (hyphen)
435	Amount is missing in order item
436	Merchant invoice number is not according to validation. Allow only alphanumeric, _ (underscore) and - (hyphen).
437	Missing additional text
438	Additional text is not according to validation. Allow only alphanumeric, _ (underscore) and - (hyphen)
439	Invoice number is too long. Maximum of 50 characters allowed
440	Check request with given uuid not found
441	Wrong mandate id format, should contain only digits
442	Wrong mandate type format, should be: 'FIRST', 'RECURRING', 'ONETIME'
443	Please provide valid iban/bank account number.
444	Order amount is bigger than requested
445	Check request with given uuid has already expired
446	Check request with given uuid already has been used
447	Missing check request uuid
448	Company name must be between 2 and 50 characters long
449	Phone number can contain only digits, spaces and - signs
450	Housenumber extension must be between 0 and 10 characters long
451	Workflow without guarantee is used for check request.
452	Amount is bigger than allowed.
453	Minimum age for ordering via Billink is 16.
601	Errors parsing xml file
603	Redirect Billink API error
701	Credit check not

Summary of Credit API Error Codes

The error codes for the Credit API focus on workflow issues, order validation, and invoice management.

Common problems include:

Unknown details such as API version, client username, or client id.
Workflow errors related to missing or incorrect workflow numbers.
Order errors like trying to apply credit to an order that already exists or cannot be managed at the current stage.
Invalid data such as empty or missing XML files, or missing invoices.
Access control issues, such as being unable to manage an order or apply credit at a certain stage.

All available error codes and messages for Credit API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
402	Workflow with number %number% does not exist
404	Order with number %number% already exists
601	XML empty or not found
603	Redirect Billink API error
705	No invoices provided
706	You are not allowed to manage this order
707	Credit cannot be applied at this stage
708	Credit cannot be applied at this stage(0)

Summary of Status API Error Codes

The Status API error codes mainly address issues related to client identification, request limitations, and invoice data handling.

Common problems include:

Unknown details such as API version, client username, or client id.
Request limits such as exceeding the maximum number of invoices per request or overall request limits.
Missing invoice data or errors in parsing the XML file.
Redirect issues related to the Billink API.

All available error codes and messages for Status API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
110	Limit is 100 invoices per request
111	Request limit exceeded
420	Missing invoice numbers
601	Errors parsing xml file
603	Redirect Billink API error
705	No invoices provided

Summary of Start Workflow API Error Codes

The Start Workflow API error codes mainly focus on issues related to client identification, invoice validation, workflow management, and request limitations.

Common problems include:

Unknown details such as API version, client username, or client id.
Invoice validation issues, such as missing or unknown invoice numbers.
Workflow errors, such as trying to start a workflow when it's already been started or when you're not authorized to manage the order.
Request limits, such as exceeding the maximum allowed invoices per request.

All available error codes and messages for Start Workflow API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
603	Redirect Billink API error
704	Unknown invoice number
705	No invoices provided
706	You are not allowed to manage this order
707	Order workflow is already started
708	Maximum 10 invoices per request allowed

Summary of Payment API Error Codes

The Payment API error codes mainly address issues related to client identification, invoice management, and order status.

Common problems include:

Unknown details such as API version, client username, or client id.
Invoice-related errors, such as missing or unknown invoice numbers.
Order management issues, including trying to manage an order you are not authorized to manage or attempting to pay an order that's already paid.
Description length errors, such as exceeding the character limit for payment descriptions.

All available error codes and messages for Payment API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
102	Unknown client username or client id
103	Unknown action
402	Workflow with number %number% does not exist
420	Missing invoice numbers
603	Redirect Billink API error
704	Unknown invoice number
706	You are not allowed to manage this order
707	Order is already paid
708	Description is too long (max. 30 characters)

Summary of On Hold API Error Codes

The On Hold API error codes mainly address issues related to client identification, invoice and workflow management, and order hold status.

Common problems include:

Unknown details such as API version, client username, or client id.
Missing or incorrect invoice or workflow numbers.
Hold period issues, such as exceeding the maximum allowed duration due to guaranteed payment restrictions.
Order management errors, such as trying to set an order on hold when it's not possible or using unsupported parameters for resuming the order.

All available error codes and messages for On Hold API:

Code

Message

001	Unknown API version
101	Unknown client username or client id
103	Unknown action
104	Unsupported param for resume
401	Missing invoice number or workflow number
402	Unknown invoice number or workflow number
403	On hold period is too long, because of guaranteed payment (max 14 days)
603	Redirect Billink API error
701	Order cannot be set on hold

The Client Management section allows users to view and manage client information within the system. Users can retrieve details about clients, update their information, and perform other actions related to client management. This section provides essential functionalities to efficiently handle client-related tasks.

The Payment Session Management section facilitates the creation and monitoring of payment sessions, ensuring a smooth and streamlined payment process for users. This section enables you to initialize payment sessions and check their current status, providing real-time insights into the payment lifecycle. These capabilities are vital for delivering a secure and efficient payment experience.

The Order Management section provides tools for handling the complete lifecycle of an order, from creation to monitoring and advanced workflows. It enables efficient order processing through functionalities such as checking the status of an order, creating new orders, evaluating consumer creditworthiness, adding messages to orders, and managing workflows by placing orders on hold or resuming them. These features ensure seamless integration, accurate tracking, and streamlined operations for order management.

Please note that the described endpoints include only a few examples of error responses. For a comprehensive list of error codes and messages, refer to the Errors section.

The Legacy endpoints section provides access to deprecated API functionalities for backward compatibility purposes. Users can leverage these endpoints to interact with older versions of the API and maintain compatibility with legacy systems. This section serves as a bridge for transitioning to newer API versions while ensuring existing integrations continue to function seamlessly.

Welcome to our brand Toolkit. Here you can find the logos that you can use in your webshop. Place the Billink logo where you also have the logos of other payment methods. The logos can be placed in the check-out, footer, and for example the productpage and the landingpages.

The payment badges are aimed at implementation in the checkout. Below you can download the Billink badges in SVG (optimal for web implementation) and PNG format. The orange badge is our preferred badge. Below there are 2 alternative badges, white with orange and black with orange.

The preferred orange badge ensures the greatest recognisability for consumers in the check-out and will be most often used by other web shops.

Default badges:

Preferred orange badge

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-orange.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-orange.png

Preferred wide orange badge

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-orange-wide.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-orange-wide.png

When you have a good reason to not use the orange badge, there are two alternatives. The white with orange badge and the black with orange badge.

When you want to use it, use the one with the highest contrast with the background.

Alternative badge orange on white

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-white.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-white.png

Alternative wide badge orange on white

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-white-wide.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-white-wide.png

Alternative badge orange on black

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-orangeonblack.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-orangeonblack.png

Alternative wide badge orange on black

xDownload SVGx https://cdn.billink.nl/assets/paybadge/svg/billink-badge-orangeonblack-wide.svg

xDownload PNGx https://cdn.billink.nl/assets/paybadge/png/billink-badge-orangeonblack-wide.png

The logos are each offered in SVG (optimal for web implementation), AI, EPS, and 5 different sizes of PNG files.

Default orange

xAIx / xEPSx

xDownload SVGx https://cdn.billink.nl/assets/lockup/svg/billink-logo-default.svg

xDownload PNG 126x34x https://cdn.billink.nl/assets/lockup/png/billink-logo-default-126x34.png

xDownload PNG 189x51x https://cdn.billink.nl/assets/lockup/png/billink-logo-default-189x51.png

xDownload PNG 252x68x https://cdn.billink.nl/assets/lockup/png/billink-logo-default-252x68.png

xDownload PNG 503x135x https://cdn.billink.nl/assets/lockup/png/billink-logo-default-503x135.png

xDownload PNG 1005x268x https://cdn.billink.nl/assets/lockup/png/billink-logo-default-1005x268.png

Alternative white

xAIx / xEPSx

xDownload SVGx https://cdn.billink.nl/assets/lockup/svg/billink-logo-white.svg

xDownload PNG 126x34x https://cdn.billink.nl/assets/lockup/png/billink-logo-white-126x34.png

xDownload PNG 189x51x https://cdn.billink.nl/assets/lockup/png/billink-logo-white-189x51.png

xDownload PNG 252x68x https://cdn.billink.nl/assets/lockup/png/billink-logo-white-252x68.png

xDownload PNG 503x135x https://cdn.billink.nl/assets/lockup/png/billink-logo-white-503x135.png

xDownload PNG 1005x268x https://cdn.billink.nl/assets/lockup/png/billink-logo-white-1005x268.png

Alternative black

xAIx / xEPSx

xDownload SVGx https://cdn.billink.nl/assets/lockup/svg/billink-logo-black.svg

xDownload PNG 126x34x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-126x34.png

xDownload PNG 189x51x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-189x51.png

xDownload PNG 252x68x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-252x68.png

xDownload PNG 503x135x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-503x135.png

xDownload PNG 1005x268x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-1005x268.png

Alternative black monochrome

xAIx / xEPSx

xDownload SVGx https://cdn.billink.nl/assets/lockup/svg/billink-logo-black.svg

xDownload PNG 126x34x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-126x34.png

xDownload PNG 189x51x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-189x51.png

xDownload PNG 252x68x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-252x68.png

xDownload PNG 503x135x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-503x135.png

xDownload PNG 1005x268x https://cdn.billink.nl/assets/lockup/png/billink-logo-black-1005x268.png

Orange

#F28D20

R242 G141 B32

Black

#000000

R00 G00 B00

Teal

#49B2A6

R73 G178 B166

Refer directly to the source images that are shown above and are hosted on CDN.Billink.nl.
Preferably make use of the SVG files regarding scalability.

We recommend that you implement the logos with a direct link to the source image as we made available above. For this we have setup a so-called CDN (Content Delivery Network) to guarantee loading times of just a few milliseconds. The advantage of a link to the source files is that you are always guaranteed for the most current logos and badges in line with the final brand strategy of Billink.

To clearly display Billink at checkout, it is important to mention that the customer can pay afterwards. This is central to how we communicate as a company. Always use the following text next to or behind the Billink logo:

Pay afterwards with Billink
Pay later with Billink
Pay afterwards

These formulations are clear and directly inform the customer about the possibility of paying afterwards via Billink. It is essential to always display these texts at checkout.

Example:

Do you need an alternative format which is not listed on this page or do you have a different question about the deployment of logos? Send an e-mail to marketing@billink.nl.

We look forward to a successful collaboration.

If you need help with the integration, we are happy to assist you. You can reach us on weekdays from 09:00 to 20:00 at support@billink.nl or by phone at 010 - 414 14 73.

If you still have questions, you can find answers here

Sections

Introduction

Unable to find the endpoint you need?

API URLs

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

What made this section unhelpful for you?

API Versions

Actual API (v2)

Legacy API (v1)

Important Notes

Example Request and Response

Actual API:

Legacy API:

What made this section unhelpful for you?

Errors

Common Issues:

What made this section unhelpful for you?

Check API

Summary of Check API Error Codes

001

Unknown API version

101

Unknown client username or client id

102

Unknown client username or client id

103

Unknown action

104

Missing workflow number

105

Wrong workflow number

402

Phone number should be between 9-18 characters, it can contain only digits, spaces, '+', '()' and '-' signs

406

Missing type

407

Wrong type

408

Missing company name

409

Wrong sex format

410

Last name missing

411

Missing Chamber of Commerce number

412

Missing firstname or initials

414

Missing house number

415

Missing postal code

416

Wrong postal code format

417

Missing phone number

418

Wrong birth date format. Expected dd-mm-yyyy

419

Missing email

420

Wrong email format

421

Missing birth date

422

Minimal age for ordering through Billink is 18

424

Wrong house number format

425

Wrong delivery house number format

426

Delivery address not allowed