PAY by square QR Code
PAY by square is a standardized QR code payment format developed by the Slovak Banking Association to simplify and unify the initiation of bank transfers via QR codes. The format encodes all required payment details into a compact, machine-readable structure that can be scanned by supported mobile banking applications to prefill a payment order accurately and securely.
PAY by square is widely used in Slovakia and the Czech Republic for invoicing, retail payments, donations, and e-commerce scenarios. It supports structured payment data such as beneficiary account (IBAN/BIC), amount, currency, payment references, messages, and optional metadata, reducing manual entry errors and accelerating payment workflows.
An example PAY by square QR Code with which 10 EUR will be donated to the Czech Red Cross:
Endpoints
The API can be called via POST method. The endpoint returns an PNG image.
POST/v1/pay-by-square-qr-code
curl -X POST https://api.apistax.io/v1/pay-by-square-qr-code \
-o 'qr-code.png' \
-H 'Authorization: Bearer API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"payments": [
{
"type": "PAYMENT_ORDER",
"accounts": [
{
"iban": "CZ14 2700 0000 0000 0033 3999"
}
],
"recipient": {
"name": "Czech Red Cross Humanity Fund"
}
}
]
}'
Parameters
The following parameters can be used as JSON fields in the POST request.
size: Integer = 300
The size of the QR code in pixels. The value must be between 100 and 2000 pixels.
invoice: String
The corresponding invoice number
payments: Array<Object>
The payments. At least one payment must be specified.
type: String
The payment type. Possible values are STANDING_ORDER, PAYMENT_ORDER and DIRECT_DEBIT.
accounts: Array<Object>
The recipient's bank accounts. At least one account must be specified.
iban: String
The international bank account number of the recipient. Any spaces between the blocks are removed.
bic: String
The bank identifier code of the recipient's bank. Often known as SWIFT code.
amount: Float
The amount to be paid with a maximum of two decimal places. The value is optional, but recommended.
currency: String
The currency according to ISO 4217 (USD, EUR etc.).
dueDate: Date
The due date in the format YYYY-MM-DD, for example 2020-01-31
recipient: Object
The recipient's details
name: String
The name of the recipient
street: String
The street of the recipient
city: String
The city of the recipient
standingOrder: Object
The standing order details are required if STANDING_ORDER was selected as the type.
day: Integer
The day on which the payment should occur.
month: Integer
The month on which the payment should occur. Must be specified if period is set to one of the following values:
WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY
period: String
The periodicity of the payment. Possible values are: DAILY, WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY,
SEMIANNUALLY, ANNUALLY
lastDate: Date
Defines the day of the last payment of the standing order. After this date, standing order is cancelled. The format is YYYY-MM-DD, for example 2020-01-31
directDebit: Object
The direct debit details are required if DIRECT_DEBIT was selected as the type.
scheme: String
The direct debit scheme. SEPA value, if direct debit is using SEPA direct debit scheme or OTHER when an ordinary
direct debit is defined
type: String
Can be ONE_OFF for one time debit or RECURRENT for repeated debit until cancelled
variableSymbol: String
The direct debit reference. Can be combined with specificSymbol variable.
specificSymbol: String
The direct debit reference. Can be combined with variableSymbol variable.
reference: String
The direct debit reference
mandate: String
The direct debit reference. Must be combined with creditor and contract.
creditor: String
The direct debit reference. Must be combined with mandate and contract.
contract: String
The direct debit reference. Must be combined with mandate and creditor.
maxAmount: Integer
The maximum amount that can be pre-filled for the user.
validTill: Date
The date after which direct debit is cancelled in the format YYYY-MM-DD, for example 2020-01-31.
variableSymbol: String
The reference. Can be combined with variable constantSymbol and specificSymbol.
constantSymbol: String
The reference. Can be combined with variable specificSymbol and variableSymbol.
specificSymbol: String
The reference. Can be combined with variable constantSymbol and variableSymbol.
reference: String
The SEPA payment reference
note: String
The payment note. The recommended structure is as follows: Issuer - Subject - Term, for example Law Firm - legal services - 2020-01
If most parameters are utilized, an example curl request could look like this:
curl -X POST https://api.apistax.io/v1/pay-by-square-qr-code \
-o 'qr-code.png' \
-H 'Authorization: Bearer API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"size": 300,
"invoice": "2020-009",
"payments": [
{
"type": "PAYMENT_ORDER",
"accounts": [
{
"iban": "CZ14 2700 0000 0000 0033 3999",
"bic": "BACXCZPP"
}
],
"amount": 10,
"currency": "EUR",
"recipient": {
"name": "Czech Red Cross Humanity Fund",
"street": "Thunovská 18",
"city": "Praha"
},
"reference": "Donation",
"note": "Donates 10 EUR to the humanity fund."
}
]
}'
Possible errors
| Identifier | Description |
|---|---|
message.ibanMustBeValid |
Parameter iban must be a valid IBAN according to ISO 13616-1:2020. |
message.bicMustBeValid |
Parameter bic must be a valid BIC according to ISO 9362. |
message.ibanMustNotBeBlank |
Parameter iban mut not be blank. |
message.sizeMustMotBeBiggerThan2000Pixels |
Parameter size must be between 100 and 2000 pixels. |
message.sizeMustNotBeSmallerThan100Pixels |
Parameter size must be between 100 and 2000 pixels. |
message.currencyMustBeValid |
Parameter currency must be valid and provided as an ISO 4217 currency code. |
message.accountsMustNotBeEmpty |
Parameter accounts must not be empty. |
message.paymentsMustNotBeEmpty |
Parameter payments must not be empty. |
message.typeMustNotBeNull |
Parameter type must not be null. |
message.nameMustNotBeBlank |
Parameter name of a recipient must not be blank. |
message.recipientMustNotBeNull |
Parameter recipientmust not be null. |
message.dayMustBeBetween1And31 |
Parameter day must be between 1 and 31. |
message.monthMustBeBetween1And12 |
Parameter month must be between 1 and 12. |
message.periodMustNotBeNull |
Parameter period must not be null. |
It should be noted that there are a number of common error messages, which can be found in the "Possible errors" section of the general documentation.