Modul: CardPay pre PrestaShop / thirty bees

Platobná brána CardPay umožňuje zákazníkom bezhotovostnú platbu debetnými a kreditnými kartami VISA, VISA Electron, MasterCard, Maestro a Diners Club International za zakúpený tovar vo Vašom e-shope, v prospech Vášho bankového biznis účtu vedeného v Tatra banke. CardPay podporuje Apple Pay a Google Pay. Modul zabezpečuje spracovanie platby a šifrovanú komunikáciu medzi Vašim internetovým obchodom PrestaShop a platobným rozhraním Tatra banky - tatrabanka.sk.

Vlastnosti platobnej brány

Zoznam vlastností nižšie je len orientačný. Všetky aktuálne obchodné podmienky o prevádzkovaní platobnej brány CardPay a rozsah ponúkaných služieb nájdete na webe www.tatrabanka.sk alebo na obchodnom oddelení banky.

• obchodník musí mať vedený biznis účet v Tatra banke - zmluvu vie uzavrieť na pobočke banky (nie vo všetkých je to možné) a peniaze prijímané z kartových operácií v e-shope si nechať zasielať iba na spomínaný účet.
• podporované karty:
  • VISA
  • VISA Electron
  • MasterCard
  • Maestro
  • Diners Club International
• podpora platieb cez Apple Pay
• podpora platieb cez Google Pay
• dostupné platobné meny:
  • Euro
  • Americký dolár
  • Česká koruna
  • Anglická libra
  • Maďarský forint
  • Poľský zloty
  • Švajčiarský frank
  • Dánska koruna
• dostupné jazyky platobného rozhrania:
  • slovenský
  • český
  • anglický
  • poľský
  • maďarský
  • nemecký
  • španielský
  • francúzsky
  • talianský

Vlastnosti modulu

• nešifrovaný a otvorený kód modulu
• možnosť určiť spôsob objednávania
  • vytvorenie objednávky pred platbou (identifikátorom platby je číslo objednávky)
  • vytvorenie objednávky po zaplatení (identifikátorom platby je číslo nákupného košíka)
• šifrovanie dát algoritmom:
  • HMAC SHA256 (v platnosti od mája 2015)
• podpora platby vo viacerých platobných menách - ak máte uzavretú zmluvu pre platby kartou vo viacerých menách
• možnosť určiť a párovať stavy objednávok, ktoré modul priraďuje objednávkam v závislosti od stavu platby priamo v administrácii modulu
• možnosť dokončiť platbu neskôr a/alebo zrušiť nedokončenú platbu - v histórii objednávok nájde zákazník výzvu na opakovanie platby, ak je objednávka stále v stave čakania na platbu
• možnosť zaslania odkazu na dokončenie či opakovanie platby kartou zákazníkovi v notifikačnom e-maile
• možnosť vložiť marketingové a affiliate kódy do posledného kroku platby
• možnosť zobraziť logá platobných kariet z modulu kdekoľvek v e-shope, formou jednoduchého vloženia ukotvenia do TPL šablóny
• všetky logá podporovaných platobných kariet sú v bezstratovom formáte SVG a tvarované ako dlaždice CSS kódom
• "classic" aj "modern" šablóny notifikačných e-mailov modulu + TWIG šablóna pre generovanie HTML šablón
• záznam transakcií do .LOG súboru v koreňovom priečinku modulu a prístupné z administrácie modulu
• automatická implementácia ikony platobného systému a lôg akceptovaných bankových kariet vo verejnej časti Vášho obchodu
• automatická implementácia príslušných nových stavov objednávok a notifikačných e-mailových šablón do PrestaShop-u
• možnosť meniť pozíciu platobnej ikony z administrácie modulu (ľavý / pravý stĺpec, stránka detailu produktu)
• možnosť nastaviť odkaz cieľovej statickej (CMS) stránky z ikony CardPay
• možnosť vypnúť/zapnúť ikony Material Design Icons
• rýchla inštalácia
• jednoduché nastavenie

Kroky implementácie služby CardPay

