Static QR Code

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

Static QR Code allows you to add a printed static QR code to your point of sale (PoS) and link it to your cash register system. 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.

Process Flow

The following section outlines the key steps involved in a Static QR Code 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.
• 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 printed static QR code
• 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

This section outlines a typical “Static QR Code” in-store payment flow using Bancontact Payconiq. The process begins when the transaction is initiated at the merchant’s location and ends when both the merchant and the consumer receive the final confirmation.

• The Merchant frontend displays a Static QR code, visible to the consumers.
• The Merchant backend issues a REST request to the Bancontact Payconiq backend to create the payment, providing parameters like amount, currency, description, and other relevant parameters.
• The Bancontact Payconiq backend responds with the created payment ID and other relevant detail to the Merchant backend
• The Payer app scans the QR code to initiate the payment process.
• The Payer app sends a request for payment details to the Bancontact Payconiq backend. The POS ID present in the Static QR is matched with a POS ID on Bancontact Payconiq backend.
• Bancontact Payconiq backend sends the payment details tot he Payer App, which contains the name of the merchant and the amount to pay.
• 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.
• 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 frontend displays the payment status.

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:

Implementation Guide

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

1. Create a Static QR Code

In order to create a Static 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.

Static QR Code Parameters

The QR code contains the following parameters:

Static 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. Create Payment

In order to initiate a payment, you will first have to create it through Bancontact Payconiq via a POST request. Each request will result in a unique payment identifier which will be valid for two minutes (120 seconds).

If the payment does not take place within these two minutes, a new payment must be created.

📦 Request Body

📥 Response

🔧 Error Codes for create

🔍 Sample Request – create payment

curl -i -X POST \
  https://merchant.api.preprod.bancontact.net/v3/payments/pos \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "19848995",
    "bulkId": "Bulk-1-200",
    "amount": 1,
    "currency": "EUR",
    "description": "string",
    "posId": "POS00001",
    "shopId": "3418e946-ef71-41ef-ad56-c41421c1e079",
    "shopName": "Bun café",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment",
    "voucherEligibility": [
      {
        "voucherSchemes": [
          "BEL_MEAL_VOUCHER"
        ],
        "amount": 1013
      }
    ]
  }'

3. 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.

📦 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 "Get Payment Details". This alternative will also allow you to confirm the status of a transaction in order to complete the payment.

4. 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'

5. 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"
  }'

Canceling a Payment

Endpoint delete-payment can be used to cancel a created payment that is still in status PENDING. The endpoint can also be used to cancel a payment in IDENTIFIED status, as long as the consumer has not initiated payment confirmation.

🧩 Path Parameters

• id (string, required) — Payconiq Payment Id

🔧 Error Codes for delete-payment

🔍 Sample Request – delete-payment

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