← Blog 11.4.2026 ONDRÚŠ SOFTWARE developer

Pay by Square QR kód v PHP cez REST API

Návod ako generovať Pay by Square QR kódy v PHP pomocou REST API. Bez knižníc, bez závislostí — jeden HTTP request a máte PNG hotový.

Úvod

PHP vývojári, ktorí potrebujú generovať Pay by Square QR kódy, si tradične museli inštalovať knižnicu, riešiť kompresiu platobných údajov, Reed-Solomon kódovanie a Base32 výstup. Taký kód sa zvyčajne ťahá cez niekoľko projektov, rastie s každou opravou štandardu a pridáva údržbu navyše. Easy Square REST API to celé odstraňuje — jeden POST request vám vráti PNG obrázok pripravený na vloženie do faktúry.

Tento článok ukazuje dva spôsoby integrácie v PHP — natívny cURL bez závislostí a variant cez GuzzleHttp pre Composer projekty. Oba sú otestované proti reálnemu API a na konci každého príkladu nájdete aj Dockerfile na spustenie bez lokálnej PHP inštalácie.

Čo budete potrebovať

PHP 7.4+ s rozšírením curl (väčšinou predvolene)
API kľúč z easy-square.sk/registracia/ — kredit plán od 0,003 € bez DPH za QR kód
(voliteľne) Composer pre GuzzleHttp variant
(voliteľne) Docker pre spustenie príkladov bez lokálnej PHP inštalácie

Základná integrácia — cURL (natívne PHP)

Najjednoduchšia cesta — žiadne závislosti, len curl_* funkcie, ktoré sú v každej PHP inštalácii. Uložte nasledujúci súbor ako example.php:

<?php

$payload = [
    'beneficiaryName' => 'Firma s.r.o.',
    'iban' => 'SK3112000000198742637541',
    'amount' => 42.50,
    'variableSymbol' => '2026001',
];

$apiUrl = 'https://api.easy-square.sk/api/v1/pay-by-square/qr-code';
$apiEmail = getenv('ES_API_EMAIL');
$apiKey = getenv('ES_API_KEY');

$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "X-Api-Email: {$apiEmail}",
        "X-Api-Key: {$apiKey}",
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    fwrite(STDERR, "HTTP {$httpCode}: {$response}\n");
    exit(1);
}

file_put_contents('qr.png', $response);
echo "QR kód uložený: qr.png\n";

Spustenie:

ES_API_EMAIL=vas@email.sk \
ES_API_KEY=esq_vas_kluc \
php example.php

Spustenie cez Docker — bez inštalácie PHP

Ak nemáte PHP lokálne, pridajte vedľa example.php tento Dockerfile:

FROM php:8.2-cli
WORKDIR /app
COPY example.php .
CMD ["php", "example.php"]

Build a run:

docker build -t es-php .
docker run --rm \
  -e ES_API_EMAIL=vas@email.sk \
  -e ES_API_KEY=esq_vas_kluc \
  -v $(pwd):/app/out \
  es-php

Upravte example.php tak, aby ukladal PNG do /app/out/qr.png — súbor sa potom objaví v priečinku z ktorého ste spustili docker run.

Integrácia cez GuzzleHttp

Ak už máte Composer projekt s Guzzle, integrácia je ešte kratšia. Vytvorte example-guzzle.php:

<?php

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.easy-square.sk/api/v1/pay-by-square/qr-code', [
    'headers' => [
        'X-Api-Email' => getenv('ES_API_EMAIL'),
        'X-Api-Key' => getenv('ES_API_KEY'),
    ],
    'json' => [
        'beneficiaryName' => 'Firma s.r.o.',
        'iban' => 'SK3112000000198742637541',
        'amount' => 42.50,
        'variableSymbol' => '2026001',
    ],
]);

file_put_contents('qr.png', $response->getBody()->getContents());
echo "QR kód uložený: qr.png\n";

Docker variant s Composerom

Vytvorte Dockerfile:

FROM composer:2 AS deps
WORKDIR /app
RUN composer require guzzlehttp/guzzle --no-interaction --quiet

FROM php:8.2-cli
WORKDIR /app
COPY --from=deps /app/vendor ./vendor
COPY example-guzzle.php .
CMD ["php", "example-guzzle.php"]

Build a run rovnako ako pri cURL variante.

