API Documentation

Generate PAY by square, SPAYD and EPC QR codes via REST API

No authentication requiredCORS enabled for all originsREST / JSON

Quick Start#

Generate a Slovak PAY by square QR code with a single POST request:

curl

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{"iban":"SK3112000000198742637541","amount":25.50,"variableSymbol":"2024001","recipientName":"Ján Novák"}'

Or generate a Czech SPAYD QR code:

curl

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{"iban":"CZ6508000000192000145399","amount":480.50,"currency":"CZK","paymentFormat":"spayd"}'

Base URL & Authentication#

https://qr-platby.com/api/v1/qr

- No authentication required
- CORS enabled for all origins
- HTTPS only

Endpoints#

POST/api/v1/qr- Generate QR code

GET/api/v1/qr- Machine-readable JSON docs

OPTIONS/api/v1/qr- CORS preflight

Request Parameters#

Send a JSON body with the following parameters to the POST endpoint:

Name	Type	Required	Default	Validation	Description
iban	string	Required	-	Valid IBAN format	Recipient IBAN (e.g. SK3112000000198742637541)
amount	number	Optional	-	0.01 - 999,999,999.99	Payment amount
currency	string	Optional	EUR	EUR \| CZK	Payment currency
variableSymbol	string	Optional	-	Up to 10 digits	Variable symbol (digits only)
specificSymbol	string	Optional	-	Up to 10 digits	Specific symbol (digits only)
constantSymbol	string	Optional	-	Up to 4 digits	Constant symbol (digits only)
recipientName	string	Optional	-	Up to 70 characters	Payee name. Use the exact account holder name. Required for epc, expected for bysquare (a code without it returns a warning)
paymentNote	string	Optional	-	Up to 140 characters	Payment note / message
bic	string	Optional	-	8 or 11 characters	BIC/SWIFT code. Supported by all formats
paymentDueDate	string	Optional	-	YYYY-MM-DD	Payment due date. bysquare and spayd only
invoiceId	string	Optional	-	Up to 10 characters	Invoice number. bysquare only
spaydReference	string	Optional	-	Up to 16 digits	SPAYD recipient reference (RF). spayd only
purposeCode	string	Optional	-	Up to 4 characters	SEPA purpose code (AT-44), e.g. GDDS. epc only
instantPayment	boolean	Optional	-	true or false	Request an instant payment where the payer's bank supports it. spayd only
paymentFormat	string	Optional	bysquare	bysquare \| spayd \| epc	QR standard. bysquare for Slovak banks (PAY by square), spayd for Czech banks (QR Platba), epc for EU SEPA (requires recipientName, EUR only)
format	string	Optional	png	png \| svg	Output format. png returns base64 data URI, svg returns SVG markup
size	integer	Optional	300	100 - 1000	QR code size in pixels (applies to png and svg)
darkColor	string	Optional	#000000	#RRGGBB or #RRGGBBAA	Foreground (module) color as hex
lightColor	string	Optional	#ffffff	#RRGGBB or #RRGGBBAA	Background color as hex. Use #FFFFFF00 for a transparent background
margin	integer	Optional	2	0 - 10	Quiet zone width in QR modules. Lowering may hurt scanner reliability
errorCorrectionLevel	string	Optional	-	L \| M \| Q \| H	Override auto-derived recovery level (L=7%, M=15%, Q=25%, H=30%)

Response Format#

Success (200)#

json

{
  "success": true,
  "data": "data:image/png;base64,iVBORw0KGgo...",
  "format": "png",
  "iban": "SK3112000000198742637541",
  "amount": 25.5,
  "currency": "EUR"
}

The response may include a warnings array. For example, PAY by square without recipientName is still generated, with a note that banks verify the payee name.

Error#

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed. Check the issues array for details.",
    "issues": [
      { "path": "iban", "message": "Invalid IBAN" }
    ],
    "hint": "Required: iban (string). Optional: amount, currency, ...",
    "docs": "https://qr-platby.com/en/docs",
    "example": {
      "iban": "SK3112000000198742637541",
      "amount": 25.5
    }
  }
}

Error Handling#

400VALIDATION_ERROR

Invalid or missing request parameters. Check the issues array for field-specific errors.

400VALIDATION_ERROR(Invalid JSON)

Request body is not valid JSON. Ensure you send proper JSON with Content-Type: application/json.

400VALIDATION_ERROR(Invalid IBAN)

IBAN failed validation. Must start with a 2-letter country code followed by 2 check digits.

400VALIDATION_ERROR(SPAYD payload)

SPAYD payload too large. Reduce the length of paymentNote or recipientName.

429RATE_LIMIT

Too many requests. Respect the Retry-After header and implement exponential backoff.

500INTERNAL_ERROR

Unexpected server error. Try again later or contact support.

Rate Limiting#

- 20 requests per minute
- 100 requests per day
- GET and OPTIONS endpoints are not rate-limited

Response Headers#

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
Retry-After: 45  (only on 429)

Implement exponential backoff when you receive a 429 response. Cache QR codes on your side when possible.

Code Examples#

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "SK3112000000198742637541",
    "amount": 25.50,
    "currency": "EUR",
    "variableSymbol": "2024001",
    "recipientName": "Ján Novák"
  }'

Try It Out#

Send a real request to the API and see the response:

← Back to home page

API Documentation

