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

# On a Receipt

## Introduction

Our receipt solution allows you to generate a one-time usage QR code and print it on your receipts through your cash-register (ECR) system. Your consumers scan the QR code with their preferred payment application and confirm the transaction.

## Process Flow

The following section outlines the key steps involved in a On a Receipt payment with Bancontact Pro. The process involves several key parties, each playing a specific role in completing the transaction.

### Prerequisites

* **API Key** (Optional) – This is used to secure the request between the **Merchant’s backend** and **Bancontact Pro's backend**. Do not share your API keys in public areas such as online sites or client-side code.
* **Merchant CallbackUrl** – This URL will be called by Bancontact Pro's backend servers in order to send the status of the payment to the merchant.
* **PPID or Product Profile ID** – unique identifier of the product handling the payment.


### Involved Parties

The following parties participate in a On a Receipt payment with Bancontact Pro:

* **Payer Application**: The consumer's preferred payment app used to complete the transaction.
* **Merchant Frontend**: The receipt on which the QR code is printed.
* **Merchant Backend**: The merchant’s server-side system that integrates with Bancontact Pro.
* **Bancontact Pro Backend**: The backend system responsible for handling payment processing and integration services.


### Step-by-Step Payment Flow

* The **Merchant Backend** creates a one-time usage QR code using the Bancontact Pro service URL. The QR code will contain parameters such as the amount to be paid, a dscription and a payment reference.
* The QR Code is printed on the **Merchant Fronted**.
* The **Payer App**  reads the details of the QR code and presents them for payment confirmation. The details would contain the amount to pay, the merchant name and a description.
* The consumer confirms the payment in the **Payer app** using PIN, fingerprint, or face ID. The **Payer App** then submits the payment request to the **Bancontact Pro Backend** for authorization.
* A payment response is sent back by the **Bancontact Pro backend** to the **Payer App**, indicating whether the payment was successful or failed.
* The **Bancontact Pro backend** sends a payment notification with the payment status to the **merchant backend** via the configured callback URL.
* The **merchant backend** acknowledges the callback notification.
* The **merchant frontend** is notified of the status of the payment.


**NB:** The order of consumer and merchant notification is not sequential. One may arrive before the other depending on internet and network connections.

## Payment Flow Diagram

In the following diagrams you will find a visual overview of the process flows presented above:

![Visualized diagram of the QR on a receipt payment flow](/assets/onareceipt2x.49894da8039e2d957af2d15f0c3dcffa9b771979b3fe35bdb5ef623dc17368af.85e0cfdd.jpg)

## Implementation Guide

> For the full endpoint documentation, please refer to the [Merchant Payment API](/apis/merchant-payment.openapi).


### 1. Creating QR Code

In order to create a QR code you need to use the Bancontact Pro service URL as illustrated below. Once created, you will be able to print the Static QR on the medium of your choice.

#### QR Code Parameters

The QR code contains the following parameters:

| Attribute | Description |
|  --- | --- |
| `f` [String :: Enum]  Allowed Values: SVG, PNG | Image format. If not provided, the default format is PNG. |
| `s` [String :: Enum]  Allowed Values: S, M, L, XL | Image size of the QR code to generate. Small (S) = 180x180 Medium (M) = 250x250Large (L) = 400x400 Extra Large (XL) = 800x800  The sizes only applies to PNG format.  *If not provided, the default size is Small. |
| `c`  [String, required] | The Bancontact Pro UTF-8 URL encoded content. This is comprised of the template URL scheme. |
| `c.D` [String, optional] Maximum Length: 35 chars | UTF-8 URL encoded description of the payment |
| `c.A` [String, optional]Minimum: 1Maximum: 999999 | UTF-8 URL encoded amount of the QR code in Euro cents. |
| `c.R` [String, optional]Maximum Length: 35 chars | UTF-8 URL encoded reference of the QR code. |


**IMPORTANT NOTE:** The combination of amount, reference, and description should always be unique. If not, the QR code could be considered as already paid.

#### QR code creation process

