← Blog developer

Pay by Square QR kód do WooCommerce e-shopu

Pridajte Pay by Square QR kód do WooCommerce objednávky cez REST API. Kód, hook, email šablóna — kompletný návod.

Úvod

WooCommerce natívne nepodporuje Pay by Square. Ak predávate na Slovensku a chcete zákazníkom ponúknuť naskenovanie QR kódu po objednávke, musíte si to pridať sami. V tomto článku ukážeme kompletný plugin — 30 riadkov PHP — ktorý zobrazí platobný QR kód na ďakovnej stránke aj v emaili s objednávkou. Plus kompletný Docker setup, ktorý vám rozbehne WordPress + WooCommerce s pluginom za minútu, aby ste si to mohli vyskúšať bez dotyku vášho existujúceho e-shopu.

Celé riešenie používa Easy Square REST API — žiadne knižnice na generovanie QR kódov v PHP, žiadne závislosti. Jeden POST request vráti PNG pripravený na vloženie do HTML.

Ako to bude fungovať

Flow pri dokončení objednávky:

  1. Zákazník dokončí checkout → WooCommerce presmeruje na ďakovnú stránku
  2. WordPress spustí hook woocommerce_thankyou pre dané číslo objednávky
  3. Náš plugin vezme IBAN, sumu a číslo objednávky a zavolá Easy Square API
  4. API vráti PNG — plugin ho vloží ako inline base64 obrázok pod sumarizáciu objednávky
  5. Rovnaký QR kód sa vygeneruje aj pri odosielaní potvrdzujúceho emailu cez hook woocommerce_email_after_order_table

Zákazník naskenuje QR kód v bankovej aplikácii, údaje sa vyplnia automaticky, platba prebehne štandardným prevodom.

Čo budete potrebovať

  • WooCommerce 7+ (fungovalo aj na starších)
  • PHP 7.4+ s curl rozšírením
  • API kľúč z easy-square.sk/registracia/ — kredit plán od 0,003 € bez DPH za QR kód
  • (voliteľne) Docker — ak chcete plugin otestovať bez dotyku produkčného e-shopu

Plugin — easy-square-qr.php

Vytvorte priečinok easy-square-qr/ a v ňom súbor easy-square-qr.php:

<?php
/**
 * Plugin Name: Easy Square QR
 * Description: Pridá Pay by Square QR kód na ďakovnú stránku a do emailu objednávky.
 * Version: 1.0.0
 */

if (!defined('ABSPATH')) {
    exit;
}

function easy_square_generate_qr($order) {
    $apiUrl = getenv('ES_API_URL') ?: 'https://api.easy-square.sk/api/v1/pay-by-square/qr-code';
    $apiEmail = getenv('ES_API_EMAIL');
    $apiKey = getenv('ES_API_KEY');
    $iban = getenv('ES_BENEFICIARY_IBAN');

    if (!$apiEmail || !$apiKey || !$iban) {
        return null;
    }

    $payload = [
        'beneficiaryName' => get_option('blogname'),
        'iban' => $iban,
        'amount' => floatval($order->get_total()),
        'variableSymbol' => strval($order->get_id()),
    ];

    $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}",
        ],
        CURLOPT_TIMEOUT => 10,
    ]);

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

    return $code === 200 ? $response : null;
}

add_action('woocommerce_thankyou', function ($order_id) {
    $order = wc_get_order($order_id);
    if (!$order) return;
    $png = easy_square_generate_qr($order);
    if (!$png) return;

    echo '<div style="margin:2em 0;padding:1.5em;border:1px solid #e2e8f0;border-radius:8px;text-align:center;">';
    echo '<h2>Platba cez QR kód</h2>';
    echo '<p>Naskenujte kód v aplikácii vašej banky — platobné údaje sa vyplnia automaticky.</p>';
    echo '<img src="data:image/png;base64,' . esc_attr(base64_encode($png)) . '" width="256" height="300" alt="Platobný QR kód">';
    echo '</div>';
});

add_action('woocommerce_email_after_order_table', function ($order) {
    $png = easy_square_generate_qr($order);
    if (!$png) return;

    echo '<h2>Platobný QR kód</h2>';
    echo '<p>Naskenujte kód v aplikácii vašej banky.</p>';
    echo '<img src="data:image/png;base64,' . esc_attr(base64_encode($png)) . '" width="256" height="300" alt="QR kód">';
});

Kľúčové detaily:

  • Konfigurácia cez environment premenné — API kľúč, IBAN a URL prichádzajú z prostredia. Vďaka tomu môžete ten istý plugin nasadiť na viacero inštancií bez zmeny kódu. Ak preferujete WordPress options, nahraďte getenv() za get_option('easy_square_api_key') a pridajte admin stránku na ich správu.
  • Inline base64 — obrázok vložený priamo do HTML. Výhoda pre emailové šablóny, kde externé obrázky niekedy nefungujú. Nevýhoda: HTML stránka je o ~17 kB väčšia. Pre high-traffic e-shop zvážte uloženie PNG na disk a referenciu cez <img src="/wp-content/uploads/qr/...">.
  • 10-sekundový timeout — chráni vás pred visiacou checkout stránkou ak by API reagovalo pomaly.