Generate PAY by square, SPAYD and EPC QR codes via REST API

No authentication requiredCORS enabled for all originsREST / JSON

Quick Start#

Generate a Slovak PAY by square QR code with a single POST request:

curl

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{"iban":"SK3112000000198742637541","amount":25.50,"variableSymbol":"2024001","recipientName":"Ján Novák"}'

Or generate a Czech SPAYD QR code:

curl

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{"iban":"CZ6508000000192000145399","amount":480.50,"currency":"CZK","paymentFormat":"spayd"}'

Base URL & Authentication#

https://qr-platby.com/api/v1/qr

- No authentication required
- CORS enabled for all origins
- HTTPS only

Endpoints#

POST/api/v1/qr- Generate QR code

GET/api/v1/qr- Machine-readable JSON docs

OPTIONS/api/v1/qr- CORS preflight

Request Parameters#

Send a JSON body with the following parameters to the POST endpoint:

Name	Type	Required	Default	Validation	Description
iban	string	Required	-	Valid IBAN format	Recipient IBAN (e.g. SK3112000000198742637541)
amount	number	Optional	-	0.01 - 999,999,999.99	Payment amount
currency	string	Optional	EUR	EUR \| CZK	Payment currency
variableSymbol	string	Optional	-	Up to 10 digits	Variable symbol (digits only)
specificSymbol	string	Optional	-	Up to 10 digits	Specific symbol (digits only)
constantSymbol	string	Optional	-	Up to 4 digits	Constant symbol (digits only)
recipientName	string	Optional	-	Up to 70 characters	Payee name. Use the exact account holder name. Required for epc, expected for bysquare (a code without it returns a warning)
paymentNote	string	Optional	-	Up to 140 characters	Payment note / message
bic	string	Optional	-	8 or 11 characters	BIC/SWIFT code. Supported by all formats
paymentDueDate	string	Optional	-	YYYY-MM-DD	Payment due date. bysquare and spayd only
invoiceId	string	Optional	-	Up to 10 characters	Invoice number. bysquare only
spaydReference	string	Optional	-	Up to 16 digits	SPAYD recipient reference (RF). spayd only
purposeCode	string	Optional	-	Up to 4 characters	SEPA purpose code (AT-44), e.g. GDDS. epc only
instantPayment	boolean	Optional	-	true or false	Request an instant payment where the payer's bank supports it. spayd only
paymentFormat	string	Optional	bysquare	bysquare \| spayd \| epc	QR standard. bysquare for Slovak banks (PAY by square), spayd for Czech banks (QR Platba), epc for EU SEPA (requires recipientName, EUR only)
format	string	Optional	png	png \| svg	Output format. png returns base64 data URI, svg returns SVG markup
size	integer	Optional	300	100 - 1000	QR code size in pixels (applies to png and svg)
darkColor	string	Optional	#000000	#RRGGBB or #RRGGBBAA	Foreground (module) color as hex
lightColor	string	Optional	#ffffff	#RRGGBB or #RRGGBBAA	Background color as hex. Use #FFFFFF00 for a transparent background
margin	integer	Optional	2	0 - 10	Quiet zone width in QR modules. Lowering may hurt scanner reliability
errorCorrectionLevel	string	Optional	-	L \| M \| Q \| H	Override auto-derived recovery level (L=7%, M=15%, Q=25%, H=30%)

Response Format#

Success (200)#

json

{
  "success": true,
  "data": "data:image/png;base64,iVBORw0KGgo...",
  "format": "png",
  "iban": "SK3112000000198742637541",
  "amount": 25.5,
  "currency": "EUR"
}

The response may include a warnings array. For example, PAY by square without recipientName is still generated, with a note that banks verify the payee name.

Error#

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed. Check the issues array for details.",
    "issues": [
      { "path": "iban", "message": "Invalid IBAN" }
    ],
    "hint": "Required: iban (string). Optional: amount, currency, ...",
    "docs": "https://qr-platby.com/en/docs",
    "example": {
      "iban": "SK3112000000198742637541",
      "amount": 25.5
    }
  }
}

Error Handling#

400VALIDATION_ERROR

Invalid or missing request parameters. Check the issues array for field-specific errors.

400VALIDATION_ERROR(Invalid JSON)

Request body is not valid JSON. Ensure you send proper JSON with Content-Type: application/json.

400VALIDATION_ERROR(Invalid IBAN)

IBAN failed validation. Must start with a 2-letter country code followed by 2 check digits.

400VALIDATION_ERROR(SPAYD payload)

SPAYD payload too large. Reduce the length of paymentNote or recipientName.

429RATE_LIMIT

Too many requests. Respect the Retry-After header and implement exponential backoff.

500INTERNAL_ERROR

Unexpected server error. Try again later or contact support.

Rate Limiting#

- 20 requests per minute
- 100 requests per day
- GET and OPTIONS endpoints are not rate-limited

Response Headers#

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
Retry-After: 45  (only on 429)

Implement exponential backoff when you receive a 429 response. Cache QR codes on your side when possible.

Code Examples#

curl -X POST https://qr-platby.com/api/v1/qr \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "SK3112000000198742637541",
    "amount": 25.50,
    "currency": "EUR",
    "variableSymbol": "2024001",
    "recipientName": "Ján Novák"
  }'

Try It Out#

Send a real request to the API and see the response:

← Back to home page