API dokumentácia — checkout cez bankový prevod

REST API pre platby prevodom v e-shope - vytvorenie transakcie, hosted platobná stránka s QR kódom, webhook notifikácia o zaplatení. Integrácia za pár minút.

Ako to funguje

Easy Pay je checkout cez bankový prevod — alternatíva platobnej brány bez provízií:

  1. Váš e-shop pošle objednávku jedným API callom — Easy Pay vytvorí proforma faktúru a vráti redirectUrl
  2. Zákazníka presmerujete na platobnú stránku s Pay by Square QR kódom
  3. Zákazník zaplatí prevodom vo svojej banke — priamo na váš účet
  4. Easy Pay platbu automaticky spáruje, vystaví faktúru a pošle vám webhook invoice.created

Dôležité: Jediný spoľahlivý signál, že objednávka je zaplatená, je webhook invoice.created (prípadne stavový endpoint). Návrat zákazníka na returnUrl je len mäkký signál — zákazník mohol kliknúť „Pokračovať" aj bez zaplatenia.

Rýchly štart

3 kroky k prvej platbe:

  1. Zaregistrujte sa — aktivujeme vám účet do jedného pracovného dňa
  2. V aplikácii na karte API si vytvorte API kľúč
  3. Spustite príkaz nižšie s vašimi údajmi
curl -X POST https://test-api.easy-pay.sk/public/api/v1/eshop/transactions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ep_vas_api_kluc" \
  -H "X-Idempotency-Key: objednavka-ABC123" \
  -d '{
    "customer": {"name": "Zákazník", "email": "zakaznik@example.sk"},
    "items": [{"name": "Objednávka ABC123", "quantity": 1, "unitPrice": 41.58, "vatRate": 20}],
    "currency": "EUR",
    "returnUrl": "https://vas-eshop.sk/navrat?order=ABC123"
  }'

Výsledok: JSON so redirectUrl — presmerujte naň zákazníka, ostatné prebehne automaticky.

Poznámka: Príklady používajú testovacie údaje. Pred nasadením do produkcie nahraďte všetky hodnoty reálnymi.

Autentifikácia

Hlavička Povinná Popis
X-API-Key áno API kľúč vytvorený v aplikácii na karte API
X-Idempotency-Key áno (pri POST) Unikátny kľúč požiadavky (odporúčame UUID alebo číslo objednávky)

Idempotencia chráni pred duplicitnými objednávkami pri opakovaní požiadavky: rovnaký kľúč s rovnakým telom vráti uloženú odpoveď, rovnaký kľúč s iným telom vráti chybu 422.

Vytvorenie transakcie

POST /public/api/v1/eshop/transactions
Content-Type: application/json

Synchrónne vytvorí proforma faktúru a platobnú session. Konverzia na riadnu faktúru prebehne asynchrónne po spárovaní platby s bankovým účtom.

Telo požiadavky

Parameter Typ Povinný Popis
customer object áno Odberateľ — vytvorí sa automaticky, ak ešte neexistuje
customer.name string áno Meno alebo obchodné meno
customer.email string áno Email — pošle sa naň proforma a faktúra
customer.ico string nie IČO — údaje sa doplnia automaticky z registra (RPO)
customer.dic string nie DIČ
customer.icDph string nie IČ DPH
customer.address object nie Adresa: street, city, zip, country
items array áno Položky proformy (1 – 200)
items[].name string áno Názov položky
items[].quantity number áno Množstvo
items[].unitPrice number áno Jednotková cena bez DPH
items[].vatRate number áno Sadzba DPH v %
items[].unit string nie Merná jednotka (predvolená ks)
currency string áno Mena, ISO 4217 (napr. EUR)
returnUrl string áno URL návratu zákazníka — Easy Pay pridá ?status=declared|timeout|paid&session_id=…
validUntil string nie Platnosť proformy (YYYY-MM-DD), predvolene +14 dní
variableSymbol string nie Vlastný variabilný symbol (max 10 číslic), predvolene číslo proformy
config.sendPeppol boolean nie Po spárovaní odoslať faktúru do siete Peppol (spoplatnené kreditom), predvolene false
config.peppolRecipientId string nie Peppol Participant ID príjemcu (povinné pri sendPeppol=true), napr. 0210:12345678
config.sendEmail boolean nie Po spárovaní poslať faktúru emailom (v paušáli), predvolene true
config.emailRecipient string nie Email pre doručenie faktúry, predvolene customer.email

