README.md (4746B)
1 # Taler Gateway For Payage 2 3 ## Introduction 4 5 Welcome to the user documentation for the Payage Gateway that 6 integrates Taler as a payment option for your website. This 7 documentation will guide you through the installation, configuration, 8 and usage of the plugin. It is important to note that this is not a 9 stand-alone plugin and requires the Payage component to be installed 10 and configured on your website. For more information on Payage, please 11 visit the [Payage 12 Documentation](https://www.lesarbresdesign.info/extensions/payage) 13 14 ## Table of Contents 15 16 - [Installation](#installation) 17 - [Configuration](#configuration) 18 - [Usage](#usage) 19 - [Enabling Taler Payment](#enabling-taler-payment) 20 - [Managing Taler Settings](#managing-taler-settings) 21 - [Troubleshooting](#troubleshooting) 22 - [Frequently Asked Questions](#frequently-asked-questions) 23 24 ## Installation 25 26 First make sure you have already a version of the Payage Plugin 27 installed. If not, please follow the [Payage Installation 28 Guide](https://www.lesarbresdesign.info/extensions/payage/installation). 29 If you have already installed Payage, you can install the Taler plugin 30 simply by downloading the latest version from the [Taler Plugin 31 Releases](https://ftp.gnu.org/gnu/taler/com_payage_taler-latest.zip) 32 and installing it through the Joomla plugin manager. 33 34 ### Enabling Taler Payment 35 36 To create a new instance for a Taler Gateway, navigate to the Payage 37 component and select the "Gateway Accounts" tab. Click on the "New" 38 button to create a new gateway instance. Select "Taler" as the gateway 39 type and fill out the required fields. If you have filled out all the 40 required fields you must TEST if the Taler Backend you configured is 41 valid with the "TEST" button. If the test is successful you can "Save" 42 the gateway. 43 44 After all this, please make sure to PUBLISH the new payment gateway, as otherwise each of your Mediashop 45 products will show the next error: "No payment gateway accounts available", and not only that. You 46 won't be able to see any related information about the product itself, such as description text or image. 47 48 After publishing the payment gateway, you will see the payment button. 49 50 To see how to create a payment button inside your E-commerce app, refer to the Payage Documentation. 51 52 ## Special Currencies 53 54 The Taler Payage plugin supports all common currencies. However, if 55 you want to use a special currencies that do not have a 3 letter 56 ISO-4217 currency code, you have to add an explicit mapping to a 3 57 letter currency code: Payage is limited to 3 letter currency codes 58 while Taler supports currency codes with up to 11 letters. 59 60 To do so, clone the Git repository from [Taler Plugin 61 Releases](https://gitlab.ti.bfh.ch/leibt2/taler-joomla) and edit the 62 file "com_payage_taler/currencies.csv". There is already an example 63 for the Taler test currency "KUDOS". To add a new special currency, 64 simply add a new line following the same format of 65 "$NAME,$ABBREVIATION". Then submit a patch to the maintainers (see 66 AUTHORS) to ensure that the new currency is available in future 67 releases. The abbreviation should be some 3 letter code that is *not* 68 in ISO-4217. Note that in theory new currency codes could be added to 69 ISO-4217, so such unofficial currency codes may need to be removed in 70 the future. 71 72 ## Webhook Configuration For Refunds 73 74 To update the Payage database automatically when a refund is made, you 75 have to configure a webhook in the Taler merchant backend. To do so, 76 log into the Taler merchant backend Web interface and select the 77 "Webhooks" tab. Click on the "New" button to create a new webhook with 78 the following values: 79 80 Id: A unique name for the webhook (say "taler-payage-refund-hook") 81 Event: refund 82 Method: 'POST' 83 URL: "https://example.com/index.php?option=com_payage&task=refund" 84 Header: 'Content-Type: application/json' 85 Body: '{"refunded_amount":"{{refund_amount}}","order_id":"{{order_id}}"}' 86 87 https://tim-leibacher.ch:8443/index.php?option=com_payage&task=refund&aid=1003&tid=0 88 89 - Id: `A unique name for the webhook (say "taler-payage-refund-hook")` 90 - Event: `'refund'` 91 - Method: `'POST'` 92 - URL: `"https://example.com/index.php?option=com_payage&task=refund&aid=1000&tid=0"` 93 94 aid stands for the account id. In the "Gateway Accounts" tab you can see which id you should use 95 96 - Header: `'Content-Type: application/json'` 97 - Body: 98 `'{ 99 "order_id": "{{order_id}}" 100 }'` 101 102 103 ## Frequently Asked Questions 104 Q: How can I add my own Translations? \ 105 A: See [Taler Translations](https://docs.taler.net/taler-developer-manual.html#how-to-create-a-translation) 106 107 Q: Where do I get my own Taler Merchant Backend? \ 108 A: See [Taler Merchant Backend](https://docs.taler.net/taler-merchant-manual.html) 109 110 111 112