commit de7780bc4dfb7ffe15b46e6be3fd761c0527c828
parent b8f5204435f982bd7a9f12e78f4b64101fd08a31
Author: Florian Dold <florian@dold.me>
Date: Wed, 18 Feb 2026 15:09:35 +0100
first draft of PoS integration guide
Diffstat:
4 files changed, 183 insertions(+), 0 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -127,6 +127,8 @@ unless specified otherwise.
.. include:: merchant/any-star.rst
+.. _merchant-api-authentication:
+
--------------
Authentication
--------------
@@ -754,6 +756,7 @@ Using template
.. include:: merchant/post-templates-TEMPLATE_ID.rst
+.. _merchant-webhooks:
--------
Webhooks
diff --git a/core/merchant/post-private-orders.rst b/core/merchant/post-private-orders.rst
@@ -1,3 +1,5 @@
+.. _merchant-post-private-orders:
+
.. http:post:: [/instances/$INSTANCE]/private/orders
Create a new order that a customer can pay for.
diff --git a/orphaned/gnu-taler-with-oim-inside.md b/orphaned/gnu-taler-with-oim-inside.md
@@ -0,0 +1,25 @@
+# GNU Taler ‘with OIM Inside’
+
+## Scope of Work
+The project will develop an OIM design solution for three features of GNU Taler:
+
+* send money,
+* receive money, and
+* point-of-sale payment.
+
+This will enable users to conduct the following tasks:
+
+* Send money, using a demo currency, to another demo participant.
+* Receive money from another participant.
+* Pay for a snack in the GNU Taler store.
+
+This scoping, and the design results, will be integrated in into the FOSS documentation of GNU Taler.
+
+
+## Design Tasks
+* Two documented 'image association' focus group discussions and three individual interviews. With support of our graphic designer, preparation of a complete sketch-level draft layout and presentation of draft to Taler Systems for review.
+* Get feedback on possible sound and haptic components.
+* Prepare first iteration of clickable prototype, test it with five qualified users, document results, and review with Taler Systems again.
+* Prepare second iteration of clickable prototype, test it with five qualified users, document results and conduct final review with Taler Systems.
+
+
diff --git a/pos-integration.rst b/pos-integration.rst
@@ -0,0 +1,153 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2026 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+
+
+Taler Point of Sale Integration
+###############################
+
+This guide provides an overview of Point of Sale (PoS) terminals can integrate
+with Taler to allow payments with electronic cash from Taler Wallets.
+
+
+Architecture Overview
+---------------------
+
+* Taler wallet: App installed on customer devices (Android, iOS, others) that
+ holds Taler electronic cash (CHF, EUR, ...) in self-custody.
+* Taler exchange: Regulated payment service provider (Taler Operations AG in
+ Switzerland). Processes electronic cash withdrawals/deposits, payments
+ from wallet users and to merchants.
+* Taler merchant backend: Multi-tenant service that facilitates payments via
+ the Taler exchange. Can be self-hosted. Taler Operations AG provides `managed
+ hosting <https://my.taler-ops.ch>`__ for it.
+* Taler merchant portal: Web-based user interface for the Taler Merchant Backend
+* PoS Terminal: Third party point of sale terminal. The current document describes how
+ to integrate this PoS terminal with Taler payments.
+
+Merchant API Basics
+-------------------
+
+A Taler merchant backend offers a HTTP API. Requests to private endpoints are
+`authenticated <merchant-api-authentication>` with a bearer token in the
+``Authorization: Bearer $TOKEN`` header.
+
+Some endpoints offered by the Taler merchant backend are publicly accessible,
+as they are used by wallets for processing payments.
+
+Onboarding
+----------
+
+Option A: External Onboarding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Merchant registers on Taler Merchant Portal and configures their bank account
+* Merchant completes KYC process on Taler Merchant Portal
+* Merchant configures the PoS terminal to enable access to the Taler merchant by either:
+
+ * (a) using a base URL and API token created in the Taler merchant portal
+ * (b) using a base URL, login name, password and 2FA code
+
+* PoS is now ready to accept Taler payments
+
+In the external onboarding, the merchant has to onboard twice,
+once with the PoS provider and once with Taler as a payment method.
+
+Option B: Integrated Onboarding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the integrated onboarding, the merchant only needs to complete one
+onboarding flow with the PoS provider. While more convenient, it comes with
+more integration effort.
+
+This flow requires that the provider of the PoS terminal is operating (or
+subcontracting the operation of) a separate `Taler merchant backend <merchant-backend-operator-manual>`.
+
+The Taler exchange, the regulated payment service provider, will still be
+operated separately (i.e. by Taler Operations AG in Switzerland). To simplify the
+onboarding for merchants, the PoS terminal provider shares KYC data with the
+exchange as part of the onboarding process.
+
+For the integrated onboarding, the steps for the merchant are:
+
+* Merchant onboards with PoS terminal and enables Taler support.
+* The PoS terminal provider creates a new tenant (=instance) in the Taler
+ merchant backend via the :http:post:`management/instances` endpoint and
+ configures it (i.e. setting up contact info for notifications, bank account
+ info, etc. via the respective endpoints). This is done using
+ administrative credentials on the merchant backend.
+* The PoS provider transmits KYC information for the new merchant to the Taler
+ exchange.
+* PoS is now ready to accept Taler payments.
+
+
+Payments
+--------
+
+New payments are made via a request to the
+:http:post:`[/instances/$INSTANCE]/private/orders` endpoint.
+
+This creates a new *order* in the Taler Merchant backend, identified by an
+order ID (unique within a Taler merchant backend). An order is the
+Taler-specific concept for a payment request with associated data and lifecycle
+information.
+
+The :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint can be used
+to query the status of an order.
+
+When an order is in the *unpaid* state, the API returns a ``taler_pay_uri``.
+This URI should be rendered by the PoS terminal as a QR code.
+
+Once the user's wallet scans it and successfully downloads information about
+it, the order transitions to a **claimed** state. In this state, other
+wallets can no longer scan the QR code (and the terminal can stop displaying it).
+
+When the user confirms the payment and pays successfully, the order transitions
+into the *paid* state.
+
+There are two ways to subscribe to status updates:
+
+* `Webhooks <merchant-webhooks>`_
+* Long-polling on the :http:get:`[/instances/$INSTANCE]/private/orders/$ORDER_ID` endpoint
+
+Refunds
+-------
+
+Refunds for paid orders can be given via the
+:http:post:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/refund` endpoint.
+Note that refunds do not arrive automically in user's wallet: The user either needs
+to scan the refund QR code from the ``taler_refund_uri`` field of the response to
+accept the refund or manually trigger checking for a refund in their wallet.
+
+Transaction History
+-------------------
+
+Past orders can be listed via the :http:get:`[/instances/$INSTANCE]/private/orders` endpoint.
+
+KYC/AML
+-------
+
+When a merchant hits certain transaction thresholds or is flagged for AML
+investigation, they may be blocked from accepting further payments and/or may
+be blocked from receiving settlement wire transfers.
+
+In this case, the Taler Merchant Backend will notify them via the
+configured contact method(s) such as SMS or E-Mail.
+
+Furthermore, the :http:get:`[/instances/$INSTANCE]/private/kyc` endpoint may be requested by the PoS terminal
+to request information about the KYC status (per merchant bank account and
+Taler Exchange).
+
