V prípade, že systém neobsahuje implementáciu Vami požadovanej platobnej brány (Podporujete bankovní online platby? (Trustpay, PayPal...)) je možné si vytvoriť vlastnú implementáciu platobnej brány. Implementácia vyžaduje programátorské skúsenosti a vlastný hosting kde bude bežať Váš skript pre prepojenie systému WEXBO® a platobnej brány.
Základné pokyny
- V sekcii Doplňky / Pluginy / Platební brány po kliknutí na tlačítko Přidat platební bránu pridajte platobnú bránu s názvom "Vlastná platobná brána" kde získate "Klíč (heslo)" pre implementáciu prepojenia.
- V sekcii Eshop / Platba po kliknutí na tlačítko Přidat způsob platby pridajte spôsob platby a v úprave v položke "Typ platby" nastavte pred-vytvorenú platobnú bránu. Pre testovanie odporúčame danú platbu zobraziť napr. len skupine "Administrátor".
- Je nutné si u niektorého z poskytovateľov hostingu vytvoriť hostingový priestor, kde umiestnite prepojovací vlastný skript.
- Skript napojenia na samotnú platobnú bránu je nutné vytvoriť na základe technickej dokumentácie požadovanej platobnej brány a následne ho umiestniť na uvedený hosting, aby bol dostupný na URL adrese. Využiť je možné subdoménu Vašej domény, ktorú nastavíte, resp. potrebné DNS záznamy subdomény nastavíte v sekcii Nastavení / Domény po kliknutí na akciu požadovanej domény.
- Nakoniec v skripte vytvorte prepojenie medzi systémom WEXBO®, resp. pred-vytvorenou platobnou bránou "Vlastná platobná brána" a požadovanou platobnou bránou, resp. Vaším skriptom umiestneným na vlastnom hostingu. Prepojenie vykonáte podľa dokumentácie uvedenej nižšie, avšak v prvom rade zadaním URL adresy na Váš skript do položky "URL adresa" v sekcii Doplňky / Pluginy / Platební brány v úprave platobnej brány "Vlastná platobná brána" .
Proces spracovania
Popis spracovania
- Ak si zákazník v košíku vyberie spôsob platby cez "Vlastná platobná brána", po vytvorení objednávky sa zobrazí tlačítko s odkazom na vlastný skript (položka "URL adresa" v úprave platobnej brány v systéme WEXBO®).
- Po kliknutí na tlačítko, systém WEXBO® zákazníka presmeruje na zvolenú URL adresu (Vášho skriptu), kde zároveň v požiadavke odošle aj všetky potrebné dáta ohľadom objednávky (ID objednávky, celková suma, informácie o zákazníkovi, návratové či notifikačné URL adresy, atď.). Dáta sú odosielané metódou POST v parametri s názvom "token" zabalené v štruktúre typu JWT.
- Váš skript načíta daný POST parameter "token" a dekóduje (Base64) do štruktúry JWT (JSON), prípadne pomocou uvedeného algoritmu (SHA256) a tajného kľúča ("Klíč (heslo)") overí konzistenciu prijatých dáta. Tento proces je už súčasťou pred-vytvoreného skriptu "index.php", (viď. odstavec "Prepojenie"). Príklad prijatých dát vo formáte JSON:
{
"account": {
"alg": "HS256",
"crypt": "AES-256-CBC",
"domain": "example.com",
"email": "info@example.com",
"endpoint": "pg_100",
"eshop_id": 1,
"test": false,
"timestamp": 1700000000,
"type": "frontend",
"uuid": "1bd118e7-3c82-8f95-5e46-5ff5b6d3484f",
"version": "v1"
},
"customer": {
"city": "Bratislava",
"country": "sk",
"country_code": 703,
"email": "customer@gmail.com",
"first_name": "John",
"ip": "127.0.0.1",
"last_name": "Doe",
"name": "John Doe",
"phone": "+421910123456",
"street": "Uličná",
"street_number": "1",
"zip": "81101"
},
"items": [
{
"type": "item",
"id": 1000001,
"name": "Dezertový tanier",
"price_unit_novat": 5,
"price_total_novat": 5,
"price": 6,
"quantity": 1,
"url": "https://www.example.com/d/1000001/",
"vat": 20
},
{
"type": "shipping",
"price": 6,
"quantity": 1,
"vat": 0
}
],
"order": {
"amount": 12,
"currency": "EUR",
"currency_code": 978,
"description": "Objednávka 12000001",
"language": "sk",
"reference": "12000001",
"session": "ac257332fdfb376957383291c5878a4d",
"timestamp": 1700000000
},
"url": {
"cancel": "cancel/",
"error": "error/",
"notification": "notification/",
"pending": "pending/",
"return": "https://www.example.com/cart/pay/pg_100/",
"success": "success/"
}
} - Získané dáta o objednávke v štruktúre JSON si Váš skript musí uložiť do databázy alebo súboru, a následne využiť na vytvorenie požiadavky pre presmerovanie či zobrazenie okna platobnej brány, kde zákazník vykoná samotnú platbu.
- Po vykonaní platby bude zákazník presmerovaný späť na zvolenú URL adresu (Váš skript), ktorý spracuje stav vykonania platby (uhradené, zrušená platba, čaká sa na úhradu, atď.).
- Nakoniec Váš skript presmeruje zákazníka späť do e-shopu na ďakovnú stránku aj so stavom platby. Návratová URL adresa pre konkrétny stav je obsiahnutá v dátach o objednávke, ktorú Vám systém už odoslal (viď. bod 3. a 4.).
- Systém WEXBO® zobrazí zákazníkovi ďakovnú obrazovku s odoslaným stavom platby, prípadne tlačítko pre opakovanie platby pri jej zrušení.
- Dodatočne Váš skript môže poslať informáciu o stave či spracovaní platby, aby systém WEXBO® označil objednávku ako uhradenú. Tento stav platby sa odosiela na pozadí. Pre tento účel slúži pred-vytvorený notifikačný skript "notification.php", (viď. odstavec "Prepojenie"), pričom notifikačná URL adresa, na ktorú sa odosiela stav platby je obsiahnutá v dátach o objednávke, ktorú Vám systém už odoslal (viď. bod 3. a 4.).
Prepojenie
Vzorové skripty pre prepojenie aj s pred-vytvorenou triedou v programovacom jazyku PHP poskytujeme v ZIP súbore "wexbo_payment_gateway_v1.zip", ktorý je možné si stiahnuť. Stiahnutý súbor ZIP je nutné rozbaliť, požadovane upraviť a nahrať na hosting, pričom sa v ňom nachádzajú nasledujúce PHP skripty:
- wexbo_payment_gateway.php - Trieda (PHP class) pre jednoduchšie spracovanie a odosielanie požiadaviek.
- index.php - Príklad vlastného skriptu pre príjem dát o objednávke so systému WEXBO® a následné presmerovanie späť do e-shopu aj so stavom platby. Skript neobsahuje samotné napojenie na platobnú bránu, ktoré je nutné do skriptu doplniť.
- notification.php - Príklad notifikačného skriptu, ktorý odosiela stav platby do systému WEXBO® na pozadí, po tom čo už bol zákazník presmerovaný do e-shopu na ďakovnú stránku. Skript slúži na hlavne na automatické priradenie úhrady k objednávke, prípadne zapísanie stavu platby do histórie objednávky. Skript neobsahuje samotné napojenie na platobnú bránu, ktoré je nutné do skriptu doplniť.
Do skriptov "index.php" a "notification.php" je nutné doplniť premennú "WEXBO_PAYMENT_GATEWAY_KEY", pričom hodnotu pre ňu nájdete v sekcii Doplňky / Pluginy / Platební brány v úprave pred-vytvorenej platobnej brány "Vlastná platobná brána" v položke "Klíč (heslo)". Jedná sa o tajný kľúč, ktorý slúži na šifrovanie, dešifrovanie, podpisovanie a overenie odosielaných dát.
Všetky informácie o objednávke aj s návratovými URL adresami a notifikačnou URL adresou sú obsiahnuté v POST parametri "token", ktorý ukážkový skript "index.php" spracuje a zobrazí.
Prepojenie bez programovania a hostingu
Na prepojenie je pravdepodobne možné využiť niektorý z nástrojov na automatizáciu prepojení, ktorý podporuje napojenie na požadovanú platobnú bránu. Odpadá tak nutnosť hostingu či nejaká znalosť samotného programovania. Automat samozrejme musí dokázať prijímať a odosielať požiadavky metódou POST, dekódovať dáta prostredníctvom Base64, podporovať štruktúru dát vo formáte JWT, prípadne len JSON a podporovať algoritmus SHA256, čo by mali byť bežné nástroje pre automatizáciu. Príkladom služieb daného typu sú Make, IFTTT, Zapier, Integrately, Celigo, n8n, Power Automate, atď.