1. Uzavrite s Tatra bankou zmluvu o prevádzkovaní platobnej brány pre už existujúci e-shop a potom obdržíte osobné číslo obchodníka a šifrovací kľúč.
2. Nainštalujte, nastavte a otestujte modul vo Vašom PrestaShop-e (postupujte podľa "Inštalácia a testovanie modulu").
3. Týmto je modul je pripravený k prevádzke.
4. Ak modul nepracuje správne, kontaktujte nás.

Vloženie štatistických a marketingových meracích kódov

Ak potrebujete vložiť štatistické a marketingové / affiliate meracie kódy, môžete tak urobiť v šablóne modulu /modules/cardpay/views/templates/front/tracking_codes.tpl. Následujte premennú $payment_status, ktorá nadobúda stav"success" pre úspešnú platbu, alebo "fail" pre neúspešnú, alebo neuskutočnenú platbu. Tento spôsob vloženia kódov je potrebný iba vtedy, ak je v nastaveniach modulu vybratá voľba pre spôsob objednávania "vytvoriť objednávku pred zaplatením".

Dostupné sú nasledujúce premenné - nezabudnite použiť tagy {literal} {/literal}:

• {$total} - celková cena objednávky
• {$order_reference} - kód objednávky
• {$order_id} - číslo objednávky
• {$currency_iso} - platobná mena objednávky - ISO kód (napr.: 987 pre Euro, 203 pre Českú korunu)
• {$currency_sign} - platobná mena objednávky - kód (napr.: EUR pre Euro, CZK pre Českú korunu)

Pre vloženie kódov odporúčame osloviť PHP & SMARTY programátora.

Inštalácia a testovanie modulu

1. Overte, že konfigurácia Vášho servera má zapnuté rozšírenie: openssl_verify. V opačnom prípade nebude modul fungovať.
2. Nahrajte priečinok "cardpay" manuálne do priečinku /modules/ prostredníctvom FTP, alebo použite nástroj pre nahrávanie modulov v časti Ovládací panel » Moduly » Správca modulov » Nahrať modul.
3. Ak ste modul nahrali cez FTP, vykonajte jeho inštaláciu v časti: Ovládací panel » Moduly » Knižnica modulov
4. Ak ste modul nahrali cez rozhranie ovládacieho panela, modul sa súčasne aj nainštaloval.
5. Prejdite k nastaveniam: Ovládací panel » Platby » Predvoľby » Obmedzenia na základe meny, a zaškrtnite všetky platobné meny, pre ktoré máte pre CardPay uzavretú zmluvu.
6. Prejdite do nastavení modulu a zadajte údaje nasledovne:
   1. otvorte si v jednom okne prehliadača testovaciu stránku Tatra banky: moja.tatrabanka.sk
   2. zo stránky moja.tatrabanka.sk skopírujte hodnoty ID obchodníka (MID) a Kľúč (KEY). V druhom okne prehliadača ich potom vložte do nastavenia modulu a uložte. Pri čistej inštalácii modulu nájdete tieto polia už predvyplnené testovacími údajmi Tatra banky.
   3. voľbu "Testovanie a režim odhaľovania chýb" nastavte do stavu "áno"
   4. v treťom okne prehliadača prejdite do verejnej časti e-shopu a vložte do košíka tovar (ako bežný zákazník)
   5. v nákupnom košíku si z ponuky platobných brán vyberte platobnú bránu "CardPay"
   6. v ďalšom kroku sa Vám otvorí stránka obsahujúca červenou farbou zvýraznené údaje
   7. otvorte si opäť prvé okno prehliadača a nastavte testovací nástroj Tatra banky údajmi zobrazenými v predchádzajúcom kroku
   8. po vyplnení údajov stlačte tlačidlo "Overiť podpis"
   9. údaje vo Vašom e-shope sa musia zhodovať s údajmi vygenerovanými nástrojom Tatra banky, vrátane podpisu platby HMAC
   10. v prípade, že sa podpisy nezhodujú, prekontrolujte všetky vstupné údaje. Ak ani opakovane nedosiahnete zhodu, kontaktujte prosím autora modulu.
   11. ak sa podpisy zhodujú, odporúčame urobit odtlačok obrazovky obsahujúci súčasne obe okná prehliadača (ktorý môžete zaslať pracovníkovi Tatra banky ako úspešný výsledok testu)
   12. prejdite do nastavenia modulu a:
       1. nastavte voľbu "Testovanie a režim odhaľovania chýb" nastavte do stavu "nie"
       2. vložte hodnoty "ID obchodníka" a "Šifrovací kľúč". Oba údaje nájdete vo Word dokumente, umiestnenom v zaheslovanom archíve, ktorý ste od Tatra banky dostali e-mailom. Šifrovací kľúč je možné tiež získať oskenovaním QR kódu. Do modulu zadajte hexadecimálnu verziu šifrovacieho kľúča (má 128 znakov).
       3. ďalšie možnosti modulu nastavte podľa želania
