VIAMO PayGate API (2.0.0)

• timestamp — používa sa všade, kde sa očakáva presný čas; hodnota je typu number a predstavuje počet sekúnd od začiatku Unixovej epochy
• date — používa sa tam, kde je významný celý kalendárny deň a nie konkrétny čas (napr. platnosť mandátu opakovanej platby); hodnota je typu string vo formáte ISO 8601 RRRR-MM-DD (napr. 2029-03-15). Deň je vždy vrátane — mandát s expiresOn 2029-03-15 je platný celý 15. marec 2029
• amount — všetky sumy sú v centoch, celé číslo, typ number (napr. suma 2,43 € je 243)
• object — každý objekt má pole object, ktoré hovorí, o aký typ objektu ide (napr. payment, recurring)
• list — ak je odpoveďou zoznam, vráti sa objekt typu list s poľami object, url, hasMore (true, ak kritériám vyhovuje viac objektov, ako bolo vrátených) a data (maximálne 50 objektov)
• POST request body — telo požiadavky je možné posielať ako JSON (Content-Type: application/json) alebo FORM (Content-Type: application/x-www-form-urlencoded); odpoveď je vždy JSON

Obchodník sa voči API autentifikuje prideleným API kľúčom v HTTP hlavičke X-API-KEY. Volať je možné iba z vopred definovaných IP adries. Všetky volania musia byť vykonané cez HTTPS — volania cez HTTP alebo bez autentifikácie skončia chybou.

API kľúč je potrebné mať bezpečne uschovaný. Nezdieľajte ho na verejne dostupných miestach ako GitHub, klientský kód a podobne.

Opakovaná BLIK platba umožňuje obchodníkovi účtovať platiteľa bez jeho interakcie, na základe súhlasu (mandátu), ktorý platiteľ potvrdil vo svojej bankovej aplikácii. Podporované sú tri modely:

Životný cyklus mandátu:

1. Platiteľ na stránke obchodníka vyjadrí vôľu zriadiť opakovanú platbu (povinná podmienka BLIK schémy).
2. Obchodník pošle POST /payments s BLIK kódom (blik.type=TICKET) a blokom recurring — pozvánka na zriadenie mandátu sa pripojí k bežnej platbe. Suma môže byť aj 0 (mandát sa zriadi bez toho, aby sa platiteľovi čokoľvek zúčtovalo); nulová suma je povolená iba s blokom recurring, inak požiadavka skončí chybou WRONG_AMOUNT. Za platbu s nulovou sumou sa neúčtuje transakčný poplatok. Pozor: pri nulovej sume nemá platba čo zúčtovať, takže vydavateľ bez podpory PAYID aliasov ju odmietne celú (PAYID_NOT_SUPPORTED) — rovnako ako pri refuseNoPayid=true. Mandát vznikne v stave INVITED; jeho id je v odpovedi v poli recurringId.
3. Platiteľ v bankovej aplikácii jedným krokom potvrdí platbu aj zriadenie mandátu.
4. Po registrácii aliasu vydavateľom prejde mandát do stavu ACTIVE — obchodník je notifikovaný webhookom (payloadType=recurring). Až od tohto momentu je možné mandát účtovať. Ak registrácia neprebehne do 24 hodín, mandát prejde do stavu REJECTED.
5. Účtovanie: POST /payments s blik.type=RECURRING a blik.recurringId. Vydavateľ má na autorizáciu až 72 hodín — platba zostáva v stave PROCESSING; obchodník sa dopytuje na GET /payments/{id}. Pri modeloch A a O je možné vyžiadať okamžitú odpoveď (blik.noDelay=true).
6. Zamietnutú platbu je možné zopakovať cez blik.retryPaymentId (id zamietnutej platby) — platba si zachová rovnaké id; opakovať možno najviac 3-krát (spolu 4 pokusy). Opakovania nepredlžujú 72-hodinové okno pôvodnej platby, iba ho zdieľajú.
7. Mandát zaniká: zrušením platiteľom v bankovej aplikácii, zrušením obchodníkom (DELETE /recurrings/{id}), alebo uplynutím platnosti. O každej zmene stavu je obchodník notifikovaný webhookom.

