Platební brány

Tento článek poskytne informace pro vývojáře, kteří by chtěli pro Shoptet vyvíjet napojení na platební bránu.

Koncept implementace

Pro integraci platební brány je potřeba implementovat následující části. V dalších kapitolách jsou uvedeny podrobnosti k jednotlivým krokům.

Nový způsob platby

Kontaktujte parner managera Shoptetu, abychom vám založili záznam pro vaši platební bránu v Shoptetu. V ní zaregistrujeme typ platby a vaši gateway pro přesměrování. V případě, že se různé platební metody mají v eshopu zobrazovat samostatně (např. „Platba kartou“, „Online převod“, „SMS platba“), bude založeno více záznamů. Dále je možné založit záznamy vždy jednou pro ostrý provoz a jednou pro vývojové prostředí. Tento záznam zaregistruje platební bránu jako zprostředkovatele, čili jakýsi technický prostředek pro provedení platby.

Gateway URL musí obsahovat 2 placeholdery, ve kterých vám v okamžiku platby předáme identifikaci eshopu (buď ID nebo URL) a jednorázový kód transakce:

Např. https://pay.to.me/gataway/#LANGUAGE#/#ESHOP_URL#/#PAYMENT_CODE#/

Jazyk platební brány lze nastavit podle hodnoty #LANGUAGE#, nebo podle hodnoty atributu eshopLanguage v api endpointu Eshop info

Druhým krokem je založení „Způsobu platby“. Způsoby platby se již zakládají v každém eshopu samostatně a vystavují zprostředkovatele založeného v předchozím odstavci v eshopu. Způsoby platby se vytvářejí v administraci eshopu a je třeba nastavit popisky, ceny, podmínky podle měny, země doručení, doručovací služby nebo ceny objednávky, popř. nastavit logo. Více informací naleznete na stránkách Podpory.

Způsob platby je však možné i pro eshopaře připravit, aby nastavení vypadala podle vašich představ a ušetřili jste eshopaři práci. Pro vytvoření musíte být zaregistrovaný jako zprostředkovatel (viz první odstavec). Založení se provede pomocí endpointu POST /api/payment-methods.

Nový způsob platby založte jako neaktivní, aby se neprojevil v eshopu dříve, než si ho eshopař prohlédne a odsouhlasí, popřípadě poupraví parametry. Způsob platby by také neměl být viditelný předtím, než eshopař podepíše smlouvu a získá přístupové údaje k platební bráně.

Objednávka – krok 1 – platební metody

Jakmile je v eshopu nainstalován doplněk a založena platební metoda, zobrazí se automaticky (pokud splní podmínky v kombinaci s dopravou, měnou, výší objednávky atp).

Objednávka – děkovací stránka

Pokud nakupující zvolil vaši platební bránu, na stránce potvrzení objednávky (děkovací stránce) se zobrazí tlačítko pro zaplacení online. Uživatel na něj může kliknout nebo je po 5 vteřinách automaticky přesměrován na vaši platební bránu (gateway URL, které jste nám uvedli).

V gateway URL budou nahrazeny placeholdery #ESHOP_ID#, #ESHOP_URL# a #PAYMENT_CODE# skutečnými hodnotami. Payment Code slouží jako identifikace platební transakce.

Odkaz na děkovací stránce na Shoptet (a na potvrzovacím emailu zákazníkovi) obsahuje URL adresu Shoptetu, která obratem přesměruje na gateway URL platební brány.

Proces placení

Platební brána může poupravit své API nebo doplněk může tvořit „proxy“ mezi Shoptetem a API platební brány.

V prvním kroku musí doplněk získat informace o objednávce, která je předmětem platby, a URL pro návrat do eshopu. To se učiní pomocí endpointu [GET] /api/payment-status/{paymentCode} – viz dokumentace v Apiary.

Informace o objednávce získáte pomocí endpointu Detail objednávky. Pozor, že code objednávky vypadá jako číslo, je to ale řetězec (může obsahovat i písmena).