Docker setup — WordPress + WooCommerce za minútu

Ak nechcete dotknúť sa produkčného e-shopu, rozbehnite celú stack v Dockeri. Vytvorte tieto súbory:

docker-compose.yml

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
    tmpfs:
      - /var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uwordpress", "-pwordpress"]
      interval: 2s
      timeout: 5s
      retries: 30

  wordpress:
    image: wordpress:6-php8.2
    ports:
      - "18080:80"
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
      ES_API_URL: ${ES_API_URL:-https://api.easy-square.sk/api/v1/pay-by-square/qr-code}
      ES_API_EMAIL: ${ES_API_EMAIL}
      ES_API_KEY: ${ES_API_KEY}
      ES_BENEFICIARY_IBAN: ${ES_BENEFICIARY_IBAN}
    volumes:
      - wp_data:/var/www/html
      - ./easy-square-qr:/var/www/html/wp-content/plugins/easy-square-qr

  wpcli:
    image: wordpress:cli
    depends_on:
      - wordpress
    user: "33:33"
    volumes:
      - wp_data:/var/www/html
      - ./easy-square-qr:/var/www/html/wp-content/plugins/easy-square-qr
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress

volumes:
  wp_data:

.env

ES_API_EMAIL=vas@email.sk
ES_API_KEY=esq_vas_kluc
ES_BENEFICIARY_IBAN=SK3112000000198742637541

init.sh

#!/bin/bash
set -e

echo "Čakám na WordPress..."
until curl -sf http://localhost:18080 > /dev/null; do sleep 2; done

docker compose run --rm wpcli wp core install \
  --url=http://localhost:18080 \
  --title="Test Shop" \
  --admin_user=admin --admin_password=admin \
  --admin_email=admin@test.local --skip-email

docker compose run --rm wpcli wp rewrite structure '/%postname%/' --hard
docker compose run --rm wpcli wp plugin install woocommerce --activate
docker compose run --rm wpcli wp plugin activate easy-square-qr
docker compose run --rm wpcli wp wc product create \
  --name="Testovací produkt" --type=simple \
  --regular_price=42.50 --status=publish --user=admin

echo ""
echo "Hotovo!"
echo "Shop:  http://localhost:18080/shop"
echo "Admin: http://localhost:18080/wp-admin (admin / admin)"

Spustenie

chmod +x init.sh
docker compose up -d
./init.sh

Po minúte máte funkčný e-shop na http://localhost:18080. Kúpte testovací produkt, pri dokončení objednávky sa vám pod sumarizáciou objednávky zobrazí Pay by Square QR kód.

Časté problémy

QR kód sa nezobrazí na ďakovnej stránke

Skontrolujte environment premenné cez docker compose exec wordpress env | grep ES_. Najčastejšia chyba je nesprávny API kľúč alebo chýbajúci IBAN.

Email klienti nezobrazujú base64 obrázok

Gmail a Apple Mail zobrazujú base64 obrázky bez problému. Outlook (desktop) môže blokovať — ak sa vás to týka, uložte PNG na server a pošlite ako <img src="https://vas-eshop.sk/wp-content/uploads/qr/order-{$id}.png">.

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.

Plugin sa neaktivuje — chýba súbor

Skontrolujte, že plugin je v priečinku wp-content/plugins/easy-square-qr/easy-square-qr.php (názov priečinka sa musí zhodovať s názvom súboru).

QR kód má nesprávny variabilný symbol

Predvolené nastavenie používa WooCommerce order ID ako variabilný symbol. Ak používate vlastné číslovanie faktúr (napr. cez WooCommerce Sequential Order Numbers plugin), nahraďte $order->get_id() za $order->get_order_number().

Dva QR kódy v emaili

Niektoré témy volajú woocommerce_email_after_order_table dvakrát (raz pre zákazníka, raz pre admina). Ak chcete QR kód len v zákazníckom emaili, obmedzte hook cez druhý parameter: function ($order, $sent_to_admin) { if ($sent_to_admin) return; ... }.

Nasadenie na produkciu

Pre reálny e-shop:

  1. Nakopírujte easy-square-qr/ priečinok do wp-content/plugins/ vášho WordPress.

  2. Nastavte environment premenné v wp-config.php:

    putenv('ES_API_EMAIL=vas@email.sk');
putenv('ES_API_KEY=esq_vas_kluc');
putenv('ES_BENEFICIARY_IBAN=SK3112000000198742637541');

  3. Aktivujte plugin v Pluginy > Nainštalované pluginy.

  4. Otestujte na jednej objednávke pred nasadením pre všetkých zákazníkov.

Záver

Integrácia Pay by Square do WooCommerce nie je zložitá — plugin má 30 riadkov PHP a celý setup vrátane Docker-based testovania sa dá postaviť za hodinu. Kľúčové je, že používateľovi ponúknete pohodlný spôsob platby bez inštalácie ďalších platobných brán.

Pre plnú dokumentáciu všetkých parametrov API (farby, rámček, veľkosť) pozrite REST API dokumentáciu. Pre PHP integrácie mimo WooCommerce nájdete samostatný článok Pay by Square QR kód v PHP cez REST API. API kľúč získate po registrácii na easy-square.sk/registracia/.