7. Kontaktujte zamestnanca banky a oznámte mu dátum, od ktorého má banka na svojej strane systém CardPay pre Váš e-shop zapnúť. Prepošlite mu aj odtlačok obrazovky testu z bodu č.XI.
8. Týmto je modul pripravený pre prácu v ostrej prevádzke.
9. Pri inštalácii modulu došlo k automatickému umiestneniu ikôn platobného systému v detaile produktu verejnej časti obchodu. Ikony viete zobraziť v ľubovolnej časti e-shopu vložením kódu {hook h='displaycardpayicons'} do TPL šablón.
10. V súvislosti s ochranou osobných údajov podľa smernice GDPR doplňte do prehlásenia o GDPR vo Vašom e-shope informácie o platobnej bráne CardPay so zoznamom nižšie uvedených údajov zákazníka, ktoré do platobnej brány odosielate.:
    • Meno a priezvisko (Name)
    • E-mailová adresa (Email address)
    • Domáce telefónne číslo (Home phone number)
    • Číslo mobilného telefónu (Mobile phone number)
    • Fakturačná adresa (Billing address)
    • Dodacia adresa (Shipping address)
11. Pokiaľ by sa vyskytol problém, skontrolujte najskôr správnosť údajov vložených do nastavení modulu. Ak problém naďalej pretrváva, kontaktujte autora modulu.

Časté otázky pri prevádzke modulu

Pri platobnom procese sa zobrazí biela stránka. Prečo a ako problém odstrániť?
Odpoveď: Modul využíva pre generovanie bezpečnostného podpisu platby funkciu, ktorá je dostupná až vo verzii PHP 5.4 a vyššej. Váš obchod pravdepodobne beží na PHP serveri verzie 5.3 alebo nižšej. Aktualizujte prosím verziu PHP servera. Ak neviete o čo sa jedná, oslovte s požiadavkou poskytovateľa Vášho webhostingu.

Prečo sa, aj po otestovaní modulu na strane Tatra banky zobrazí informácia o vypršaní časového limitu?

Odpoveď: Po úspešnom otestovaní modulu, musí samotný bankový dom svoj systém pre Váš obchod zapnúť. Nie je to teda chyba modulu, ani dôvod na jeho reklamáciu, či vyžiadanie si pomoci. Je potrebné iba počkať, prípadne opakovane požiadať Tatra banku o zapnutie systému pre Váš e-shop.

V dizajne modulu CardPay vo verejnej časti obchodu sa mi zobrazuje pravý / ľavý stĺpec šablóny, aj keď sa pri iných platobných moduloch nezobrazuje. Kde a ako môžem nastaviť zobrazenie stĺpcov?
Odpoveď: Prejdite prosím do časti Ovládací panel > Predvoľby > Šablóny a logá (Back Office > Preferences > Themes), pri aktuálne zvolenej šablóne kliknite na tlačidlo "Upraviť". Následne sa dostanete do časti, kde môžete ovládať zobrazovanie stĺpcov pre rôzne stránky e-shopu. Pre modul CardPay nájdite položky "module-cardpay-payment" a "module-cardpay-validation" a nastavte zobrazovanie stĺpcov podľa Vášho želania.

