Top Up

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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:

Implementation Guide

For the full endpoint documentation, please refer to the Merchant Payment API.

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:

QR code creation process

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.

📦 Request Body

📥 Response

(No defined response schema)

🔍 Sample Request – callback

curl -i -X POST \
  https://merchant.api.preprod.bancontact.net/callback \
  -H 'Content-Type: application/json' \
  -H 'Signature: YOUR_API_KEY_HERE' \
  -H 'User-Agent: Payconiq' \
  -d '{
    "paymentId": "5f91483d-78a7-4914-bc6f=",
    "currency": "EUR",
    "amount": 0,
    "description": "string",
    "reference": "19848995",
    "createdAt": "2019-08-24T14:15:22Z",
    "expireAt": "2019-08-24T14:15:22Z",
    "succeededAt": "2019-08-24T14:15:22Z",
    "status": "PENDING",
    "debtor": {
      "iban": "*************12636",
      "name": "John"
    }
  }'

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

🔍 Sample Request – merchant-get-payment

curl -i -X GET \
  'https://merchant.api.preprod.bancontact.net/v3/payments/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

🔍 Sample Request – search

curl -i -X POST \
  'https://merchant.api.preprod.bancontact.net/v3/payments/search?page=0&size=10' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2019-08-24T14:15:22Z",
    "to": "2019-08-24T14:15:22Z",
    "paymentStatuses": [
      "PENDING"
    ],
    "reference": "19848995"
  }'