pos-integration.rst (6775B)
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 2.1, 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 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 a HTTP API. Requests to private endpoints are 45 `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 `Taler merchant backend <merchant-backend-operator-manual>`. 78 79 The Taler exchange, the regulated payment service provider, will still be 80 operated separately (i.e. by Taler Operations AG in Switzerland). To simplify the 81 onboarding for merchants, the PoS terminal provider shares KYC data with the 82 exchange as part of the onboarding process. 83 84 For the integrated onboarding, the steps for the merchant are: 85 86 * Merchant onboards with PoS terminal and enables Taler support. 87 * The PoS terminal provider creates a new tenant (=instance) in the Taler 88 merchant backend via the :http:post:`management/instances` endpoint and 89 configures it (i.e. setting up contact info for notifications, bank account 90 info, etc. via the respective endpoints). This is done using 91 administrative credentials on the merchant backend. 92 * The PoS provider transmits KYC information for the new merchant to the Taler 93 exchange (this will require a new endpoint to be implemented that does 94 not yet exist, as well as an agreement between the exchange operator 95 and the PoS terminal provider, for example to include the exchange 96 operator terms of service in the onboarding of the PoS terminal provider). 97 We anticipate that this will be done by POSTing (possibly multiple times) 98 the KYC data in JSON format to an authenticated endpoint. The best 99 options for sharing access to large files, such as onboarding videos, 100 will need to be discussed. 101 * PoS is now ready to accept Taler payments. 102 103 104 105 Payments 106 -------- 107 108 New payments are made via a request to the 109 :http:post:`[/instances/$INSTANCE]/private/orders` endpoint. 110 111 This creates a new *order* in the Taler Merchant backend, identified by an 112 order ID (unique within a Taler merchant backend). An order is the 113 Taler-specific concept for a payment request with associated data and lifecycle 114 information. 115 116 The :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint can be used 117 to query the status of an order. 118 119 When an order is in the *unpaid* state, the API returns a ``taler_pay_uri``. 120 This URI should be rendered by the PoS terminal as a QR code. 121 122 Once the user's wallet scans it and successfully downloads information about 123 it, the order transitions to a **claimed** state. In this state, other 124 wallets can no longer scan the QR code (and the terminal can stop displaying it). 125 126 When the user confirms the payment and pays successfully, the order transitions 127 into the *paid* state. 128 129 There are two ways to subscribe to status updates: 130 131 * `Webhooks <merchant-webhooks>`_ 132 * Long-polling on the :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint 133 134 Refunds 135 ------- 136 137 Refunds for paid orders can be given via the 138 :http:post:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/refund` endpoint. 139 Note that refunds do not arrive automically in user's wallet: The user either needs 140 to scan the refund QR code from the ``taler_refund_uri`` field of the response to 141 accept the refund or manually trigger checking for a refund in their wallet. 142 143 Transaction History 144 ------------------- 145 146 Past orders can be listed via the :http:get:`[/instances/$INSTANCE]/private/orders` endpoint. 147 148 KYC/AML 149 ------- 150 151 When a merchant hits certain transaction thresholds or is flagged for AML 152 investigation, they may be blocked from accepting further payments and/or may 153 be blocked from receiving settlement wire transfers. 154 155 In this case, the Taler Merchant Backend will notify them via the 156 configured contact method(s) such as SMS or E-Mail. 157 158 Furthermore, the :http:get:`[/instances/$INSTANCE]/private/kyc` endpoint may be requested by the PoS terminal 159 to request information about the KYC status (per merchant bank account and 160 Taler Exchange).