Vloženie QR kódu do HTML faktúry

Pre webové faktúry máte dve možnosti — uložiť PNG a odkázať cez <img src>, alebo vložiť ako inline base64:

// Varianta 1 — uložiť ako súbor
file_put_contents("faktury/qr-{$orderId}.png", $response);
echo '<img src="/faktury/qr-' . $orderId . '.png" alt="Platobný QR kód" width="200">';

// Varianta 2 — inline base64
$base64 = base64_encode($response);
echo '<img src="data:image/png;base64,' . $base64 . '" alt="Platobný QR kód" width="200">';

Base64 variant sa hodí pre PDF export alebo emailové faktúry, kde nechcete závisieť od externých súborov.

Voliteľné parametre — farby, veľkosť, logo

Okrem základných platobných údajov API podporuje aj vizuálne prispôsobenie QR kódu. Všetky parametre sú voliteľné:

$payload = [
    // povinné
    'beneficiaryName' => 'Firma s.r.o.',
    'iban' => 'SK3112000000198742637541',
    'amount' => 42.50,
    'variableSymbol' => '2026001',
    // voliteľné
    'currency' => 'EUR',
    'constantSymbol' => '0308',
    'specificSymbol' => '12345',
    'paymentNote' => 'Faktúra 2026001',
    'dueDate' => '2026-05-15',
    'size' => 512,
    'colorScheme' => 'MEDIUM',
    'withFrame' => true,
];

Parameter colorScheme akceptuje hodnoty LIGHT, MEDIUM alebo DARK. Parameter withFrame pridá ku QR kódu rámček s textom "PAY by square". Podrobný zoznam všetkých parametrov nájdete v dokumentácii API.

Tip pre WooCommerce / vlastný e-shop

V e-shope zvyčajne chcete generovať QR kód v okamihu dokončenia objednávky. Vo WooCommerce na to existuje hook woocommerce_payment_complete:

add_action('woocommerce_payment_complete', function($order_id) {
    $order = wc_get_order($order_id);
    $payload = [
        'beneficiaryName' => get_option('blogname'),
        'iban' => get_option('easy_square_iban'),
        'amount' => $order->get_total(),
        'variableSymbol' => strval($order_id),
    ];
    // ... volanie API ako vyššie, uložiť ako qr-{$order_id}.png
});

Kompletný WooCommerce návod pripravujeme v samostatnom článku.

Časté chyby a riešenia

HTTP 401 — Neautorizovaný

Skontrolujte, či posielate oba headery X-Api-Email aj X-Api-Key, a či email zodpovedá registračnému emailu. Kľúč začína prefixom esq_.

HTTP 429 — Rate limit

Free generátor na hlavnej stránke povoľuje 100 QR kódov denne (bez registrácie, bez API kľúča). API s vlastným kľúčom vyžaduje kredit plán — 0,003 € bez DPH za QR kód bez denného limitu. Registrácia

Prázdna odpoveď alebo PNG sa neukladá

Skontrolujte CURLOPT_RETURNTRANSFER => true. Bez neho curl_exec vypíše odpoveď do stdout namiesto návratovej hodnoty.

Nefunkčný QR kód pri skenovaní

Najčastejšia príčina — neplatný IBAN alebo nesprávny formát sumy. Suma musí byť float alebo číslo s desatinnou bodkou, nie reťazec s čiarkou. Odporúčame validovať IBAN pred volaním API — Easy Square síce IBAN kontroluje, ale ušetríte si zbytočné volania do API počítadla.

Časové limity pri hromadnom generovaní

Ak generujete desiatky QR kódov naraz (napr. po importe faktúr), držte paralelné requesty pod 10 naraz a medzi dávkami pridajte krátku pauzu. API je rýchle, ale pomôžete tým stabilite aj vlastným logom.

Záver

REST API odstraňuje potrebu inštalácie a údržby Pay by Square knižnice. Integrácia v PHP trvá pár minút a celá logika zmestí do 20 riadkov kódu — cURL variant nepotrebuje ani Composer.

Ďalšie detaily o parametroch (farby, logo, veľkosť, formát) nájdete v REST API dokumentácii. Pre registráciu a získanie API kľúča navštívte easy-square.sk/registracia/.

Prvý Easy Square článok nájdete na Easy Square je live.