# Top Up

## Introduction

This solution allows you to create a closed loop payment system to top up payment cards or wristbands. Ideal for festivals, employee cards, student cards…etc.

With Top-Up, 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.

Top-Up QR codes can be scanned and paid multiple times and remain valid until they are revoked. The QR Code amount can be

- Defined by the consumer: you generate an open value QR code, the payment amount is provided by the consumer upon scanning it.
- Modifiable by the consumer: you generate a QR code with a predefined amount, but the consumer can modify it upon scanning it.
- Fixed: you generate a QR code with a fixed amount, it cannot be changed by the consumer.


**Important Note**:

* The behaviour of the QR Code (Defined, Modifiable, Fixed) needs to be set up by our Support Team upon product creation.
* A Callback URL will similarly have to be provided upon product creation. Our Top Up solution does cannot function without a predefined callback URL.


## Process Flow

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

### Prerequisites

* **Merchant CallbackUrl**  – This URL will be called by Bancontact Payconiq’s backend servers in order to send the status of the payment to the merchant.
* **API Key** (*Optional*) – 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.
* **QR Code URL Scheme** – The Bancontact Payconiq template QR Code URL Scheme.
* **PPID or Product Profile ID** – unique identifier of the product handling the payment.


### Involved Parties

The following parties participate in a Top Up payment with Bancontact Payconiq:

* **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 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 **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 Payconiq backend for authorization.
* A payment response is sent back by the **Bancontact Payconiq backend** to the **Payer App**, indicating whether the payment was successful or failed.
* 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** 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:

![TOP UP](/assets/topup2x.300ea5fb7a5464ec134929793fd8db08e51b6aec8caba8f97502ca25ac4c9d5e.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 Payconiq 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. |
| `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. |


#### 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. • Product 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=Receipt PaymentA=1000R=sd89sd91?sd9Payconiq encoded URL payload parameters:D=Receipt%20PaymentA=1000R=sd89sd91%3Fsd9 |
| **4.** Build the Payconiq URL payload using the following details.  •	Template URL scheme. •	Product 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/{productProfileId?D={Enc_description}&A={Enc_amount}&R={Enc_reference}` Sample URL payload:`https://payconiq.com/t/1/5c18cbd1296e9a26d3278518?D=Receipt%20Payment&A=1000&R=sd89sd91%3Fsd9` |
| **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=sd89sd91%3Fsd9 `Payconiq URL Payload after Encoding:`https%3A%2F%2Fpayconiq.com%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%2Fpayconiq.com%2Ft%2F1%2F5c18cbd1296e9a26d3278518%3FD%3DReceipt%2520Payment%26A%3D1000%26R%3Dsd89sd91%253Fsd9 ` |


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.

### 2. The Bancontact Payconiq Callback

Bancontact Payconiq's backend will call the specified callback URL to  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 **"4. 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`