New payment URLs
Following the decommissioning of the Payconiq brand in Belgium, these URL changes are essential to ensure compliance and
mark the final phase in aligning our branding with the new Bancontact Pro identity.

Please implement adaptations described here promptly to avoid service interruptions and guarantee the continued acceptance of mobile payments via Bancontact Pay and Wero.

Changes are already available in our pre-production environement and will be rolled out in production starting 11/05/2026

# Getting Started

Before getting started on your integration, please make sure to follow the instructions below.

## The Bancontact Pro Brand Guidelines

To ensure a consistent and professional representation of our brand across all platforms and integrations, we have established a set of brand usage guidelines which can be found [here](https://brand.bancontactpro.com/).

Following these guidelines helps maintain brand integrity and ensures a cohesive user experience for all stakeholders. Please review and adhere to these standards when referencing or displaying our brand in connection with your integration.

## Merchant Onboarding

Merchant Onboarding refers to the process of setting up a Bancontact Pro account on the Bancontact Pro Payment Acceptance Service in order to interact with the API endpoints.

As part of the onboarding process, you will receive:

* A unique **API key** and/or **JWS key**.
* A unique **Product Profile Identifier** or **PPID** for each product.


These elements will be required when interacting with the Bancontact endpoints.

In case you use multiple products, you will receive one unique API Key per product. In our production environement he API keys and the information of the products they belong to will be accessible directly from your Bancontact Pro portal.

If you do not have a Bancontact Pro account yet, please make sure to request one on here. 

If you already have a Bancontact Pro account and require a new API keys

* In production: please request it through the Bancontact Pro portal. Alternatively, please reach out to our Support Team or to your dedicated Account Manager.
* In pre-production: please request it through devsupport@bancontact.com


## Available Environments

Two different environments will be exposed to the Merchants and/or their integrators:

* The Pre-Production Environment (PREPROD): merchant.api.preprod.bancontact.net
* The Production Environment (PROD): merchant.api.bancontact.net


All requests to the Bancontact payment system are authenticated using API keys.
The API key is set in the header of the requests via HTTP Authorization header.

All requests are encrypted using TLS 1.2 or TLS 1.3 and must be made over HTTPS, any calls made over unencrypted Http will fail.
Wrong API keys or API requests without an API keys will also fail.

### Pre-Production Environment

The Pre-Production Environement is  ideal to handle all tests and integration work prior to moving onto the Production Environement, as none of the tests performed here will hit the Production Environment of the real Banking Environment.

To request an account on our pre-Production Environment, please email us at devsupport@bancontact.com with the following information:

* Company Name:
* Merchant ID (MID): (your unique Merchant Identifier. You can retrieve it from your Merchant Portal)
* Point of Contact:
  * Name:
  * Surname:
  * Email:
  * Phone Number:
* Type of Integration:


The available types of integration for testing are the following:

* **On a Display**: A one-time usage digital QR code will be generated by your system and shown on a consumer-facing screen. Your consumers scan the QR code with their preferred payment application and confirm the transaction.
* **On a Receipt**: A one-time usage QR code is printed by your ECR system on your receipts. Your consumers scan the QR code with their preferred payment application and confirm the transaction.
* **Static QR**:A printed static QR code is linked to your cash register or your point of sale (PoS). Your PoS sends the payment information to the QR code, your consumers scan the QR code with their preferred payment application and confirm the transaction.
* **Top Up**: Closed loop payment system to top up payment cards or wristbands. Ideal for festivals, employee cards, student cards…etc. You print a fixed payment QR code on a top-up medium of your choosing, your consumers scan the QR code with their preferred payment application and confirm the transaction.


Once we receive your email, a member of our Dev Support Team will
create your pre-production account and will provide you, for each integration type:

* **Product Profile ID (PPID)**: Unique product identifier
* **API Key**: Used to secure the request between the Merchant’s backend and Bancontact's backend. Do not share your API keys in public areas such as online sites or client-side code.


Please note that processing your request may take up to **2 weeks**.

### Production Environment

In this environement, all transactions will hit the  real Banking Environment. As a result, **all transactions will be debited from the payer's account** and will be credited to the corresponding Payout IBAN.

**Important Note**: it is  highly recommended to request a sign-off on the Pre-Production Environment before moving on to the Production Environment.

## Bancontact Pay app

In order to test transactions and validate your integration with the Bancontact Pro Acceptance Service end-to-end, you will need to use the Bancontact Pay app.

To install and activate the app, please follow the instructions below.

If you require any assistance or encounter any issues during the process, please reach out to testappsupport@bancontact.com with a description of the encountered issue and the following information:

* Account details: phone number **and** email address
* App version


### Step-by-step installation guide

**Important Note: before proceeding with the steps below, please make sure there are no other Bancontact Pay apps installed on your device. Having multiple versions installed can cause redirection issues. Delete the PRODUCTION app before downloading the PRE-PRODUCTION (EXT) version.**

Start by downloading Bancontact Pay app and install it on your device.

* The **PREPROD Build** of the app can be downloaded via the following [form](https://tally.so/r/nP8P1Q).
* The **PROD Build** of the app can be downloaded via both the App Store (iOS) and the Google Play Store.


For our pre-production app, once obtained, open it and follow the intructions below:

1. Select: Continue **"I don't have itsme"**
2. Email address:
  1. Enter your email address
  2. Enter the code **123456** (no OTP code will be sent by email)
3. Enter your first name and last name (only applicable if you are a new user)
4. Phone number
  1. Enter your phone number (must be an EU phone number)
  2. Enter the code **123456** (no OTP code will be sent by SMS)
5. Set a PIN code. It will be used to validate payments.
6. Either activate Biometric or skip the step.
7. Add a Bancontact card from the list here below
8. Select the bank of the card.
9. Input the bank card number and the expiry date.
10. Switch the toggle “I have read and accepted the terms and conditions of my bank.” and click on "Add card".
11. Click on “Continue” on the next screen.
12. Give access to the camera and allow notifications.


You are now all set!

**Important Note**:if you intend to onboard again with a new email or phone number, you’ll need to reset the app first. You can do this directly within the app (via your profile).

### Test Cards

| Issuer | Card Number | Expiry Date | Expected Result |
|  --- | --- | --- | --- |
| KBC | 5127 8829 9999 9715 | Nov-29 | Always Authorized |
| KBC | 5127 8829 9999 9723 | Nov-29 | Insufficient funds |
| KBC | 5127 8829 9999 9731 | Nov-29 | Card Refused by Issuer |