Czech QR Payment (QR Platba)

From Barion Documentation
Jump to navigation Jump to search

Overview

Czech QR Payment (QR Platba) is available on the Barion Smart Gateway for all merchants accepting CZK payments. It is a standardized bank transfer method that encodes payment data into a QR code following the Short Payment Descriptor (SPD) standard. All Czech mobile banking apps support QR Platba, allowing customers to complete a payment simply by scanning the code and approving the transfer in their banking app.

Because all Czech banks support instant payments, the majority of QR Platba payments are confirmed within seconds, making this method a practical alternative to card payments for Czech customers.

Prerequisites

Czech QR payment is shown on the gateway only when all of the following conditions are met:

  • Payment currency is CZK, with a minimum amount of 1 CZK,
  • PayerHint is not null or empty in the Payment/Start request,
  • The payment is an immediate (non-reservation) payment,
  • The payment is a non-token payment,
  • BankTransfer is included in FundingSources in the Payment/Start request (or FundingSources is sent as All),
  • The customer is paying as a guest (not as a logged-in Barion user).

Limitations

WARNING
Most Czech banking apps allow the payer to switch from instant to standard bank transfer before confirming. Standard transfers may arrive hours later or on the next business day.

If the payment type is standard instead of instant, the following applies:

  • Barion will continue monitoring incoming payments. Once the transfer arrives, the gateway interface updates automatically and we send an IPN call.
  • Until the payment is confirmed, the gateway remains unchanged — the payer receives no immediate feedback that their payment was sent.
  • The payer can navigate back to the merchant’s site at any point. In that case, the payment enters Waiting status.
  • If the customer closes the browser window without navigating back to the merchant’s site, the payment remains in Prepared status — not Waiting.
  • Waiting and Prepared payments are set to Expired after 7 days, if the transfer is not received

Refunds

The standard refund flow is not available for Czech QR payments. The refund button is not shown in the Barion Account interface, and the Barion API returns an error if a refund is attempted programmatically.

Merchants can still initiate a refund manually: the payer’s bank account number is visible in the transaction history, so the merchant can initiate a bank transfer directly from their Barion Wallet for the amount they wish to return.

Payment Flow

When all prerequisites are met, the QR code accordion appears at the bottom of the Smart Gateway. When the customer opens the accordion, the QR code is generated and displayed.

Desktop Flow

  1. The payer opens the Czech QR accordion on the Smart Gateway.
  2. The QR code is generated and displayed. Alternatively, the customer can enter the payment data manually using the details shown on screen.
  3. The payer opens their mobile banking app and scans the QR code.
  4. After a few seconds, an “Already paid? Check payment” button appears for manual status refresh.
  5. Barion monitors the payment status in the background. Instant payments typically arrive within seconds.
  6. Once the incoming transfer is detected, the gateway shows a success screen and redirects the customer to the merchant’s site.
NOTE
If the payer navigates back to the merchant’s site before the payment is detected, the payment changes to Waiting status. The merchant should handle Waiting status in their order flow accordingly.

Mobile Flow

  1. The payer opens the Czech QR accordion.
  2. The QR code is displayed along with an “Open in banking app” button.
  3. The button uses the Web Share API to share the QR code image to installed banking apps. The customer selects their banking app manually — this is not a deeplink, but most of the Czech banking apps that support QR Platba accept the shared image.
  4. Barion monitors the payment status in the background. Instant payments typically arrive within seconds.
  5. Once the incoming transfer is detected, the gateway shows a success screen and redirects the customer to the merchant’s site.

PaymentState implications

For Czech QR payments, the PaymentState response includes additional fields in FundingInformation once the payment reaches Succeeded status:

  • AccountName — The payer’s name as provided by their bank.
  • AccountNumber — The payer’s IBAN.

Affected endpoints:

Potential status changes