TATRA BANKA CARDPAY MODULE - CHANGELOG

---------------- PrestaShop 8.x ----------------

version 1.7.14 (10/03/2023)
  + added mechanism to check latest order state in order to prevent repetitive order state in the payment validation process
  - removed "maxlength" parameter for fields - allowing submit MID with more than 4 digits

version 1.7.13 (06/08/2023)
  + initial release for PrestaShop 8.x (testing environment: PrestaShop 8.0.4)
  x fixed date bug on PHP 8.1 that could prevent module installation
  x fixed referral_uri variable bug on PHP 8.1 that prevent processing of the payment


---------------- PrestaShop 1.7.x ----------------

version 1.7.12 (09/13/2022)
  + added an option to allow cancel order by customer
  x load module BO CSS only when module BO is displayed

version 1.7.11 (07/09/2022)
  x added BO module tabs for better UX usability and experience
  x fixed minor issues

version 1.7.10 (05/09/2022)
  + added feature in order to add custom & multi-language name of the payment method in the checkout
  + added an option to choose value of the E2E parameter
  + added SQL table PREFIX_cardpay_log installation (for future features only)
  + added an option to show/hide detailed payment instructions in the checkout
  x extended payment private message for "place an order after the payment" order method
  x fixed bug when payment response not accepted VS = order reference
  x do not display module alerts when the module is no active
  x fixed missing nbProducts variable into notification page
  x normalized Hook names

