pos-integration.rst (6836B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 18 19 Taler Point of Sale Integration 20 ############################### 21 22 This guide provides an overview of how Point of Sale (PoS) terminals can integrate 23 with Taler to allow payments with electronic cash from Taler Wallets. 24 25 26 Architecture Overview 27 --------------------- 28 29 * Taler wallet: App installed on customer devices (Android, iOS, others) that 30 holds Taler electronic cash (CHF, EUR, ...) in self-custody. 31 * Taler exchange: Regulated payment service provider (Taler Operations AG in 32 Switzerland). Processes electronic cash withdrawals/deposits, payments 33 from wallet users and to merchants. 34 * Taler merchant backend: Multi-tenant service that facilitates payments via 35 the Taler exchange. Can be self-hosted. Taler Operations AG provides `managed 36 hosting <https://my.taler-ops.ch>`__ for it. 37 * Taler merchant portal: Web-based user interface for the Taler Merchant Backend 38 * PoS Terminal: Third party point of sale terminal. The current document describes how 39 to integrate this PoS terminal with Taler payments. 40 41 Merchant API Basics 42 ------------------- 43 44 A Taler merchant backend offers an HTTP API. Requests to private endpoints are 45 :ref:`authenticated <merchant-api-authentication>` with a bearer token in the 46 ``Authorization: Bearer $TOKEN`` header. 47 48 Some endpoints offered by the Taler merchant backend are publicly accessible, 49 as they are used by wallets for processing payments. 50 51 Onboarding 52 ---------- 53 54 Option A: External Onboarding 55 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 56 57 * Merchant registers on Taler Merchant Portal and configures their bank account 58 * Merchant completes KYC process on Taler Merchant Portal 59 * Merchant configures the PoS terminal to enable access to the Taler merchant by either: 60 61 * (a) using a base URL and API token created in the Taler merchant portal 62 * (b) using a base URL, login name, password and 2FA code 63 64 * PoS is now ready to accept Taler payments 65 66 In the external onboarding, the merchant has to onboard twice, 67 once with the PoS provider and once with Taler as a payment method. 68 69 Option B: Integrated Onboarding 70 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 71 72 For the integrated onboarding, the merchant only needs to complete one 73 onboarding flow with the PoS provider. While more convenient, it comes with 74 more integration effort. 75 76 This flow requires that the provider of the PoS terminal is operating (or 77 subcontracting the operation of) a separate 78 :ref:`Taler merchant backend <taler-merchant-backend-operator-manual>`. 79 80 The Taler exchange, the regulated payment service provider, will still be 81 operated separately (i.e. by Taler Operations AG in Switzerland). To simplify the 82 onboarding for merchants, the PoS terminal provider shares KYC data with the 83 exchange as part of the onboarding process. 84 85 For the integrated onboarding, the steps for the merchant are: 86 87 * Merchant onboards with PoS terminal and enables Taler support. 88 * The PoS terminal provider creates a new tenant (=instance) in the Taler 89 merchant backend via the 90 :ref:`POST /management/instances <post-management-instances>` endpoint and 91 configures it (i.e. setting up contact info for notifications, bank account 92 info, etc. via the respective endpoints). This is done using 93 administrative credentials on the merchant backend. 94 * The PoS provider transmits KYC information for the new merchant to the Taler 95 exchange (this will require a new endpoint to be implemented that does 96 not yet exist, as well as an agreement between the exchange operator 97 and the PoS terminal provider, for example to include the exchange 98 operator terms of service in the onboarding of the PoS terminal provider). 99 We anticipate that this will be done by POSTing (possibly multiple times) 100 the KYC data in JSON format to an authenticated endpoint. The best 101 options for sharing access to large files, such as onboarding videos, 102 will need to be discussed. 103 * PoS is now ready to accept Taler payments. 104 105 106 107 Payments 108 -------- 109 110 New payments are made via a request to the 111 :http:post:`[/instances/$INSTANCE]/private/orders` endpoint. 112 113 This creates a new *order* in the Taler Merchant backend, identified by an 114 order ID (unique within a Taler merchant backend). An order is the 115 Taler-specific concept for a payment request with associated data and lifecycle 116 information. 117 118 The :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint can be used 119 to query the status of an order. 120 121 When an order is in the *unpaid* state, the API returns a ``taler_pay_uri``. 122 This URI should be rendered by the PoS terminal as a QR code. 123 124 Once the user's wallet scans it and successfully downloads information about 125 it, the order transitions to a **claimed** state. In this state, other 126 wallets can no longer scan the QR code (and the terminal can stop displaying it). 127 128 When the user confirms the payment and pays successfully, the order transitions 129 into the *paid* state. 130 131 There are two ways to subscribe to status updates: 132 133 * :ref:`Webhooks <merchant-webhooks>` 134 * Long-polling on the :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint 135 136 Refunds 137 ------- 138 139 Refunds for paid orders can be given via the 140 :http:post:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/refund` endpoint. 141 Note that refunds do not arrive automatically in the user's wallet: The user either needs 142 to scan the refund QR code from the ``taler_refund_uri`` field of the response to 143 accept the refund or manually trigger checking for a refund in their wallet. 144 145 Transaction History 146 ------------------- 147 148 Past orders can be listed via the :http:get:`[/instances/$INSTANCE]/private/orders` endpoint. 149 150 KYC/AML 151 ------- 152 153 When a merchant hits certain transaction thresholds or is flagged for AML 154 investigation, they may be blocked from accepting further payments and/or may 155 be blocked from receiving settlement wire transfers. 156 157 In this case, the Taler Merchant Backend will notify them via the 158 configured contact method(s) such as SMS or E-Mail. 159 160 Furthermore, the :http:get:`[/instances/$INSTANCE]/private/kyc` endpoint may be requested by the PoS terminal 161 to request information about the KYC status (per merchant bank account and 162 Taler Exchange).