Odpoveď (200)

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "proformaId": "660e8400-e29b-41d4-a716-446655440001",
  "proformaNumber": "20260042",
  "amount": 74.50,
  "currency": "EUR",
  "redirectUrl": "https://app.easy-pay.sk/p/550e8400-e29b-41d4-a716-446655440000",
  "statusUrl": "https://test-api.easy-pay.sk/public/api/v1/eshop/sessions/550e8400-…/status",
  "uiExpiresAt": "2026-06-12T14:35:00Z",
  "documents": {
    "proformaPdfUrl": "https://…",
    "qrPngUrl": "https://…"
  }
}
Pole Popis
sessionId ID platobnej session — použite na sledovanie stavu
proformaNumber Číslo proformy = variabilný symbol pre párovanie platby
redirectUrl Sem presmerujte zákazníka — hosted platobná stránka s QR kódom
statusUrl Endpoint pre sledovanie stavu (fallback k webhookom)
uiExpiresAt Časový limit platobnej stránky — proforma však zostáva platná aj po ňom
documents Podpísané URL na PDF proformy a PNG QR kódu

Neskorá platba: Po uplynutí uiExpiresAt sa platobná stránka zavrie, ale proforma nezaniká. Zákazník ju má v emaili s PDF a QR kódom — keď zaplatí aj o niekoľko dní, platba sa spáruje a faktúra sa vystaví normálne.

Stav platby

Webhook invoice.created je primárny signál zaplatenia. Párovanie prebieha na dennej báze zo spracovaných bankových výpisov — webhook príde spravidla nasledujúci pracovný deň po úhrade zákazníka, nie v minútach. Polling používajte ako zálohu, keď váš webhook prijímač nie je dostupný — odporúčaný interval ≥ 10 sekúnd.

Detail session

GET /public/api/v1/eshop/sessions/{sessionId}

Vráti stav session, čísla proformy a faktúry (po konverzii), sumu, URL dokumentov a časové pečiatky.

Ľahký stavový endpoint na polling

GET /public/api/v1/eshop/sessions/{sessionId}/status

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "paid",
  "invoiceId": "770e8400-e29b-41d4-a716-446655440002",
  "invoiceNumber": "FA2026042",
  "updatedAt": "2026-06-12T15:02:11Z"
}

Stavy: pending_payment → paid (po spárovaní a vystavení faktúry), prípadne cancelled.

Oba endpointy sú viazané na vašu firmu — cudzia session vráti 404.

Webhooky

Webhook URL si spravujete v aplikácii na karte API. Pri udalosti Easy Pay pošle POST s JSON telom na všetky aktívne endpointy prihlásené na danú udalosť.

Udalosť invoice.created

Odoslaná po spárovaní platby a vystavení faktúry — toto je potvrdenie zaplatenia.

{
  "event_type": "invoice.created",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440002",
  "invoice_number": "FA2026042",
  "proforma_id": "660e8400-e29b-41d4-a716-446655440001",
  "proforma_number": "20260042",
  "variable_symbol": "20260042",
  "amount": 74.50,
  "currency": "EUR",
  "issue_date": "2026-06-12",
  "due_date": "2026-06-26",
  "tax_point_date": "2026-06-12",
  "invoice_pdf_url": "https://…",
  "proforma_pdf_url": "https://…"
}

Ďalšie udalosti: invoice.peppol_sent, invoice.peppol_failed.

Hlavičky a overenie podpisu

Hlavička Popis
X-EP-Event-Type Typ udalosti, napr. invoice.created
X-EP-Signature sha256(telo_požiadavky + secret) v hex tvare

secret nájdete pri webhook endpointe v aplikácii. Overenie: spočítajte SHA-256 hash zo surového tela požiadavky spojeného so secretom a porovnajte s hlavičkou.

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto.createHash('sha256')
    .update(rawBody + secret)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Odpovedzte stavom 2xx — pri inej odpovedi Easy Pay doručenie opakuje s odstupom. História doručení s možnosťou opakovania je v aplikácii na karte API.

Chybové kódy

Stav Kód Popis
400 validation_error Chýbajúca hlavička X-Idempotency-Key alebo neplatné telo požiadavky
401 unauthorized Chýbajúci alebo neplatný API kľúč
402 ep_subscription_expired Paušál vypršal — predĺžte ho v aplikácii
402 ep_fair_use_exceeded Prekročený mesačný limit platieb plánu Štart — prejdite na Biznis
404 not_found Session neexistuje alebo nepatrí vašej firme
422 idempotency_conflict X-Idempotency-Key použitý s iným telom požiadavky

Ďalšie zdroje

  • Registrácia — aktivácia účtu do jedného pracovného dňa
  • Cenník — ročný paušál od 99 € bez DPH, žiadne provízie
  • Kontakt — pomoc s integráciou