Platobné QR kódy cez API

Požiadavka na QR kód

API URL = https://api.qrstart.eu
Method = POST


{
	"type": "bank",
	"apikey": "ApiKey",
	"amount": 1000,
	"currency": "CZK",
	"date": "20210101",
	"account": "123456789/6666",
	"note": "QR Platba",
	"variable": "20210001"
}

Odpoveď na QR kód


{
  "success": true,
  "url": "https://api.qrstart.eu/files/abcdefghijklmn.png"
}

Požiadavka na upload PDF súboru

API URL = https://upload.qrstart.eu
Method = POST multipart/form-data


curl -F "apiKey=ApiKey" -F "file=@/var/www/your-site/file.pdf" https://upload.qrstart.eu

Odpoveď na upload PDF súboru


{
  "success": true,
  "fingerprint": "315add676b4eeb3f606cfe8903448ed8c2ac468d"
}

Vstupné parametre

type - typ kódu
- možné hodnoty sú bank, ean13, code128, text (predvolené bank)
- type bank:
  - amount - suma (int alebo float)
    - povinné
  - currency - mena CZK alebo EUR
    - povinné pre CZ/SK bank
    - pre SEPA bank je currency automaticky EUR
  - bank - CZ alebo SK alebo SEPA
    - CZ pre český QR kód, SK pre slovenský QR kód (teda CZ pre české bankové aplikácie, SK pre slovenské bankové aplikácie)
    - SEPA znamená EPC SEPA formát
    - ak nie je vyplnené, použije sa CZ pre CZK menu a SK pre EUR menu
  - account - celé číslo účtu vrátane kódu banky (123-456789123/4567)
    - povinné pre CZK, ak nezadáte IBAN
  - iban - IBAN
    - povinné pre EUR (pre CZK iba ak nezadáte account)
  - swift - SWIFT kód (BIC)
  - variable - variabilný symbol
  - constant - konštantný symbol
  - specific - špecifický symbol
  - note - poznámka pre zákazníka
  - date - dátum splatnosti (YYYYMMDD)
  - size - veľkosť vygenerovaného obrázku v pixeloch (min. 50, max. 600, predvolené 150)
    - pre generovanie do pdf súboru je veľkosť (šírka) v bodoch (min. 50, max. 600, predvolené 150)
  - margin - okraje obrázku v pixeloch (predvolené 2)
  - tag - interná poznámka (štítok viditeľný v administrácii, max. 50 znakov)
  - reference - referencia platcu
    - pre SK bank EUR currency (variable a constant a specific musia byť prázdne)
    - pre SEPA bank
  - beneficiary - názov/meno príjemcu (max. 70 znakov)
    - povinné pre SEPA bank
    - pre SK bank odporúčané (špecifikácia PAY by square 1.2.0 ho vyžaduje), dlhší text sa skráti na 70 znakov
  - remittance - popis prevodu
    - iba pre SEPA bank (reference musí byť prázdna)
  - instant 0-1 (int) (predvolené 0)
    - pre okamžitú platbu použite hodnotu 1
    - iba pre CZ bank
- type ean13:
  - code - EAN-13 kód
    - povinné
  - size - 1-5 (int) (predvolené 2)
    - pre generovanie do pdf súboru je veľkosť (šírka) v bodoch (min. 50, max. 600, predvolené 150)
  - tag - interná poznámka (štítok viditeľný v administrácii, max. 50 znakov)
- type code128:
  - code - text
    - povinné
  - size - 1-5 (int) (predvolené 2)
    - pre generovanie do pdf súboru je veľkosť (šírka) v bodoch (min. 50, max. 600, predvolené 150)
  - tag - interná poznámka (štítok viditeľný v administrácii, max. 50 znakov)
- type text:
  - code - text
    - povinné
  - size - veľkosť vygenerovaného obrázku v pixeloch (min. 50, max. 600, predvolené 150)
    - pre generovanie do pdf súboru je veľkosť (šírka) v bodoch (min. 50, max. 600, predvolené 150)
  - margin - okraje obrázku v pixeloch (predvolené 2)
  - tag - interná poznámka (štítok viditeľný v administrácii, max. 50 znakov)
ak chcete do svojho PDF súboru (max. veľkosť 2 MB) vložiť QR kód, pridajte nasledujúce parametre
- fingerprint - fingerprint z požiadavky na upload
- top - pozícia zhora v bodoch
- bottom - pozícia zdola v bodoch
  - v jednej požiadavke použite buď top alebo bottom
- left - pozícia zľava v bodoch
- right - pozícia sprava v bodoch
  - v jednej požiadavke použite buď left alebo right
- page - stránka, na ktorú sa obrázok uloží (predvolené 1)
  - pre poslednú stránku použite hodnotu -1
- všetky rozmery a pozície v PDF sú v bodoch (1 bod = 1/72 palca ≈ 0,35 mm, 10 mm ≈ 28 bodov)
štandardne sa obrázok QR kódu generuje ako PNG, môžete ho však generovať aj ako JPG/WEBP
- output - jpg alebo webp
  - hodnota jpg vytvorí obrázok v JPG formáte
  - hodnota webp vytvorí obrázok vo WEBP formáte

github.com

QR kód môžete tiež generovať GET požiadavkou

Požiadavka na QR kód

API URL = https://api.qrstart.eu
Method = GET


https://api.qrstart.eu/?type=bank&apikey=XXXXXX&amount=10&currency=EUR&iban=SK3112000000198742637541

Výsledkom, ak je zadanie validné, je URL obrázku QR kódu. V opačnom prípade text s chybou a http kód 400.
Ak do URL dáte ako ďalší parameter &image=1 tak sa vám namiesto URL obrázku pošle priamo samotný obrázok.

image - výstup ako obrázok s header Content-Type image/png (alebo image/jpeg alebo image/webp)
- jediná možná hodnota je 1

Podpísaná požiadavka – bez zverejnenia API kľúča

Ak chcete QR kód vložiť priamo do verejnej stránky alebo e-mailu (<img src="...">), nedávajte do URL parameter apikey. Namiesto neho pošlite KID (Key ID) a podpis parametrov. API kľúč tak v URL nie je vidieť a nikto nemôže zmeniť žiadny parameter ani vytvoriť novú požiadavku.

API URL = https://api.qrstart.eu
Method = GET


https://api.qrstart.eu/?type=bank&amount=10&currency=EUR&iban=SK3112000000198742637541&image=1&kid=a1b2c3d4&signature=3f8a...e91c

kid - KID (Key ID) vášho API kľúča
- nájdete ho v administrácii my.qrstart.eu pri API kľúči
signature - podpis HMAC-SHA256 (hex, malé písmená)
- podpisujú sa všetky parametre požiadavky okrem kid a signature, zoradené podľa názvu a zakódované ako PHP funkcia http_build_query() (medzera ako +)
- kľúčom podpisu je váš API kľúč
pri zmene akéhokoľvek parametra API vráti chybu wrong signature
každé načítanie URL sa počíta ako požiadavka, URL nemá obmedzenú platnosť
podpis je možné namiesto parametra apikey použiť aj pre POST požiadavky a pre upload.qrstart.eu
v PHP SDK použite metódu signedUrl()


$params = [
	'type' => 'bank',
	'amount' => 10,
	'currency' => 'EUR',
	'iban' => 'SK3112000000198742637541',
	'image' => 1
];
ksort($params);
$params['signature'] = hash_hmac('sha256', http_build_query($params), 'ApiKey');
$params['kid'] = 'KID';
$url = 'https://api.qrstart.eu/?' . http_build_query($params);