| Activity | Comment |
|  --- | --- |
| **1.** Obtain the pre-requisite information needed to generate the Bancontact Pro QR Code. | • Format of the Bancontact Pro QR code. • Size of the Bancontact Pro QR code. • Template URL scheme. • Product profile id of the merchant. • Amount of the Bancontact Pro QR code. • Description of the Bancontact Pro QR code. • Reference of the Bancontact Pro QR code. |
| **2.** Build the Bancontact Pro service URL using the optional parameters which include:  •	Image format (PNG or SVG)  •	Image size (S, M, L, XL). This only applies to PNG. | Sample format: `https://qrcodegenerator.api.bancontact.net/qrcode?f={imageFormat}&s={ImageSize}&c= ` Example Output URL (PNG):`https://qrcodegenerator.api.bancontact.net/qrcode?f=PNG&s=L&c=` Sample URL (SVG)`https://qrcodegenerator.api.bancontact.net/qrcode?f=SVG&c= ` |
| **3.** UTF-8 encode the Bancontact Pro URL payload parameter values using UTF-8 as the destination character set. This means encoding the following: •	Description •	Amount •	Reference. | Bancontact Pro unencoded URL payload parametersD=Receipt PaymentA=1000R=sd89sd91?sd9Bancontact Pro encoded URL payload parameters:D=Receipt%20PaymentA=1000R=sd89sd91%3Fsd9 |
| **4.** Build the Bancontact Pro URL payload using the following details.  •	Template URL scheme. •	Product profile id of the merchant. •	Amount of the Bancontact Pro QR code. •	Description of the Bancontact Pro QR code. •	Reference of the Bancontact Pro QR code. | Sample format:`https://pay.bancontact.net/t/1/{productProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}` Sample URL payload:`https://pay.bancontact.net/t/1/5c18cbd1296e9a26d3278518?D=Receipt%20Payment&A=1000&R=sd89sd91%3Fsd9` |
| **5.** UTF-8 encode the Bancontact Pro URL Payload from step 4. | Bancontact Pro URL Payload before Encoding:`https://pay.bancontact.net/t/1/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=sd89sd91%3Fsd9 `Bancontact Pro URL Payload after Encoding:`https%3A%2F%2Fpay.bancontact.net%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DReceipt%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9` |
| **6.** Build full URL by combining results from step 2 and step 5. | Sample full URL:`https://qrcodegenerator.api.bancontact.net/qrcode?f=PNG&s=XL&c=https%3A%2F%2Fpay.bancontact.net%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DReceipt%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9 ` |


You can now execute the URL in a web view to obtain your QR Code and print it on the medium of your choice.

### 2. The Bancontact Pro Callback

You can specify a callback URL where the **Bancontact Pro backend** will send notifications about the status of a payment. This will allow you to take appropriate action and process the payment data.

The **merchant backend** must verify that the notification message originated from **Bancontact Pro backend** was not altered or corrupted during the transmission. To do so, please ensure signature validation.

> For the full Callback documentation, please refer to the [Callback Guide](/guides/general/callback052025).


#### 📦 Request Body

#### 📥 Response

*(No defined response schema)*

#### 🔍 Sample Request – `callback`

#### Callback Failure

In the event you do not receive a callback or the callback validation fails, please refer to **"Get Payment Details"**. This alternative will also allow you to confirm the status of a transaction in order to complete the payment.

### 3. Get Payment Details

By calling this endpoint you can obtain the details of an existing payment transaction by passing the unique payment ID.

**Note:** it is highly recommended to implement this call as a fallback option if callback fails.

#### 🧩 Path Parameters

- `id` *(string, required)*


#### 📥 Response

#### 🔧 Error Codes for `merchant-get-payment`

| HTTP Status | Code | Meaning |
|  --- | --- | --- |
| 401 | `UNAUTHORIZED` | caller does not have an api-key access token |
| 403 | `ACCESS_DENIED` | api-key access token is invalid, creditor it's not a participant of the requested payment |
| 404 | `PAYMENT_NOT_FOUND` | no payment could be found |
| 500 | `TECHNICAL_ERROR` | Technical error in Payment service |


#### 🔍 Sample Request – `merchant-get-payment`

### 4. Get Payment List

You can also retrieve a list of payments by specifying how many records to return, as well as a filter on the results for the total number of records returned per page.

#### 📦 Request Body

#### 📥 Response

#### 🔧 Error Codes for `search`

| HTTP Status | Code | Meaning |
|  --- | --- | --- |
| 401 | `UNAUTHORIZED` | caller does not have an api-key access token |
| 403 | `ACCESS_DENIED` | api-key access token is invalid, creditor it's not a participant of the requested payment |
| 500 | `TECHNICAL_ERROR` | Technical error in Payment service |


#### 🔍 Sample Request – `search`