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: mostly 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:

 
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:

 
{
  "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:

 
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 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> 

On this page you’ll find relevant updates to the Billink platform: from new features and improvements in Billink One to important bug fixes, API changes, and new PSP integrations. This way, you’ll always stay up to date on what’s changing and how it improves your checkout, integration, or customer experience.

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 lifecycle of an order: monitoring, workflow start, payment and more. It enables efficient order processing through functionalities such as checking the status of an order, 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 Reconciliation section provides access to financial data used for matching and tracking client invoices.

It currently supports:

• Retrieving a paginated list of invoices for a specified Billink client
• Downloading invoice data for further processing or reporting

The Webhooks section provides endpoints for configuring and managing webhook integrations. These endpoints allow users and merchants to receive real-time notifications related to payment sessions and order events by setting or disabling webhook URLs. This enables seamless communication between Billink and external systems, allowing for automation, event-driven workflows, and improved operational efficiency.

Webhooks Behavior

Billink provides webhook support to notify merchants of important updates to sessions and orders in real time.

📬 Retry Policy

• Webhooks are retried up to 3 times if delivery fails (e.g. server unavailable or responds with non-2xx status).
• After the 3rd failed attempt, an email notification is sent to the merchant to alert them about the failed webhook delivery.

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:

 
{
  "code": "000",
  "description": "Error message",
  "result": "error"
}

• Code: A unique error code representing the specific issue.
• Description: A detailed description of the error.
• Result: Short informative status

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:

1. Client Identification: Errors related to missing or incorrect client username, client id, or API version.
2. Invoice and Workflow Management: Missing or incorrect invoice numbers or workflow data.
3. Order Management: Trying to perform actions on orders that are not allowed or are already processed.
4. Request Limitations: Exceeding request limits (e.g., number of invoices, action frequency).
5. 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. Each of these subsections includes a list of error codes and their corresponding descriptions to help you understand and resolve issues effectively.

The Authorize payment section is focused on the creation and validation of payment orders. It enables you to perform a credit check and submit an order for processing. These two core actions ensure a secure, validated, and efficient payment flow within the Billink platform.

The Order Management section provides tools for handling the lifecycle of an order: monitoring, workflow start, payment and more. It enables efficient order processing through functionalities such as checking the status of an order, 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.

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 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:

1. Client Identification: Errors related to missing or incorrect client username, client id, or API version.
2. Invoice and Workflow Management: Missing or incorrect invoice numbers or workflow data.
3. Order Management: Trying to perform actions on orders that are not allowed or are already processed.
4. Request Limitations: Exceeding request limits (e.g., number of invoices, action frequency).
5. 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. Each of these subsections includes a list of error codes and their corresponding descriptions to help you understand and resolve issues effectively.

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

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-orange.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/PNG/billink-badge-orange.png

Preferred wide orange badge

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-orange-wide.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/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

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-white.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/PNG/billink-badge-white.png

Alternative wide badge orange on white

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-white-wide.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/PNG/billink-badge-white-wide.png

Alternative badge orange on black

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-orangeonblack.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/PNG/billink-badge-orangeonblack.png

Alternative wide badge orange on black

Download SVG https://cdn.billink.nl/assets/paybadge/v2/SVG/billink-badge-orangeonblack-wide.svg

Download PNG https://cdn.billink.nl/assets/paybadge/v2/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

EPS / SVG / PNG / AI

https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE_BILLINK_ORANGE.eps

https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE.svg

https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE.png

https://cdn.billink.nl/assets/Logov2/BILLINK_ORANGE_BILLINK_ORANGE.ai

Alternative white

EPS / SVG / PNG / AI

https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE_BILLINK_WHITE.eps

https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE.svg

https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE.png

https://cdn.billink.nl/assets/Logov2/BILLINK_WHITE_BILLINK_WHITE.ai

Alternative black

EPS / SVG / PNG / AI

https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK_BILLINK_BLACK.ai

https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK_BILLINK_BLACK.eps

https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK.png

https://cdn.billink.nl/assets/Logov2/BILLINK_BLACK.svg

Billink One

SVG / PNG

https://cdn.billink.nl/assets/Logov2/BILLINK_ONE.png

https://cdn.billink.nl/assets/Logov2/BILLINK_ONE.svg

• 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. 

Billink Toolkit Page 

For a complete overview and detailed instructions on how to perfectly integrate Billink on your webshop, please visit the Billink Toolkit Page. This page contains everything you need, including all assets and guidelines, to ensure a seamless and consistent implementation.

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.  

Billink Toolkit

For detailed guidance on how to best present Billink in your checkout, including all recommended texts and design elements, please visit the Billink Toolkit Page. This resource provides everything you need to ensure clear and consistent communication about paying afterwards with Billink. 

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 at support@billink.nl or by phone at 010 - 414 14 73.

If you still have questions, you can find answers here