version 1.7.9 (01/24/2022)
  + added an option to choose payment variable symbol type (Order ID or Order reference)
  + added displayAdminOrderMainBottom hook
  + added information & action panel about card transaction in the back-office order detail 
  + added order payment record if payment state has logable option allowed
  x fixed input variables (customer's shipping address) for signature
  x fixed missing SK & CZ translations

version 1.7.8 (10/19/2021)
  x added multi-currency support
  + added displayOrderDetail hook
  + added "Finish payment" button - the customer is now allowed to pay later from an Order detail / Guest tracking page
  + added "Cancel payment & order" button - the customer is now allowed to cancel the payment and order
  + added an option to redirect customer when the payment was not successful: 
    + for "place an order before the payment" order method - redirect into order detial page with "Finish payment" button
    + for "place an order after the payment" order method - redirect back into checkout
  + added variables for adding a marketing & affiliate codes
  + added an warning alert when friendly URLs are disabled and SSL is not available
  + added changing order state when customer cancel the payment (for "place an order before the payment" order method)
  + added "modern" e-mail templates + TWIG template for generate HTML templates
  + added Extra email variables
  + added log file to recording payment transactions for debugging purposes
  + added "repeat" controller in order to fix conflict with "payment" controller and PS_PURCHASE_MINIMUM value when calling repeat the payment

  - removed useless payment step - the customer is redirected on payment gateway directly from the checkout page

  x fixed parameters in {guest_tracking_url} template email URL
  x fixed an issue when friendly URLs were disabled 
  x revamped whole payment and redirection process
  x improved payment intro page in the checkout - added information about payment process
  x simplified of the payment execution template
  x updated notification email templates - added "Finish Payment" button
  x updated VISA and VISA Electron logo, 2021 version
  x improved module code
  x updated module documentation

version 1.7.7 (05/17/2021)
  + added an option to redirect customer back into checkout when the payment was not successful (for "place an order after the payment" order method)
  x fixed a special characters in the customer address

version 1.7.6 (03/09/2021)
  IMPORTANT UPDATE: 
  x updated release - Merchant Integration Manual; version: 2.0 used
  x fixed little typo in the function converting name of the customer
  x fixed calculating SIGN for testing environment
  + added an warning alert when friendly URLs are disabled
  + added a custom hook {hook h='displaycardpayicons'} in order to display module payment icons everywhere you want
  - removed module JS file that affected PrestaShop BO

version 1.7.5 (09/04/2020)
  - removed useless payment step for both types of payment methods
  + added Google Pay logo
  x updated module documentation

version 1.7.4 (01/03/2020)
  + added Back Office CSS and JavaScript file (displayBackOfficeHeader hook)
  + added Type goods selector
  - removed useless payment step - the customer is redirected on the payment gateway directly from the checkout page
  x payment icons redesign
  x added Apple Pay logo
  x fixed displaying "tax included" suffix (and his translation) for the price based on PrestaShop tax settings
  x updated module documentation

version 1.7.3 (11/12/2019)
  x updated release - Merchant Integration Manual; version: 1.8 used
  x fixed signature comparison in validation process by adding a new RC variable
  x fixed "tax incl." string translation
  + added selector for PrestaShop theme (on/off Material Design Icons)
  + added ECDSA verification
  + added private notes field

version 1.7.2 (11/21/2018)
  x added a price comparison on order to prevent change the order by customer while is payment processed

version 1.7.1 (12/03/2017)
  x fixed payment validation process for PrestaShop 1.7.2.x
  x fixed translation of the order private message created by the module

version 1.7.0 (13/02/2017)
  + initial release for PrestaShop 1.7.x (testing environment: PrestaShop 1.7.0.4)
  + front office redesign for PrestaShop 1.7 Classic theme
  + added Order payment status selectors
  + added editable source file for card payment logos
  x moved validation script into "response" folder
  x fixed TPAY parameter
  x improved testing mode
  x fixed currency check function
  x updated card payment logos
  x updated module documentation
  x updated "Terms and conditions of use" document

---------------- PrestaShop 1.6.x ----------------

version 1.6.19 (05/25/2022)
  x added BO module tabs for better UX usability and experience
  + added an option to show/hide detailed payment instructions in the checkout
  - removed "maxlength" parameter for fields - allowing submit MID with more than 4 digits

version 1.6.18 (05/09/2022)
  + added feature in order to add custom & multi-language name of the payment method in the checkout
  + added an option to choose value of the E2E parameter
  + added SQL table PREFIX_cardpay_log installation (for future features only)
  x extended payment private message for "place an order after the payment" order method
  x fixed bug when payment response not accepted VS = order reference
  x do not display module alerts when the module is no active
  x fixed missing nbProducts variable into notification page
  x normalized Hook names

version 1.6.17 (12/25/2021)
  + added an option to choose payment variable symbol type (Order ID or Order reference)
  + added multi-currency support
  + added displayAdminOrder hook
  + added displayOrderDetail hook
  + added order payment record if payment state has logable option allowed
  + added "Finish payment" button - the customer is now allowed to pay later from an Order detail / Guest tracking page
  + added "Cancel payment & order" button - the customer is now allowed to cancel the payment and order
  + added an option to redirect customer when the payment was not successful: 
    + for "place an order before the payment" order method - redirect into order detial page with "Finish payment" button
    + for "place an order after the payment" order method - redirect back into checkout
  + added variables for adding a marketing & affiliate codes
  + added an warning alert when friendly URLs are disabled and SSL is not available
  + added changing order state when customer cancel the payment (for "place an order before the payment" order method)
  + added Extra email variables
  + added log file to recording payment transactions for debugging purposes
  + added "repeat" controller in order to fix conflict with "payment" controller and PS_PURCHASE_MINIMUM value when calling repeat the payment

  - removed useless payment step - the customer is redirected on payment gateway directly from the checkout page

  x fixed input variables (customer's shipping address) for signature
  x fixed parameters in {guest_tracking_url} template email URL
  x fixed an issue when friendly URLs were disabled 
  x revamped whole payment and redirection process
  x improved payment intro page in the checkout - added information about payment process
  x simplified of the payment execution template
  x updated notification email templates - added "Finish Payment" button
  x updated VISA and VISA Electron logo, 2021 version
  x improved module code
  x updated module documentation

version 1.6.16 (04/26/2021)
  + added an option to redirect customer back into checkout when the payment was not successful (for "place an order after the payment" order method)

version 1.6.15 (03/09/2021)
  IMPORTANT UPDATE: 
  x fixed little typo in the function converting name of the customer
  x fixed calculating SIGN for testing environment
  + added a custom hook {hook h='displaycardpayicons'} in order to display module payment icons everywhere you want
  - removed module JS file that affected PrestaShop BO

version 1.6.14 (01/23/2021)
  x fixed card logo link in the cart
  - removed useless code

version 1.6.14 (12/27/2020)
  x IMPORTANT UPDATE: 
  x updated release - Merchant Integration Manual; version: 2.0 used
  + added Back Office CSS and JavaScript file (displayBackOfficeHeader hook)
  + added Type goods selector
  + added selector for PrestaShop theme (on/off Material Design Icons)
  + added an warning alert when friendly URLs are disabled
  x payment icons redesign
  x added Apple Pay and Google Pay logo
  x fixed displaying "tax included" suffix (and his translation) for the price based on PrestaShop tax settings
  x updated module documentation
  x fixed little typo in the function converting name of the customer

version 1.6.13 (11/12/2019)
  x updated release - Merchant Integration Manual; version: 1.8 used
  x fixed signature comparison in validation process by adding a new RC variable
  + added ECDSA verification
  + added private notes field

version 1.6.12 (11/21/2018)
  x added a price comparison on order to prevent change the order by customer while is payment processed

version 1.6.11 (12/05/2017)
  x revert Name clean function
  x updated module documentation
  x fixed translation of the order private message created by the module

version 1.6.10 (05/29/2017)
  x improved Name clean function

version 1.6.9 (03/16/2017)
  - removed CID parameter

version 1.6.8 (01/28/2017)
  + added dual payment method: Order method selector (creating an order before or after the payment)
  + added new payment statuses "Awaiting CardPay payment"
  + added Order payment status selectors to freedom in pairing module statuses with PrestaShop built-in order statuses
  x moved validation script into "response" folder
  x moved "img" and "css" folder into "views" folder
  x fixed currency check function
  x updated module documentation
  x updated "Terms and conditions of use" document
  x improved the module code

version 1.6.7 (12/30/2016)
  + added compatibility with "Advanced EU Compliance" module
  x changed CardPay logotype (requested by Tatra banka)
  x minor code changes

version 1.6.6 (11/02/2016)
  x fixed TPAY parameter
  + added responsive feature for image icons

version 1.6.5 (01/19/2016)
  x minor changes

version 1.6.4 (09/01/2015)
  x updated release - Merchant Integration Manual; version: 4.0 used
  x changed payment URL
  x fixed bug with processing of variables in validation process
  x fixed UTC timestamp
  x updated documentation
  + module now using HMAC SHA256 encoding type only
  + add TPAY, TIMESTAMP and CID parameter
  + added CMS page selector for icon destination link
  - removed fields: Mobile phone; Payment description

version 1.6.3 (05/25/2015)
  + added product detail icon position and set as default
  + added PHP version warning alert
  + added PHP comparator for different sign generator process
  x improved & unificated CSS to better working with 1.6.x themes
  x improved & fixed notification system
  x updated & unificated documentation

version 1.6.2 (09/14/2014)
  + added encoding type selector (AES256 and DES)
  + added module version info into module setting page
  + added automatic customer language detection
  + added more available interface languages: English, German, Spanish, French, Italian, Slovak, Czech, Polish and Hungarian
  + added more available payment currencies: US Dollar, Czech Koruna, British Pound, Hungarian Forint, Polish Zloty, Swiss Franc, Danish krone
  + added MOBILE_DEVICE variable
  x updated module Documentation
  - removed CS parameter
  
version 1.6.1 (04/19/2014)
  + module compatibility for PrestaShop 1.6.x
  + new module versioning containing a PrestaShop version
  x redesign module Back office for PrestaShop 1.6.x
  x updated and improved module Documentation
  - removed useless Working mode selector

---------------------

Legend:
  + added a new feature
  x fixed issue, updated feature
  - removed feature