Taler Point of Sale Integration

6. Taler Point of Sale Integration#

This guide provides an overview of how Point of Sale (PoS) terminals can integrate with Taler to allow payments with electronic cash from Taler Wallets.

6.1. 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 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.

6.2. Merchant API Basics#

A Taler merchant backend offers an HTTP API. Requests to private endpoints are authenticated 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.

6.3. Onboarding#

6.3.1. 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:

      1. using a base URL and API token created in the Taler merchant portal

      1. 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.

6.3.2. 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.

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 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 (this will require a new endpoint to be implemented that does not yet exist, as well as an agreement between the exchange operator and the PoS terminal provider, for example to include the exchange operator terms of service in the onboarding of the PoS terminal provider). We anticipate that this will be done by POSTing (possibly multiple times) the KYC data in JSON format to an authenticated endpoint. The best options for sharing access to large files, such as onboarding videos, will need to be discussed.

  • PoS is now ready to accept Taler payments.

6.4. Payments#

New payments are made via a request to the 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 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:

6.5. Refunds#

Refunds for paid orders can be given via the POST [/instances/$INSTANCE]/private/orders/$ORDER_ID/refund endpoint. Note that refunds do not arrive automatically in the 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.

6.6. Transaction History#

Past orders can be listed via the GET [/instances/$INSTANCE]/private/orders endpoint.

6.7. 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 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).