Pokud potřebjete podrobnější informace o eshopu (např. email, jazyk), můžete použít endpoint Eshop info.

Je třeba počítat s tím, že k platbě se nakupující může dostat i později než bezprostředně po nákupu, např. odkazem z emailu. Doplněk musí ověřit, jestli už objednávka nebyla zaplacena (nakupující vlezl na odkaz z nějakého důvodu znovu) či zda nebyla mezitím stornována. V případě, že by objednávka byla již zaplacena nebo stornována, je to nějaká nekonzistentní situace a doplněk by ji měl eskalovat na majitele eshopu a popř. nakupujícího.

Dále již probíhá placení podle funkce platební brány, tedy volitelně výběr způsobu platby, výzva k zadání údajů atd.

Nastavení výsledku platby

Výsledek platby je třeba reflekrovat na dvou místech:

Stav platby

Výsledný stav platby se nastaví voláním endpointu [PATCH] /api/payment-status/{paymentCode} – viz dokumentace v Apiary.

Výsledek platby má tyto stavy:

Při volání endpointu je možné uvést

Objednávka

Podle výsledku platby je potřeba nastavit stav objednávky. Eshopy Shoptetu mají stavy pro objednávky konfigurovatelné, je tedy potřeba počítat s tím, že pro každý eshop je třeba v nastavení specifikovat, jaký stav objednávky odpovídá jakému stavu platby.

Seznam stavů objednávky, které má eshop nadefinované, lze zjistit voláním endpointu Eshop info /api/eshop?include=orderStatuses – viz dokumentace.

Doplněk platební brány musí umět nastavit přinejmenším stav, který odpovídá zaplacení objednávky. Je ale lepší umožnit eshopaři nastavit také stav, který se nastaví v případě selhání placení a v případě, kdy se čeká na potvrzení (stav „pending“ – probíhající).

Stav objednávky se nastaví voláním endpointu Změna stavu objednávky PATCH /orders/{code}/status (viz dokumentace v Apiary).
V případě úspěšného zaplacení je potřeba uvést formu úhrady (hotově, převodním příkazem, kartou…), odpovídající platební metodě, kterou uživatel k placení zvolil.

Součástí definice stavu v Shoptetu je již příznak zaplacení (tedy že přepnutí do daného stavu zároveň označí objednávku za zaplacenou), možnost generovat dokumenty (fakturu, dodací list) a odeslat email. O to se tedy doplněk platební brány nemusí starat.

Volitelně doplněk může posílat email nakupujícímu i eshopu o průběhu plateb nebo v případě detekce nestandardního stavu.

Volitelně může doplněk do objednávky doplnit údaje jako např. číslo platby na straně platební brány pomocí endpointu Změna poznámek objednávky api/orders/{code}/notes – viz dokumentace.

Doplněk by měl i ověřit, že objednávka je v očekávaném stavu (tedy nezaplacená) a cena objednávky zůstala nezměněná (eshopař ji mohl mezitím změnit nebo stornovat). Řešení případné nekonzistence už necháme na doplňku.

Návrat do eshopu

Pokud je nastaven stav objednávky a výsledek platby, doplněk zavolá naši návratovou URL.

Shoptet podle stavu platby vykreslí děkovací stránku:

Průběžná činnost doplňku

Krom samotného placení musí doplněk ještě sledovat změny na probíhajících platbách a nastavovat podle nich stavy objednávek. Volitelně k tomu může posílat emaily nebo upozorňovat na příliš dlouho probíhající platby.
Platby, které selhaly, může doplněk posílat s odkazem na opětovné placení.

Nastavení doplňku

Nastavení doplňku zatím není možné umístit přímo do administrace Shoptetu, nýbrž musí být provozováno na serveru vývojáře doplňku. Založení klientského účtu je zpravidla inicializováno během instalace doplňku. Identitu eshopaře je možno ověřit přímo v Shoptetu prostřednictvím OAuth.

Doplněk musí poskytovat své GUI pro nastavení parametrů přinejmenším:

Facebook
Twitter