# Invoice

## Introduction

Our invoice solution allows your to print a single use payment QR code on your invoices. Your consumers simply scan the QR code with their preferred payment application and confirm the transaction.

For digital invoices, a deeplink alternative is available to allow your consumers to settle their invoices directly from their mobile devices.

**Important Note** Invoices can be used with or without structured communication (GMO). The parameter must be activated upon product creation by our support team.

## Process Flow

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

### Prerequisites

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


### Involved Parties

The following parties participate in a display-based in-store payment with Bancontact Payconiq:

* **Payer Application**: The consumer's preferred payment app used to complete the transaction.
* **Merchant Frontend**: The physical or digital invoice where the QR code is displayed
* **Merchant Backend**: The merchant’s server-side system that integrates with Bancontact Payconiq.
* **Bancontact Payconiq 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 Payconiq service URL. The QR code will contain parameters such as the amount to be paid, a discription and a payment reference.
* The QR Code is printed on the **Merchant Fronted**
* The consumer confirms the payment n the **Payer app** using PIN, fingerprint, or face ID. The Payer app then submits the payment request to the Bancontact Payconiq backend for authorization.
* The consumer confirms the payment n the **Payer app** using PIN, fingerprint, or face ID. The Payer app then submits the payment request to the **Bancontact Payconiq backend** for authorization.
* The **Bancontact Payconiq 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** displays the payment  status (digital invoices)


> **Important Note:** The order in which the merchant and consumer receive payment status notifications is **not guaranteed**. Network and connectivity differences may cause one party to receive the update before the other.


## Payment Flow Diagram

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

> Embed diagram INVOICE


## Implementation Guide

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

> 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 Payconiq service URL as ilustrated 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. |
| `cl` [String :: Enum]  Allowed Values: magenta, black | The colour of the QR code.  Default is magenta. |
| `c`  [String, required] | The Payconiq 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 Payconiq QR Code. | • Format of the Payconiq QR code. • Size of the Payconiq QR code. • Template URL scheme. • Payment profile id of the merchant. • Amount of the Payconiq QR code. • Description of the Payconiq QR code. • Reference of the Payconiq QR code. |
| **2.** Build the Payconiq 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 Payconiq URL payload parameter values using UTF-8 as the destination character set. This means encoding the following: •   Description •   Amount •    Reference. | Payconiq unencoded URL payload parametersD=Invoice PaymentA=1000R= unique reference OR structured communicationExample: for structured communication  +++123/4567/89101+++ ,value of R should be **123456789101** |
| **4.** Build the Payconiq URL payload using the following details.  •  Template URL scheme •   Payment profile id of the merchant. •   Amount of the Payconiq QR code. •   Description of the Payconiq QR code. •  Reference of the Payconiq QR code. | Sample format:`https://payconiq.com/t/1/{PaymentProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference} `Sample URL payload:`https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=123456789101` |
| **5.** UTF-8 encode the Payconiq URL Payload from step 4. | Payconiq URL Payload before Encoding:`https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=1000&R=123456789101`Payconiq URL Payload after Encoding:`https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3D123456789101` |
| **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=L&c=https%3A%2F%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DInvoice%2520Payment%26A%3D1000%26R%3D123456789101` |


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

### Invoice Deeplink

For digital invoices, you can use the Payload URL as a deeplink to allow your consumers to pay withdirectly from their mobile device.

To do so, simply send the Bancontact Payconiq Payload URL generated in the Step 4 of the QR Code creation process and send it to your consumers.

**Invoice DeepLink Example**

* **Description:** Invoice Payment
* **Amount:** 2.50€
* **Reference:** 4198798465


https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=Invoice%20Payment&A=250&R=4198798465

### 2. The Bancontact Payconiq Callback

You can specify a callback URL where the **Bancontact Payconiq 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 Payconiq backend** was not altered or corrupted during the tranmission. 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 doesn’t 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 doesn’t 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`