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