Storno platby z mandátu sa vykonáva štandardne cez POST /stornos.

Ak má obchodník nakonfigurovanú notifikačnú URL, VIAMO na ňu posiela HTTP POST s objektom notification. Pole payloadType určuje typ payloadu:

• alias — zmena OneClick aliasu (objekt alias)
• recurring — zmena mandátu opakovanej platby (objekt recurring); ak sa notifikácia týka konkrétnej platby (strata MIT výnimky, scaRejected), jej id je v poli paymentId

Pravosť payloadu je možné overiť poľom sign — viď nižšie.

Podpis objektov (sign)

Objekty recurring a alias nesú pole sign. Overením sa obchodník uistí, že payload pochádza z VIAMO a že sa cestou nezmenil — týka sa to rovnako webhookov ako odpovedí GET /recurrings/{id}, GET /recurrings/search a GET /aliases/search.

Podpisuje sa prideleným API kľúčom obchodníka — tou istou hodnotou, akou sa autentifikuje volanie PAPI (hlavička X-API-KEY). Kľúč je zdieľané tajomstvo: vstupuje do hashu, ale sám sa nikdy neprenáša v payloade.

Postup:

1. Zreťazte hodnoty polí v uvedenom poradí, bez akéhokoľvek oddeľovača, presne v tvare, v akom sú v JSON-e (čísla desiatkovo, bez formátovania).
2. Reťazec zakódujte do UTF-8 a vypočítajte SHA-256.
3. Výsledok zapíšte ako hexadecimálny reťazec malými písmenami, 64 znakov.

Chýbajúce pole sa do podpisu vkladá ako literál null (štyri znaky). Payload sa serializuje bez prázdnych polí, takže pole, ktoré v JSON-e nevidíte, do reťazca vstupuje ako null — týka sa to expiresOn mandátu aj aliasu (bez konca platnosti) a appLabel aliasu.

Príklad — mandát bez konca platnosti, API kľúč TEST_API_KEY_123:

id        = b3f1c0d4e5a6478fa1b2c3d4e5f60718
state     = ACTIVE
model     = M
expiresOn = (pole chýba)

reťazec:  b3f1c0d4e5a6478fa1b2c3d4e5f60718ACTIVEMnullTEST_API_KEY_123
sign:     676d7bd8d58d4f63f3e21e636f82093e0a88afd259af4786fbfa51290064d9f4

Príklad — mandát s koncom platnosti (expiresOn vstupuje ako dátum, presne tak, ako je v JSON-e):

id        = b3f1c0d4e5a6478fa1b2c3d4e5f60718
state     = ACTIVE
model     = A
expiresOn = 2029-03-15

reťazec:  b3f1c0d4e5a6478fa1b2c3d4e5f60718ACTIVEA2029-03-15TEST_API_KEY_123
sign:     79dd1332418f5d9359b06fa34892a3a0dd301dff28cdc00abea69cbf8a2de630

Príklad — alias:

userId    = payer@example.com
appKey    = 655158
appLabel  = TEST APP
expiresOn = 1798761600
state     = VALID

reťazec:  payer@example.com655158TEST APP1798761600VALIDTEST_API_KEY_123
sign:     e62668164aed280de0f68d999a0b51c1285e0dea26a68c9f006f2cfe3bacef4f

Vytvorenie BLIK platby (LEVEL 0), zistenie stavu a vyhľadávanie platieb.

Mandáty pre opakované BLIK platby — vytvárajú sa cez POST /payments s blokom recurring.

Stornovanie (vrátenie) platby.

Požiadavky na vyplatenie a ich stav.

Aktuálny zostatok obchodníka.

Registrované BLIK OneClick aliasy (UID) pre platby jedným klikom.