gnu-taler-payment-for-magento

Adobe Commerce (Magento) plugin to enable payments with GNU Taler
Log | Files | Refs | README

README.md (6052B)

      1 # GNU Taler Magento Open Source Payment module
      2 This module extends Magento 2.4+ for GNU Taler payment functionality.
      3 
      4 ## Payment flow
      5 This module uses the authorize and capture payments flow integrated by Magento.
      6 When a user fills his shopping cart and proceeds to checkout, he will eventually come 
      7 to the point of choosing his payment provider,
      8 where he will be presented with the option "GNU Taler payment".
      9 ![Frontend payment method selection](images/frontend_payment_method.jpg "Frontend payment method selection")
     10 
     11 On successfully entering the needed data, which is Magento's default payment form, 
     12 the magento event "gnu_taler_payment_method_is_active" gets triggered, which is listened to in the DataAssignObserver class.
     13 This class assembles the Taler PostOrderRequest based on the user's shopping cart.
     14 
     15 As with any Magento request, it is built, transferred and sent through the, in the di.xml dependency injection logic defined,
     16 "TalerChargeCommand" command. Which routes from RequestBuilder, to TransferFactory, to the Client itself, which sends the
     17 requests via CURL.
     18 
     19 Back in the DataAssignObserver class, the received answer gets validated and with the received body (order id and token)
     20 the URL for the payment redirection gets assembled and sent to the frontend via cookies.
     21 
     22 After pressing the "Place Order"-button, the customer gets redirected to the Taler payment URL.
     23 After payment, Taler routes back to the fulfillment URL which is configured in routes.xml.
     24 
     25 Therefore, the Controller/Service/Index class gets called, which assembles the Taler inspecting order request through the 
     26 default "TalerChargeCommand" route. On successful request transfering, the validation happens in the GeneralResponseValidator
     27 and based on the result, the customer gets redirected to the success page.
     28 
     29 ### File description
     30 GNU/Taler/Controller/Service/Index.php: Fulfillment action, triggered by redirect after Taler payment  
     31 GNU/Taler/etc/config.xml: Config  
     32 GNU/Taler/etc/di.xml: Dependency Injection for extension main logic  
     33 GNU/Taler/etc/events.xml: Events to subscribe to  
     34 GNU/Taler/etc/events.xml: Configuration of used modules in extension  
     35 GNU/Taler/Gateway/Http/Client.php: Executes and transfers request with CURL  
     36 GNU/Taler/Gateway/Http/TransferFactory.php: Builds transfer factory for request to submit  
     37 GNU/Taler/Gateway/Request/RequestBuilder.php: Builds request  
     38 GNU/Taler/Gateway/Validator/GeneralResponseValidator.php: Validates and logs result from Client  
     39 GNU/Taler/Model/ConfigProvider.php: Logic to return config details to configured dependencies  
     40 GNU/Taler/Observer/DataAssignObserver.php: Logic that gets triggered by event subscription, starts order creation  
     41 GNU/Taler/composer.json: composer definition  
     42 GNU/Taler/COPYING: License declaration  
     43 GNU/Taler/README.md: Readme  
     44 GNU/Taler/registration.php: Magento registration file  
     45 
     46 ## Admin panel
     47 The whole admin panel logic happens in the .xml files located in etc/adminhtml. Basically all configurable elements shown
     48 in the admin panel, are to be configured in the system.xml.
     49 ![Admin payment method settings](images/admin_payment_method_settings.jpg "Admin payment method settings")
     50 
     51 ### File description
     52 GNU/Taler/etc/adminhtml/di.xml: Dependency Injection for adminpanel  
     53 GNU/Taler/etc/adminhtml/system.xml: Config param values shown in adminpanel  
     54 
     55 ## Frontend 
     56 The work in the frontend is primarily done in the taler_form.js-file. Everything else is mostly recommended default or configuration. 
     57 
     58 ### File description
     59 GNU/Taler/etc/frontend/di.xml: Dependency Injection for frontend; the config in this case  
     60 GNU/Taler/view/frontend/layout/checkout_index_index.xml: Adding our frontend into Magento checkout layout  
     61 GNU/Taler/view/frontend/web/js/view/payment/taler_gateway.js: Add component to payment method renderlist  
     62 GNU/Taler/view/frontend/web/js/view/payment/method-renderer/taler_form.js: To be rendered payment method  
     63 GNU/Taler/view/frontend/web/js/template/payment/form.html: Checkout form for Taler payment method  
     64 
     65 
     66 ## Installation
     67 As per Magento default, the GNU Taler Magento payment module gets installed by composer.
     68 Put the extension in %magento_installation_path%/app/code/ and execute the following lines:
     69 ```
     70 php bin/magento module:enable --clear-static-content GNU_Taler && php bin/magento setup:upgrade
     71 ```
     72 
     73 ## Configuration
     74 
     75 ### Payment methods
     76 In your admin backend, navigate to Stores -> Configuration -> Sales -> Payment methods.
     77 There you will see, in chapter "Other payment methods", the method "GNU Taler".
     78 
     79 The following parameters are available and ***must*** be configured (follow provided example values exactly):
     80 
     81 Enabled: Yes
     82 
     83 Taler Logo URL: https://taler.net/images/logo-2021.svg
     84 
     85 Backend URL: https://backend.demo.taler.net/instances/pos/private/orders
     86 
     87 Authorization token: sandbox
     88 
     89 Currency: KUDOS
     90 
     91 Payment deadline in seconds: 120
     92 
     93 ### Products
     94 It's important that the products (Adminpanel -> Catalog -> Products) have set an SKU corresponding to the product ID in the merchant backend.
     95 
     96 ## Future topics
     97 As there seems to be no information on refunds in the offical Magento docs, this has to be a case for the future.  
     98 Magento also does not include any payment backend check, like Talers /config request. For the future aswell.
     99 Lastly, currently the commerce shop's inventory currently has to be replicated in the merchant backend of Taler.
    100 This could be changed to generating the complete order in this extension.
    101 
    102 ## Links
    103 Official Adobe documentation for integrating payment systems:
    104 
    105 https://developer.adobe.com/commerce/php/development/payments-integrations/
    106 
    107 https://developer.adobe.com/commerce/php/tutorials/frontend/custom-checkout/
    108 
    109 GNU Taler documentation: https://docs.taler.net/taler-merchant-api-tutorial.html
    110 
    111 ## Supported versions
    112 As of now, tested are 2.4.4, 2.4.6, 2.4.7.  
    113 Potentially all of 2.4.* should be supported. I cannot make any statement for versions below.
    114 
    115 ## Authors and acknowledgment
    116 Author: Nic Eigel
    117 
    118 ## License
    119 GNU AFFERO GENERAL PUBLIC LICENSE, see file COPYING