taler-docs

api-merchant.rst (63020B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2014-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 Marcello Stanisci
   @author Florian Dold
   @author Christian Grothoff
   @author Priscilla Huang
   @author Martin Schanzenbach
 
 .. _merchant-api:
 
 ============================
 Merchant Backend RESTful API
 ============================
 
 ---------------
 Version History
 ---------------
 
 The currently implemented protocol version is **v32**.
 
 * The Android PoS app is currently targeting **v20**.
 * The SPA is currently targeting **vXX**.
 * taler-mdb is currently targeting **v27**.
 * anastasis is currently targeting **v27**.
 * taler-woocommerce is currently targeting **v29**.
 * taler-drupal-turnstile is currently targeting **v29**.
 * taler-drupal-commerce is currently targeting **vXX**.
 * paivana is currently targeting **v29**.
 
 **Version history:**
 
 * ``v21``: Added self-provisioning and two factor authentication
 * ``v22``: Added various defaults
 * ``v23``: Added various defaults, fields and some new filters
 * ``v24``: Make minor changes to refund semantics
 * ``v25``: adds features to group amounts internally (say to
   separate tips, taxes and revenue in reporting), endpoints
   for periodic report generation and inventory-based templates,
   new long-polling for KYC and features for templates to support
   session-based payments
 * ``v26``: adds unclaim endpoint, enhanced settlement reporting
 * ``v27``: adds various fields to a few endpoints
 * ``v28``: adds the ``/kycauth`` endpoint for wire transfer subject
   shortening during KYC Auth wire transfers and expands ``/config``.
 * ``v29``: adds ``max_pickup_duration`` to templates (for Paivana)
 * ``v30``: adds ``debit_restrictions`` to GET /exchanges (for SPA)
 * ``v31``: adds ``/private/accept-tos-early`` and related API changes
 * ``v32``: adds "force" argument for locked product deletion
 
 **Upcoming versions:**
 
 * ``vTAXES``: adds features to manage taxes
 
 **Ideas for future version:**
 
 * ``vXXX``: marker for features not yet targeted for release
 
 -----------------------
 Base URLs and Instances
 -----------------------
 
 A single merchant backend installation can host multiple merchant instances.
 This is useful when multiple businesses want to share the same payment
 infrastructure.
 
 Merchant backends have one special ``admin`` instance.  This ``admin``
 instance is used when no explicit instance is specified.  Note that using
 ``/instances/admin/$ANYTHING`` is deprecated and will result in a permanent
 redirect (HTTP status 308) to ``$ANYTHING``. a Despite its name, this instance
 must be created after the installation.
 
 Each instance (admin and others) has a base URL.  The resources under
 this base URL are divided into to categories:
 
 * Public endpoints that are exposed to the Internet
 * Private endpoints (under ``/private/*``) that are only supposed to be exposed
   to the merchant internally, and must not be exposed on the
   Internet.
 * Management endpoints (under ``/management/*``) are also private and dedicated
   to CRUD operation over instances and reset authentication settings over all
   instances. Only accessible with the admin instance authentication token.
 
 Examples:
 
 .. code-block:: none
 
    Base URL of the merchant (admin instance) at merchant-backend.example.com:
    https://merchant-backend.example.com/
 
    A private endpoint (admin instance):
    https://merchant-backend.example.com/private/orders
 
    A public endpoint (admin instance and order id "ABCD"):
    https://merchant-backend.example.com/orders/ABCD
 
    A private endpoint ("myinst" instance):
    https://merchant-backend.example.com/instances/myinst/private/orders
 
    A public endpoint ("myinst" instance and order id "ABCD"):
    https://merchant-backend.example.com/instances/myinst/orders/ABCD
 
    A private endpoint (explicit "admin" instance):
    https://merchant-backend.example.com/private/orders
 
    A public endpoint (explicit "admin" instance):
    https://merchant-backend.example.com/orders
 
    Endpoints to manage other instances (ONLY for implicit "admin" instance):
    https://merchant-backend.example.com/management/instances
    https://merchant-backend.example.com/management/instances/$ID
 
    Endpoints to manage own instance:
    https://merchant-backend.example.com/private
    https://merchant-backend.example.com/private/auth
    https://merchant-backend.example.com/instances/$ID/private
    https://merchant-backend.example.com/instances/$ID/forgot-password
    https://merchant-backend.example.com/instances/$ID/private/auth
 
    Unavailabe endpoints (will return 404):
    https://merchant-backend.example.com/instances/myinst/private/instances
 
 -----------------
 Generic Responses
 -----------------
 
 The following (error) responses are applicable to all endpoints
 unless specified otherwise.
 
 .. include:: merchant/any-star.rst
 
 .. _merchant-api-authentication:
 
 --------------
 Authentication
 --------------
 
 Each merchant instance has separate authentication settings for the private API resources
 of that instance.
 
 Currently, the ``/private/auth/`` API supports two main authentication methods in the ``InstanceAuthConfigurationMessage``:
 
 * ``external``: (@deprecated since **v20**) With this method, no checks are done by the merchant backend.
   Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
 * ``token`` (**@since v19**): With this method, the client must provide an authorization header
   that contains a bearer token  when accessing a protected endpoint in the form
   ``Authorization: Bearer secret-token:$TOKEN``.
   ``$TOKEN`` is an authentication token retrieved from the ``/private/token`` endpoint using basic authorization.
   The respective username is the instance ``$ID``, and the password the instance password (``$INSTANCE_PASSWORD``).
   A login token is commonly only valid for a limited period of time and scoped to specific permissions.
   If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a password
   using the ``taler-merchant-passwd`` command-line tool.
 * ``token`` (@deprecated since **v19**): With this method, the client must provide an authentication token in
   the format ``secret-token: $INSTANCE_PASSWORD``.
   The behaviour is then equivalent to the ``token`` method above.
   Any API may be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``.
   Notice that this behaviour is deprecated and will be phased out in favor of login tokens.
 
 For testing, the service may be started with the configuration option ``DISABLED_AUTHENTICATION = YES``
 in section ``[merchant]`` (@since **v20**).
 
 Scopes
 ^^^^^^
 
 Access tokens can be requested with a (limiting) scope. Available scopes and their associated permissions are:
 
 * ``readonly``: ``*-read`` -- Access to APIs using ``GET`` requests is always allowed.
 * ``write`` (*deprecated*): See ``all``.
 * ``all``: ``*`` -- General access to all APIs and endpoints and always refreshable. (@since **v19**)
 * ``spa``: ``*`` -- General access to all APIs and endpoints. (@since **v20**)
 * ``order-simple``: ``orders-read``, ``orders-write`` -- Allows the creation of orders and checking of payment status. (@since **v19**)
 * ``order-pos``: ``orders-read``, ``orders-write``, ``inventory-lock`` -- Same as ``order-simple`` and allows inventory locking. (@since **v19**)
 * ``order-mgmt``: ``orders-read``, ``orders-write``, ``orders-refund`` -- Same as ``order-simple`` and also allows refunding. (@since **v19**)
 * ``order-full``: ``orders-read``, ``orders-write``, ``inventory-lock``, ``orders-refund`` -- Same ``order-pos`` and ``order-mgmt`` combined. (@since **v19**)
 
 Since **v19** the scope may be suffixed with ``:refreshable``, e.g. ``order-pos:refreshable``.
 This allows the token to be refreshed at the token endpoint.
 This behaviour replaces the deprecated ``refreshable`` field in the `LoginTokenRequest`.
 
 -----------------
 Configuration API
 -----------------
 
 The configuration API exposes basic information about a merchant backend,
 such as the implemented version of the protocol and the currency used.
 
 .. include:: merchant/get-config.rst
 
 .. include:: tos.rst
 
 -------------------
 Exchange Status API
 -------------------
 
 The exchange status API exposes basic information about the exchanges
 configured for a merchant backend, in particular the acceptable
 currencies, master public keys and the status of the merchant backend's
 download of the ``/keys`` from the exchange.  This is mostly useful
 to diagnose configuration problems.
 
 .. include:: merchant/get-exchanges.rst
 
 ---------------
 Two Factor Auth
 ---------------
 
 202 Challenge Responses
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor
 authentication (MFA) is required.  In this case, the response will be a
 `ChallengeResponse`.  In these cases, the client must first request and solve
 one or more challenges before repeating the request. When repeating the
 request, they must include a list of comma-separated challenge IDs of the
 solved challenges in an ``Taler-Challenge-Ids`` HTTP header. The body must
 remain absolutely unchanged.
 
   .. note::
 
     If all allowed attempts to solve the MFA challenge(s) fail, the endpoint
     may start to return ``403 Forbidden`` until the issued challenges expire,
     preventing the request from being completed for a while.  In this case,
     repeating the request with a different body may still be allowed!
 
 .. ts:def:: ChallengeResponse
 
   // @since v21
   interface ChallengeResponse {
     // List of challenge IDs that must be solved before the
     // client may proceed.
     challenges: Challenge[];
 
     // True if **all** challenges must be solved (AND), false if
     // it is sufficient to solve one of them (OR).
     combi_and: boolean;
 
   }
 
 .. ts:def:: Challenge
 
   interface Challenge {
     // Unique identifier of the challenge to solve to run this protected
     // operation.
     challenge_id: string;
 
     // Channel of the last successful transmission of the TAN challenge.
     tan_channel: TanChannel;
 
     // Info of the last successful transmission of the TAN challenge.
     // Hint to show to the user as to where the challenge was
     // sent or what to use to solve the challenge. May not
     // contain the full address for privacy.
     tan_info: string;
 
   }
 
 Requesting challenges
 ^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-challenge-CHALLENGE_ID.rst
 
 Solving challenges
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-challenge-CHALLENGE_ID-confirm.rst
 
 ----------
 Wallet API
 ----------
 
 This section describes (public) endpoints that wallets must be able
 to interact with directly (without HTTP-based authentication). These
 endpoints are used to process payments (claiming an order, paying
 for the order, checking payment/refund status and aborting payments),
 and to process refunds (checking refund status, obtaining the refund).
 
 
 Claiming an order
 ^^^^^^^^^^^^^^^^^
 
 The first step of processing any Taler payment consists of the
 (authorized) wallet claiming the order for itself. In this process,
 the wallet provides a wallet-generated nonce that is added
 into the contract terms.  This step prevents two different
 wallets from paying for the same contract, which would be bad
 especially if the merchant only has finite stocks.
 
 A claim token can be used to ensure that the wallet claiming an
 order is actually authorized to do so. This is useful in cases
 where order IDs are predictable and malicious actors may try to
 claim orders (say in a case where stocks are limited).
 
 
 .. include:: merchant/post-orders-ORDER_ID-claim.rst
 
 .. include:: merchant/post-orders-ORDER_ID-unclaim.rst
 
 
 Making the payment
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-orders-ORDER_ID-pay.rst
 
 
 Querying payment status
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-orders-ORDER_ID.rst
 
 .. include:: merchant/get-sessions-SESSION_ID.rst
 
 
 Demonstrating payment
 ^^^^^^^^^^^^^^^^^^^^^
 
 In case a wallet has already paid for an order, this is a fast way of proving
 to the merchant that the order was already paid. The alternative would be to
 replay the original payment, but simply providing the merchant's signature
 saves bandwidth and computation time.
 
 Demonstrating payment is useful in case a digital good was made available
 only to clients with a particular session ID: if that session ID expired or
 if the user is using a different client, demonstrating payment will allow
 the user to regain access to the digital good without having to pay for it
 again.
 
 .. include:: merchant/post-orders-ORDER_ID-paid.rst
 
 
 Aborting incomplete payments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In rare cases (such as a wallet restoring from an outdated backup) it is possible
 that a wallet fails to complete a payment because it runs out of e-cash in the
 middle of the process. The abort API allows the wallet to abort the payment for
 such an incomplete payment and to regain control over the coins that were spent
 so far. Aborts are not permitted for payments that have completed.  In contrast to
 refunds, aborts do not require approval by the merchant because aborts always
 are for incomplete payments for an order and never for established contracts.
 
 
 .. _order-abort:
 .. include:: merchant/post-orders-ORDER_ID-abort.rst
 
 
 Obtaining refunds
 ^^^^^^^^^^^^^^^^^
 
 Refunds allow merchants to fully or partially restitute e-cash to a wallet,
 for example because the merchant determined that it could not actually fulfill
 the contract. Refunds must be approved by the merchant's business logic.
 
 .. include:: merchant/post-orders-ORDER_ID-refund.rst
 
 
 -------------------
 Instance management
 -------------------
 
 Instances allow one merchant backend to be shared by multiple merchants.
 Every backend must have at least one instance, typically the "admin"
 instance setup before it can be used to manage inventory or process payments.
 
 
 Setting up instances
 ^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-instances.rst
 
 .. include:: merchant/post-instances-INSTANCE-forgot-password.rst
 
 .. include:: merchant/post-management-instances.rst
 
 .. include:: merchant/post-management-instances-INSTANCE-auth.rst
 
 Access control tokens
 ^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-token.rst
 
 .. include:: merchant/get-private-tokens.rst
 
 .. include:: merchant/delete-private-tokens-SERIAL.rst
 
 .. include:: merchant/delete-private-token.rst
 
 .. include:: merchant/patch-management-instances-INSTANCE.rst
 
 
 Inspecting instances
 ^^^^^^^^^^^^^^^^^^^^
 
 .. _instances:
 .. include:: merchant/get-management-instances.rst
 
 .. include:: merchant/get-management-instances-INSTANCE.rst
 
 
 Getting statistics
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-statistics-amount-SLUG.rst
 
 .. include:: merchant/get-private-statistics-counter-SLUG.rst
 
 .. include:: merchant/get-private-statistics-report-NAME.rst
 
 
 Deleting instances
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-management-instances-INSTANCE.rst
 
 
 KYC status checks
 ^^^^^^^^^^^^^^^^^
 
 .. _merchantkycstatus:
 
 .. include:: merchant/get-private-kyc.rst
 
 .. include:: merchant/post-private-accept-tos-early.rst
 
 
 -------------
 Bank Accounts
 -------------
 
 One or more bank accounts must be associated with an instance
 so that the instance can receive payments.  Payments may be made
 into any of the active bank accounts of an instance.
 
 .. include:: merchant/post-private-accounts.rst
 
 .. include:: merchant/patch-private-accounts-H_WIRE.rst
 
 .. include:: merchant/get-private-accounts.rst
 
 .. include:: merchant/get-private-accounts-H_WIRE.rst
 
 .. include:: merchant/delete-private-accounts-H_WIRE.rst
 
 .. include:: merchant/post-private-accounts-H_WIRE-kycauth.rst
 
 
 --------------------
 Inventory management
 --------------------
 
 .. _inventory:
 
 Inventory management is an *optional* backend feature that can be used to
 manage limited stocks of products and to auto-complete product descriptions in
 contracts (such that the frontends have to do less work).  You can use the
 Taler merchant backend to process payments *without* using its inventory
 management.
 
 .. _decimal-quantity:
 
 Decimal quantities
 ^^^^^^^^^^^^^^^^^^
 
 .. ts:def:: DecimalQuantity
 
   // Fixed-point decimal string in the form "<integer>[.<fraction>]".
   // Fractional part has up to six digits.
   // "-1" is only valid for fields that explicitly allow "infinity".
   // Since protocol **v25**; used in template selection since **v25**.
   type DecimalQuantity = string;
 
 
 Managing measurement units
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-units.rst
 
 .. include:: merchant/get-private-units-UNIT.rst
 
 .. include:: merchant/post-private-units.rst
 
 .. include:: merchant/patch-private-units-UNIT.rst
 
 .. include:: merchant/delete-private-units-UNIT.rst
 
 
 Managing product categories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-categories.rst
 
 .. include:: merchant/get-private-categories-CATEGORY_ID.rst
 
 .. include:: merchant/post-private-categories.rst
 
 .. include:: merchant/patch-private-categories-CATEGORY_ID.rst
 
 .. include:: merchant/delete-private-categories-CATEGORY_ID.rst
 
 
 Managing products in the inventory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-products.rst
 
 .. include:: merchant/patch-private-products-PRODUCT_ID.rst
 
 .. include:: merchant/get-private-products.rst
 
 .. include:: merchant/get-private-products-PRODUCT_ID.rst
 
 .. include:: merchant/delete-private-products-PRODUCT_ID.rst
 
 
 
 Providing configuration data for point-of-sale terminals
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-pos.rst
 
 
 Fetching product images
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-products-IMAGE_HASH-image.rst
 
 
 
 Reserving inventory
 ^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-products-PRODUCT_ID-lock.rst
 
 
 ------------------
 Payment processing
 ------------------
 
 To process Taler payments, a merchant must first set up an order with
 the merchant backend. The order is then claimed by a wallet, and
 paid by the wallet. The merchant can check the payment status of the
 order. Once the order is paid, the merchant may (for a limited time)
 grant refunds on the order.
 
 Creating orders
 ^^^^^^^^^^^^^^^
 
 .. _post-order:
 
 .. include:: merchant/post-private-orders.rst
 
 Inspecting orders
 ^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-orders.rst
 
 .. include:: merchant/get-private-orders-ORDER_ID.rst
 
 
 .. _private-order-data-cleanup:
 
 Private order data cleanup
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Some orders may contain sensitive information that the merchant may not want
 to retain after fulfillment, such as the customer's shipping address.  By
 initially labeling these order components as forgettable, the merchant can
 later tell the backend to forget those details (without changing the hash of
 the contract!) to minimize risks from information leakage.
 
 .. include:: merchant/patch-private-orders-ORDER_ID-forget.rst
 
 .. include:: merchant/delete-private-orders-ORDER_ID.rst
 
 
 .. _merchant_refund:
 
 -----------------
 Approving Refunds
 -----------------
 
 .. include:: merchant/post-private-orders-ORDER_ID-refund.rst
 
 
 -----------------------
 Tracking Wire Transfers
 -----------------------
 
 This API is used by merchants that want to track the payments from the
 exchange to be sure that they have been paid on time. By telling the merchant
 backend about all incoming wire transfers, the backend can detect if an
 exchange failed to perform a wire transfer that was due.
 
 
 Informing the backend about incoming wire transfers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-transfers.rst
 
 
 Querying known wire transfers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-transfers.rst
 
 
 
 Querying expected wire transfers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-incoming.rst
 
 
 .. include:: merchant/get-private-incoming-ID.rst
 
 
 Deleting confirmed wire transfer
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Deleting a wire transfer can be useful in case of a data entry
 mistake. In particular, if the exchange base URL was entered
 badly, deleting the old entry and adding a correct one is a
 good idea. Note that deleting wire transfers is not possible
 if they were expected.
 
 .. include:: merchant/delete-private-transfers-TID.rst
 
 
 -----------
 OTP Devices
 -----------
 
 OTP devices can be used to allow offline merchants
 to validate that a customer made a payment.
 
 
 .. include:: merchant/post-private-otp-devices.rst
 
 
 .. include:: merchant/patch-private-otp-devices-DEVICE_ID.rst
 
 
 .. include:: merchant/get-private-otp-devices.rst
 
 .. include:: merchant/get-private-otp-devices-DEVICE_ID.rst
 
 .. include:: merchant/delete-private-otp-devices-DEVICE_ID.rst
 
 
 .. _merchant-template-api:
 
 ---------
 Templates
 ---------
 
 The template is a backend feature that is used to allow wallets to create an
 order. This is useful in cases where a store does not have Internet
 connectivity or where a Web site wants to enable payments on a purely static
 Web page (for example to collect donations). In these cases, the GNU Taler
 wallet can be used to setup an order (and then of course pay for it).
 
 Templates can describe a fixed contract (``fixed-order``), an inventory-backed
 cart where the wallet picks products and quantities (``inventory-cart``), or a
 session-based template (``paivana``). The template type controls which fields
 appear in the contract and which inputs are required during instantiation.
 
 The template itself primarily provides order details that cannot be be changed
 by the customer when the wallet creates the order.  The idea is that the user
 *may* be prompted to enter certain information, such as the amount to be paid,
 or the order summary (as a reminder to themselves or a message to the store),
 while the template provides all of the other contract details.
 
 The typical user-experience with templatates is that the user first scans a QR
 code or clicks on a taler://-URI which contains a ``pay-template`` (see `LSD
 0006 <https://lsd.gnunet.org/lsd0006/>`__). The URI specifies which values the
 user should supply, currently either nothing, the amount, the order summary or
 both.  The URI may also specify defaults or partial defaults for those
 values. After the user has supplied those values, the wallet will use the
 public template API to create the order, then fetch the order details, and
 proceed as if it had been given the respective ``pay`` URI in the first place:
 show the full contract details and allow the user to make a payment.  If the
 user chooses to aborts the payment, the wallet should give the user the
 opportunity to edit the values and create another order with different values.
 If the template does not include any values that the user is allowed to edit
 (so it is basically a fixed contract), the wallet should directly create the
 order and immediately proceed to the contract acceptance dialog.
 
 The business process for the templating API is also pretty simple. First, the
 private API is used to setup (or edit) the template, providing all of the
 contract terms that subsequently cannot be changed by the customer/wallet.
 This template data is then stored under the template ID which can be freely
 chosen and must be in URL-encoded format. The SPA should also make it easy
 for the merchant to convert the template ID into a taler://-URI and/or QR code.
 Here, the merchant must additionally specify the defaults (if any) for the
 customer-editable values. Afterwards, the merchant can print out the QR code
 for display at the store, add a link to the taler://-URI and/or embed the
 respective QR-code image into their Web page.
 
 To receive a payment confirmation, the mechant may choose to configure a
 webhook in the merchant backend on the ``pay`` action, for example to send an
 SMS to their mobile phone.  For points-of-sale without a mobile phone or
 Internet connectivity, the OTP mechanism can also be used to confirm payments.
 
 
 Adding templates
 ^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-templates.rst
 
 
 Editing templates
 ^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-templates-TEMPLATE_ID.rst
 
 
 Inspecting template
 ^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-templates.rst
 
 .. include:: merchant/get-private-templates-TEMPLATE_ID.rst
 
 
 Removing template
 ^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-templates-TEMPLATE_ID.rst
 
 
 Using template
 ^^^^^^^^^^^^^^
 
 .. include:: merchant/get-templates-TEMPLATE_ID.rst
 
 .. include:: merchant/post-templates-TEMPLATE_ID.rst
 
 .. _merchant-webhooks:
 
 --------
 Webhooks
 --------
 
 The webhook is a backend feature that is used to trigger an HTTP request
 to some business logic of the merchant in real-time whenever a specified
 type of event happens.  Depending on the type of the event, webhooks
 may include additional meta-data, such as the amount or contract paid
 by the customer. For details on setup and supported event payloads, see the
 `Merchant manual – Setting up a webhook <https://docs.taler.net/taler-merchant-manual.html#setting-up-a-webhook>`_.
 
 Each webhook is bound to an ``event_type``. The backend currently recognizes the following types, which are mirrored in the ``WebhookEventType`` enum so API clients can
 validate their payloads without guesswork:
 
 .. ts:def:: WebhookEventType
 
    enum WebhookEventType {
       ORDER_CREATED = "order_created",
       PAY = "pay",
       REFUND = "refund",
       ORDER_SETTLED = "order_settled",
       CATEGORY_ADDED = "category_added",
       CATEGORY_UPDATED = "category_updated",
       CATEGORY_DELETED = "category_deleted",
       INVENTORY_ADDED = "inventory_added",
       INVENTORY_UPDATED = "inventory_updated",
       INVENTORY_DELETED = "inventory_deleted"
    }
 
 - ``order_created``: fired whenever a new order is created and exposes the ``order_id``, contract, and owning ``instance_id``.
 - ``pay``: emitted after a payment succeeds; the payload contains the paid contract terms and ``order_id``.
 - ``refund``: triggered when a refund is approved and includes timestamp, refunded amount, and reason.
 - ``order_settled``: sent when reconciliation links a wire transfer to an order (includes ``order_id`` and ``wtid``).
 - ``category_added`` / ``category_updated`` / ``category_deleted``: cover lifecycle changes to product categories.
 - ``inventory_added`` / ``inventory_updated`` / ``inventory_deleted``: cover lifecycle changes to inventory items, including descriptive fields and stock state.
 
 For the full payloads associated with each event consult the merchant manual section linked above.
 
 
 Adding webhooks
 ^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-webhooks.rst
 
 
 Editing webhooks
 ^^^^^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-webhooks-WEBHOOK_ID.rst
 
 
 Inspecting webhook
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-webhooks.rst
 
 .. include:: merchant/get-private-webhooks-WEBHOOK_ID.rst
 
 
 Removing webhook
 ^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-webhooks-WEBHOOK_ID.rst
 
 
 -------
 Reports
 -------
 
 Reports are a backend feature that is used to send periodic
 reports to the merchant. Reports are sent using notification
 helper programs which must be configured for each merchant backend.
 
 Since protocol **v25**.
 
 Generating reports
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-reports-REPORT_ID.rst
 
 
 Scheduling periodic reports
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-reports.rst
 
 
 Editing scheduled reports
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-reports-REPORT_ID.rst
 
 
 Inspecting reporting schedules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-reports.rst
 
 .. include:: merchant/get-private-reports-REPORT_ID.rst
 
 
 Removing scheduled reports
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-reports-REPORT_ID.rst
 
 
 --------------
 Product groups
 --------------
 
 Product groups are used to manage taxes. Each product is in
 exactly one group and that group is typically used to determine
 the applicable tax rules. Products that are not assigned explicitly
 to a group are considered to be in the *default* product group.
 
 Product groups are different from categories as a product can be
 in multiple categories. Furthermore, categories are used to make
 it easier to find products in user interfaces, while product
 groups are used to make it easier to manage taxes.
 
 Since protocol **v25**.
 
 Adding groups
 ^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-groups.rst
 
 
 Editing groups
 ^^^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-groups-GROUP_ID.rst
 
 
 Inspecting groups
 ^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-groups.rst
 
 
 Removing groups
 ^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-groups-GROUP_ID.rst
 
 
 ----
 Pots
 ----
 
 Pots are a backend feature that is used for accounting. Transacted
 amounts can be assigned into pots, for example to separate out
 tips and taxes from revenue for reporting.
 
 Since protocol **v25**.
 
 Adding pots
 ^^^^^^^^^^^
 
 .. include:: merchant/post-private-pots.rst
 
 
 Editing pots
 ^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-pots-POT_ID.rst
 
 
 Inspecting pots
 ^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-pots.rst
 
 .. include:: merchant/get-private-pots-POT_ID.rst
 
 
 Removing pots
 ^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-pots-POT_ID.rst
 
 
 ----------------------------------------
 Token Families: Subscriptions, Discounts
 ----------------------------------------
 
 This API provides functionalities for the issuance, management, and revocation
 of token families. Tokens facilitate the implementation of subscriptions and
 discounts, engaging solely the merchant and the user. Each token family
 encapsulates details pertaining to its respective tokens, guiding the merchant's
 backend on the appropriate processing and handling.
 
 
 Creating token families
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-tokenfamilies.rst
 
 
 Updating token families
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
 
 
 
 Inspecting token families
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-tokenfamilies.rst
 
 .. include:: merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
 
 
 
 Deleting token families
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
 
 
 -----------------------
 Donau Charity Instances
 -----------------------
 
 A merchant instance can link one or more **Donau charity instances**.
 Each link associates the instance’s own public key with a charity registered
 at some Donau service.  These links are managed under the private API.
 
 Permissions
 ^^^^^^^^^^^
 
 * ``donau-read``  — list linked charities.
 * ``donau-write`` — add or remove charity links.
 
 Listing charity instances
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-private-donau.rst
 
 Adding a charity instance
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-donau.rst
 
 Deleting a charity instance
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/delete-private-donau-DONAU_SERIAL.rst
 
 
 ------------------
 The Contract Terms
 ------------------
 
 This section describes the overall structure of templates, orders and contract
 terms that are the foundation for Taler payments.
 
 .. _template-contract-details:
 
 Templates
 ^^^^^^^^^
 
 The template contract is like the most raw form where many choices are still
 open or deferred.
 
 
   .. ts:def:: TemplateContractDetails
 
     type TemplateContractDetails = (TemplateContractFixedOrder | TemplateContractInventoryCart | TemplateContractPaivana) & TemplateContractCommon;
 
   .. ts:def:: TemplateContractCommon
 
     interface TemplateContractCommon {
       // Template type to apply. Defaults to "fixed-order" if omitted.
       // Prescribes which interface has to be followed
       // Since protocol **v25**.
       template_type?: TemplateType;
 
       // Human-readable summary for the template.
       summary?: string;
 
       // Required currency for payments to the template.
       // This parameter is optional and should not be present
       // if "amount" is given.
       currency?: string;
 
       // The time the customer need to pay before his order will be deleted.
       // It is deleted if the customer did not pay and if the duration is over.
       pay_duration?: RelativeTime;
 
       // How long will customers have to access / read / pick-up
       // the resource they are buying? Will turn into
       // max_pickup_time in the contract.  Optional, if not given
       // the duration is forever.
       // Since protocol **v29**.
       max_pickup_duration?: RelativeTime;
 
       // Minimum age buyer must have (in years). Default is 0.
       minimum_age?: Integer;
 
       // Inventory-cart: request a tip during instantiation.
       // Since protocol **v25**.
       request_tip?: boolean;
     }
 
   .. ts:def:: TemplateType
 
     enum TemplateType {
       FIXED_ORDER = "fixed-order",
       INVENTORY_CART = "inventory-cart",
       PAIVANA = "paivana"
     }
 
   .. ts:def:: TemplateContractFixedOrder
 
     interface TemplateContractFixedOrder {
 
       // The price is imposed by the merchant and cannot be changed by the customer.
       // This parameter is optional.
       amount?: Amount;
 
     }
 
   .. ts:def:: TemplateContractInventoryCart
 
     interface TemplateContractInventoryCart {
 
       // Inventory-cart: allow any inventory item to be selected.
       // Since protocol **v25**.
       selected_all?: boolean;
 
       // Inventory-cart: only products in these categories are selectable.
       // Since protocol **v25**.
       selected_categories?: Integer[];
 
       // Inventory-cart: only these products are selectable.
       // Since protocol **v25**.
       selected_products?: string[];
 
       // Inventory-cart: require exactly one selection entry.
       // Since protocol **v25**.
       choose_one?: boolean;
 
       // Inventory-cart: backend-provided payload with selectable data.
       // Only present in ``GET /templates/$TEMPLATE_ID`` responses.
       // Since protocol **v25**.
       inventory_payload?: InventoryPayload;
    }
 
   .. ts:def:: TemplateContractPaivana
 
     interface TemplateContractPaivana {
 
       // Regular expression over URLs for which
       // this template is valid.
       // Optional, if not given all URLs are accepted.
       // Since protocol **v25**.
       website_regex?: string;
 
       // Methods to pay for the contract.
       choices: OrderChoice[];
    }
 
 .. _template-choice:
 
 Template Choices
 ^^^^^^^^^^^^^^^^
 
   The `OrderChoice` object describes a possible choice within an order. The
   choice is done by the wallet and consists of in- and outputs. In the example
   of buying an article, the merchant could present the customer with the
   choice to use a valid subscription token or pay using a gift
   voucher. Available since protocol **v21**.
 
   .. ts:def:: OrderChoice
 
     interface OrderChoice {
       // Total price for the choice. The exchange will subtract deposit
       // fees from that amount before transferring it to the merchant.
       amount: Amount;
 
       // Optional tip amount. Must match the currency of ``amount``.
       // Since protocol **v25**.
       tip?: Amount;
 
       // Human readable description of the semantics of the choice
       // within the contract to be shown to the user at payment.
       description?: string;
 
       // Map from IETF 47 language tags to localized descriptions.
       description_i18n?: { [lang_tag: string]: string };
 
       // Inputs that must be provided by the customer, if this choice is selected.
       // Defaults to empty array if not specified.
       inputs?: OrderInput[];
 
       // Outputs provided by the merchant, if this choice is selected.
       // Defaults to empty array if not specified.
       outputs?: OrderOutput[];
 
       // Maximum total deposit fee accepted by the merchant for this contract.
       // Overrides defaults of the merchant instance.
       max_fee?: Amount;
     }
 
   .. ts:def:: OrderInput
 
     // For now, only token inputs are supported.
     type OrderInput = OrderInputToken;
 
   .. ts:def:: OrderInputToken
 
     interface OrderInputToken {
 
       // Token input.
       type: "token";
 
       // Token family slug as configured in the merchant backend. Slug is unique
       // across all configured tokens of a merchant.
       token_family_slug: string;
 
       // How many units of the input are required.
       // Defaults to 1 if not specified. Output with count == 0 are ignored by
       // the merchant backend.
       count?: Integer;
 
     }
 
   .. ts:def:: OrderOutput
 
     type OrderOutput = OrderOutputToken | OrderOutputTaxReceipt;
 
   .. ts:def:: OrderOutputToken
 
     interface OrderOutputToken {
 
       // Token output.
       type: "token";
 
       // Token family slug as configured in the merchant backend. Slug is unique
       // across all configured tokens of a merchant.
       token_family_slug: string;
 
       // How many units of the output are issued by the merchant.
       // Defaults to 1 if not specified. Output with count == 0 are ignored by
       // the merchant backend.
       count?: Integer;
 
       // When should the output token be valid. Can be specified if the
       // desired validity period should be in the future (like selling
       // a subscription for the next month). Optional. If not given,
       // the validity is supposed to be "now" (time of order creation).
       valid_at?: Timestamp;
 
     }
 
   .. ts:def:: OrderOutputTaxReceipt
 
     interface OrderOutputTaxReceipt {
 
       // Tax receipt output.
       type: "tax-receipt";
 
       // Donation amount. Useful if the donation is only for
       // part of the total.
       // Optional, if not given the purchase total amount is
       // assumed to be the donation amount.
       amount?: Amount;
     }
 
 .. _contract-base-terms:
 
 Contract base terms
 ^^^^^^^^^^^^^^^^^^^
 
 These are the basic terms that are shared terms between orders and contracts
 and basically present (or optional) all the time.
 
 .. ts:def:: ContractBaseTerms
 
   interface ContractBaseTerms {
     // Human-readable description of the whole purchase.
     summary: string;
 
     // Map from IETF BCP 47 language tags to localized summaries.
     summary_i18n?: { [lang_tag: string]: string };
 
     // Unique, free-form identifier for the proposal.
     // Must be unique within a merchant instance.
     // For merchants that do not store proposals in their DB
     // before the customer paid for them, the ``order_id`` can be used
     // by the frontend to restore a proposal from the information
     // encoded in it (such as a short product identifier and timestamp).
     order_id: string;
 
     // URL where the same contract could be ordered again (if
     // available). Returned also at the public order endpoint
     // for people other than the actual buyer (hence public,
     // in case order IDs are guessable).
     public_reorder_url?: string;
 
     // URL that will show that the order was successful after
     // it has been paid for.  Optional, but either ``fulfillment_url``
     // or ``fulfillment_message`` must be specified in every
     // contract terms.
     //
     // If a non-unique fulfillment URL is used, a customer can only
     // buy the order once and will be redirected to a previous purchase
     // when trying to buy an order with the same fulfillment URL a second
     // time. This is useful for digital goods that a customer only needs
     // to buy once but should be able to repeatedly download.
     //
     // For orders where the customer is expected to be able to make
     // repeated purchases (for equivalent goods), the fulfillment URL
     // should be made unique for every order. The easiest way to do
     // this is to include a unique order ID in the fulfillment URL.
     //
     // When POSTing to the merchant, the placeholder text "${ORDER_ID}"
     // is be replaced with the actual order ID (useful if the
     // order ID is generated server-side and needs to be
     // in the URL). Note that this placeholder can only be used once.
     // Front-ends may use other means to generate a unique fulfillment URL.
     fulfillment_url?: string;
 
     // Message shown to the customer after paying for the order.
     // Either fulfillment_url or fulfillment_message must be specified.
     fulfillment_message?: string;
 
     // Map from IETF BCP 47 language tags to localized fulfillment
     // messages.
     fulfillment_message_i18n?: { [lang_tag: string]: string };
 
     // Delivery location for (all!) products.
     delivery_location?: Location;
 
     // Time indicating when the order should be delivered.
     // May be overwritten by individual products.
     delivery_date?: Timestamp;
 
     // Specifies for how long the wallet should try to get an
     // automatic refund for the purchase. If this field is
     // present, the wallet should wait for a few seconds after
     // the purchase and then automatically attempt to obtain
     // a refund.  The wallet should probe until "delay"
     // after the payment was successful (i.e. via long polling
     // or via explicit requests with exponential back-off).
     //
     // In particular, if the wallet is offline
     // at that time, it MUST repeat the request until it gets
     // one response from the merchant after the delay has expired.
     // If the refund is granted, the wallet MUST automatically
     // recover the payment.  This is used in case a merchant
     // knows that it might be unable to satisfy the contract and
     // desires for the wallet to attempt to get the refund without any
     // customer interaction.  Note that it is NOT an error if the
     // merchant does not grant a refund.
     auto_refund?: RelativeTime;
 
     // Extra data that is only interpreted by the merchant frontend.
     // Useful when the merchant needs to store extra information on a
     // contract without storing it separately in their database.
     // Must really be an Object (not a string, integer, float or array).
     extra?: Object;
 
     // Minimum age the buyer must have (in years). Default is 0.
     // This value is at least as large as the maximum over all
     // mimimum age requirements of the products in this contract.
     // It might also be set independent of any product, due to
     // legal requirements.
     minimum_age?: Integer;
 
     // Default money pot to use for this order, applies to the
     // amount remaining that was not claimed by money pots of
     // products or taxes.  Not useful to wallets, only for
     // merchant-internal accounting.  If not given, the remaining
     // account is simply not accounted for in any money pot.
     // Since **v25**.
     order_default_money_pot?: Integer;
 
     // Latest time until which the good or service specified in the
     // contract may be picked up by the customer. This is usually
     // for digital goods where the customer has a finite window
     // for downloading the resource(s).
     max_pickup_time?: Timestamp;
 
   }
 
 .. _order-details:
 
 Orders
 ^^^^^^
 
   The `Order` object represents the starting point for new `ContractTerms`.
   After validating and sanatizing all inputs, the merchant backend will add
   additional information to the order and create a new `ContractTerms` object
   that will be stored in the database.
 
   .. ts:def:: Order
 
     type Order = ContractBaseTerms & (OrderV0 | OrderV1) & OrderCommon;
 
   .. ts:def:: OrderV0
 
     interface OrderV0 {
       // Optional, defaults to 0 if not set.
       version?: 0;
 
       // Total price for the transaction, including tip. The exchange will
       // subtract deposit fees from that amount before transferring it to
       // the merchant.
       amount: Amount;
 
       // Optional tip amount. Must match the currency of ``amount``.
       // Since protocol **v25**.
       tip?: Amount;
 
       // Maximum total deposit fee accepted by the merchant for this contract.
       // Overrides defaults of the merchant instance.
       max_fee?: Amount;
     }
 
   .. ts:def:: OrderV1
 
     interface OrderV1 {
       // Version 1 order support discounts and subscriptions.
       // https://docs.taler.net/design-documents/046-mumimo-contracts.html
       // @since protocol **v21**
       version: 1;
 
       // List of contract choices that the customer can select from.
       // @since protocol **v21**
       choices: OrderChoice[];
     }
 
 
   .. ts:def:: OrderCommon
 
     interface OrderCommon {
 
       // List of products that are part of the purchase.
       products?: ProductEntry[];
 
       // After this deadline has passed, no refunds will be accepted.
       // Overrides deadline calculated from ``refund_delay`` in
       // ``PostOrderRequest``.
       // A value of "never" is not allowed.
       refund_deadline?: Timestamp;
 
       // After this deadline, the merchant won't accept payments for the contract.
       // Overrides deadline calculated from default pay delay configured in
       // merchant backend.
       // A value of "never" is not allowed.
       pay_deadline?: Timestamp;
 
       // Transfer deadline for the exchange. Must be in the deposit permissions
       // of coins used to pay for this order.
       // Overrides deadline calculated from default wire transfer delay
       // configured in merchant backend. Must be after refund deadline.
       // A value of "never" is not allowed.
       wire_transfer_deadline?: Timestamp;
 
     }
 
 .. _product-entry:
 
 Product entries
 ^^^^^^^^^^^^^^^
 
   .. ts:def:: ProductEntry
 
     type ProductEntry = (ProductSold | MinimalInventoryProduct);
 
 
 The following `MinimalInventoryProduct` can be provided if the parts of the
 order are inventory-based, that is if the `PostOrderRequest` uses
 ``inventory_products``. For such products, which must be in the backend's
 inventory, the backend can automatically fill in the amount and other details
 about the product that are known to it from its ``products`` table.  Note that
 the ``inventory_products`` will be appended to the list of ``products`` that
 the frontend already put into the ``order``.  So if the frontend can sell
 additional non-inventory products together with ``inventory_products``.  Note
 that the backend will NOT update the ``amount`` of the ``order``, so the
 frontend must already have calculated the total price --- including the
 ``inventory_products``.
 
   .. ts:def:: MinimalInventoryProduct
 
     // Note that if the frontend does give details beyond these,
     // it will override those details (including price or taxes)
     // that the backend would otherwise fill in via the inventory.
     interface MinimalInventoryProduct {
 
       // Which product is requested (here mandatory!).
       product_id: string;
 
       // Legacy integer quantity.
       // Deprecated since **v25**;
       // defaults to 1 if both ``quantity`` and ``unit_quantity`` are absent.
       quantity?: Integer;
 
       // Preferred quantity string using "<integer>[.<fraction>]" syntax.
       // @since **v25**;
       unit_quantity?: string
 
       // Money pot to use for this product, overrides value from
       // the inventory if given.
       // Since **v25**.
       product_money_pot?: Integer;
 
     }
 
 Clients must supply either ``quantity`` or ``unit_quantity`` when referencing
 inventory products. If both are missing the backend assumes a quantity of
 one. ``unit_quantity`` follows the same decimal-string rules as
 ``unit_total_stock``.
 
 
 .. _contract-token-family:
 
 Contract token family
 ^^^^^^^^^^^^^^^^^^^^^
 
 The contract token family provides additional meta-data about
 input and output tokens associated with a particular choice of
 payment.
 
 .. ts:def:: ContractTokenFamily
 
   interface ContractTokenFamily {
     // Human-readable name of the token family.
     name: string;
 
     // Human-readable description of the semantics of
     // this token family (for display).
     description: string;
 
     // Map from IETF BCP 47 language tags to localized descriptions.
     description_i18n?: { [lang_tag: string]: string };
 
     // Public keys used to validate tokens issued by this token family.
     keys: TokenIssuePublicKey[];
 
     // Kind-specific information of the token
     details: ContractTokenDetails;
 
     // Must a wallet understand this token type to
     // process contracts that use or issue it?
     critical: boolean;
   };
 
 .. ts:def:: TokenIssuePublicKey
 
   type TokenIssuePublicKey =
     | TokenIssueRsaPublicKey
     | TokenIssueCsPublicKey;
 
 .. ts:def:: TokenIssueRsaPublicKey
 
   interface TokenIssueRsaPublicKey {
     cipher: "RSA";
 
     // RSA public key.
     rsa_pub: RsaPublicKey;
 
     // Start time of this key's signatures validity period.
     signature_validity_start: Timestamp;
 
     // End time of this key's signatures validity period.
     signature_validity_end: Timestamp;
 
   }
 
 .. ts:def:: TokenIssueCsPublicKey
 
   interface TokenIssueCsPublicKey {
     cipher: "CS";
 
     // CS public key.
     cs_pub: Cs25519Point;
 
     // Start time of this key's signatures validity period.
     signature_validity_start: Timestamp;
 
     // End time of this key's signatures validity period.
     signature_validity_end: Timestamp;
 
   }
 
 .. ts:def:: ContractTokenDetails
 
   type ContractTokenDetails =
     | ContractSubscriptionTokenDetails
     | ContractDiscountTokenDetails;
 
 .. ts:def:: ContractSubscriptionTokenDetails
 
   interface ContractSubscriptionTokenDetails {
     class: "subscription";
 
     // Array of domain names where this subscription
     // can be safely used (e.g. the issuer warrants that
     // these sites will re-issue tokens of this type
     // if the respective contract says so).  May contain
     // "*" for any domain or subdomain.
     trusted_domains: string[];
   };
 
 .. ts:def:: ContractDiscountTokenDetails
 
   interface ContractDiscountTokenDetails {
     class: "discount";
 
     // Array of domain names where this discount token
     // is intended to be used.  May contain "*" for any
     // domain or subdomain.  Users should be warned about
     // sites proposing to consume discount tokens of this
     // type that are not in this list that the merchant
     // is accepting a coupon from a competitor and thus
     // may be attaching different semantics (like get 20%
     // discount for my competitors 30% discount token).
     expected_domains: string[];
   };
 
 
 .. _proto-contract-terms:
 
 Proto contract terms
 ^^^^^^^^^^^^^^^^^^^^
 
 The proto-contract terms are the proposed contract that a merchant
 is about to present to a wallet, but that lacks the wallet's *nonce*
 and is thus not yet buyer-specific.
 
 
 
 .. ts:def:: ProtoContractTerms
 
   type ProtoContractTerms = ContractBaseTerms & (ContractTermsV0 | ContractTermsV1) & ContractTermsCommon;
 
 
 .. ts:def:: ContractTermsV0
 
   interface ContractTermsV0 {
     // Defaults to version 0.
     version?: 0;
 
     // Total price for the transaction, including tip.
     // The exchange will subtract deposit fees from that amount
     // before transferring it to the merchant.
     amount: Amount;
 
     // Optional tip amount. Must match the currency of ``amount``.
     // Since protocol **v25**.
     tip?: Amount;
 
     // Maximum total deposit fee accepted by the merchant for this contract.
     // Overrides defaults of the merchant instance.
     max_fee: Amount;
   }
 
 .. ts:def:: ContractTermsV1
 
   interface ContractTermsV1 {
     // Version 1 supports the ``choices`` array, see
     // https://docs.taler.net/design-documents/046-mumimo-contracts.html.
     // @since protocol **v21**
     version: 1;
 
     // List of contract choices that the customer can select from.
     // @since protocol **v21**
     choices: ContractChoice[];
 
     // Map of storing metadata and issue keys of
     // token families referenced in this contract.
     // @since protocol **v21**
     token_families: { [token_family_slug: string]: ContractTokenFamily };
   }
 
 .. ts:def:: ContractTermsCommon
 
   interface ContractTermsCommon {
 
     // Time when this contract was generated.
     timestamp: Timestamp;
 
     // After this deadline has passed, no refunds will be accepted.
     refund_deadline: Timestamp;
 
     // After this deadline, the merchant won't accept payments for the contract.
     pay_deadline: Timestamp;
 
     // Transfer deadline for the exchange.  Must be in the
     // deposit permissions of coins used to pay for this order.
     wire_transfer_deadline: Timestamp;
 
     // Merchant's public key used to sign this proposal; this information
     // is typically added by the backend. Note that this can be an ephemeral key.
     merchant_pub: EddsaPublicKey;
 
     // Base URL of the (public!) merchant backend API.
     // Must be an absolute URL that ends with a slash.
     merchant_base_url: string;
 
     // More info about the merchant, see below.
     merchant: Merchant;
 
     // List of products that are part of the purchase (see `ProductSold`).
     products: ProductSold[];
 
     // The hash of the merchant instance's wire details.
     h_wire: HashCode;
 
     // Wire transfer method identifier for the wire method associated with ``h_wire``.
     // The wallet may only select exchanges via a matching auditor if the
     // exchange also supports this wire method.
     // The wire transfer fees must be added based on this wire transfer method.
     wire_method: string;
 
     // Exchanges that the merchant accepts even if it does not accept any auditors that audit them.
     exchanges: Exchange[];
 
   }
 
 .. ts:def:: ContractChoice
 
   interface ContractChoice {
     // Price to be paid for this choice. Could be 0.
     // The price is in addition to other instruments,
     // such as rations and tokens.
     // The exchange will subtract deposit fees from that amount
     // before transferring it to the merchant.
     amount: Amount;
 
     // Optional tip amount. Must match the currency of ``amount``.
     // Since protocol **v25**.
     tip?: Amount;
 
     // Human readable description of the semantics of the choice
     // within the contract to be shown to the user at payment.
     description?: string;
 
     // Map from IETF 47 language tags to localized descriptions.
     description_i18n?: { [lang_tag: string]: string };
 
     // List of inputs the wallet must provision (all of them) to
     // satisfy the conditions for the contract.
     inputs: ContractInput[];
 
     // List of outputs the merchant promises to yield (all of them)
     // once the contract is paid.
     outputs: ContractOutput[];
 
     // Maximum total deposit fee accepted by the merchant for this contract.
     max_fee: Amount;
   }
 
 .. ts:def:: ContractInput
 
   // For now, only tokens are supported as inputs.
   type ContractInput = ContractInputToken;
 
 .. ts:def:: ContractInputToken
 
   interface ContractInputToken {
     type: "token";
 
     // Slug of the token family in the
     // ``token_families`` map on the order.
     token_family_slug: string;
 
     // Number of tokens of this type required.
     // Defaults to one if the field is not provided.
     count?: Integer;
   };
 
 .. ts:def:: ContractOutput
 
   // For now, only tokens are supported as outputs.
   type ContractOutput = ContractOutputToken | ContractOutputTaxReceipt;
 
 .. ts:def:: ContractOutputToken
 
   interface ContractOutputToken {
     type: "token";
 
     // Slug of the token family in the
     // 'token_families' map on the top-level.
     token_family_slug: string;
 
     // Number of tokens to be issued.
     // Defaults to one if the field is not provided.
     count?: Integer;
 
     // When should the output token be valid. Can be specified if the
     // desired validity period should be in the future (like selling
     // a subscription for the next month). Optional. If not given,
     // the validity is supposed to be "now" (time of order creation).
     valid_at?: Timestamp;
 
     // Index of the public key for this output token
     // in the `ContractTokenFamily` ``keys`` array.
     key_index: Integer;
 
   }
 
 .. ts:def:: ContractOutputTaxReceipt
 
   interface ContractOutputTaxReceipt {
 
     // Tax receipt output.
     type: "tax-receipt";
 
     // Array of base URLs of donation authorities that can be
     // used to issue the tax receipts. The client must select one.
     donau_urls: string[];
 
     // Total amount that will be on the tax receipt.
     amount: Amount;
 
   }
 
 
 Product listing
 ^^^^^^^^^^^^^^^
 
 The `ProductSold` object describes a product and the quantity
 being purchased from the merchant as well as possibly the price
 and applicable taxes.
 It has the following structure:
 
 .. ts:def:: ProductSold
 
   interface ProductSold {
 
     // Merchant-internal identifier for the product.
     product_id?: string;
 
     // Name of the product.
     // Since API version **v20**.  Optional only for
     // backwards-compatibility, should be considered mandatory
     // moving forward!
     product_name?: string;
 
     // Human-readable product description.
     description: string;
 
     // Map from IETF BCP 47 language tags to localized descriptions.
     description_i18n?: { [lang_tag: string]: string };
 
     // Legacy integer portion of the quantity to deliver defaults to 1 if not specified.
     quantity?: Integer;
 
     // Preferred quantity string using "<integer>[.<fraction>]" syntax with up to six fractional digits.
     unit_quantity?: string;
 
     // Unit in which the product is measured (liters, kilograms, packages, etc.).
     unit?: string;
 
     // The price of the product;
     // Deprecated since **v25**;
     // this is the total price
     // for ``quantity`` times ``unit`` of this product.
     price?: Amount;
 
     // Price of ``unit_quantity`` units of the product in various currencies.
     // Zero or absent implies that the product is not sold
     // separately.
     // Since API version **v25**.
     prices?: Amount[];
 
     // True if the ``prices`` given are the net price,
     // false if they are the gross price.  Note that even ``prices`` are the
     // gross price, ``taxes`` may be missing if the merchant configured
     // gross ``prices`` but did not configure any ``taxes``.
     // Similarly, the merchant may have configured net ``prices``
     // for products but deals with taxes on a per-order basis. Thus, it
     // may not always be possible to compute the gross price from the net
     // price for an individual product, necessitating this flag.
     // Since protocol **vTAXES**.
     prices_are_net: boolean;
 
     // An optional base64-encoded product image.
     image?: ImageDataUrl;
 
     // A list of taxes paid by the merchant for this product. Can be empty.
     // Will likely change soon!
     taxes?: Tax[];
 
     // Time indicating when this product should be delivered.
     delivery_date?: Timestamp;
 
     // Money pot to use for this product, overrides value from
     // the inventory if given.  Not useful to wallets, only for
     // merchant-internal accounting.
     // Since **v25**.
     product_money_pot?: Integer;
 
   }
 
 .. ts:def:: Tax
 
   interface Tax {
     // The name of the tax.
     name: string;
 
     // Amount paid in tax.
     tax: Amount;
   }
 
 .. ts:def:: Merchant
 
   interface Merchant {
     // The merchant's legal name of business.
     name: string;
 
     // Email address for contacting the merchant.
     email?: string;
 
     // Label for a location with the business address of the merchant.
     website?: string;
 
     // An optional base64-encoded product image.
     logo?: ImageDataUrl;
 
     // Label for a location with the business address of the merchant.
     address?: Location;
 
     // Label for a location that denotes the jurisdiction for disputes.
     // Some of the typical fields for a location (such as a street address) may be absent.
     jurisdiction?: Location;
   }
 
 
 .. ts:def:: Location
 
   // Delivery location, loosely modeled as a subset of
   // ISO20022's PostalAddress25.
   interface Location {
     // Nation with its own government.
     country?: string;
 
     // Identifies a subdivision of a country such as state, region, county.
     country_subdivision?: string;
 
     // Identifies a subdivision within a country sub-division.
     district?: string;
 
     // Name of a built-up area, with defined boundaries, and a local government.
     town?: string;
 
     // Specific location name within the town.
     town_location?: string;
 
     // Identifier consisting of a group of letters and/or numbers that
     // is added to a postal address to assist the sorting of mail.
     post_code?: string;
 
     // Name of a street or thoroughfare.
     street?: string;
 
     // Name of the building or house.
     building_name?: string;
 
     // Number that identifies the position of a building on a street.
     building_number?: string;
 
     // Free-form address lines, should not exceed 7 elements.
     address_lines?: string[];
   }
 
 
 Exchanges
 ^^^^^^^^^
 
 The wallet must select an exchange that either the merchant accepts by
 listing it in the exchanges array.
 
 .. ts:def:: Exchange
 
   interface Exchange {
     // The exchange's base URL.
     url: string;
 
     // How much would the merchant like to use this exchange.
     // The wallet should use a suitable exchange with high
     // priority. The following priority values are used, but
     // it should be noted that they are NOT in any way normative.
     //
     // 0: likely it will not work (recently seen with account
     //    restriction that would be bad for this merchant)
     // 512: merchant does not know, might be down (merchant
     //    did not yet get /wire response).
     // 1024: good choice (recently confirmed working)
     priority: Integer;
 
     // Master public key of the exchange.
     master_pub: EddsaPublicKey;
 
     // Maximum amount that the merchant could be paid
     // using this exchange (due to legal limits).
     // New in protocol **v17**.
     // Optional, no limit if missing.
     max_contribution?: Amount;
   }
 
 In addition to the fields described above,
 each object (from ``ContractTerms`` down)
 can mark certain fields as "forgettable" by listing the names of those fields
 in a special peer field ``_forgettable``.
 (See :ref:`Private order data cleanup <private-order-data-cleanup>`.)
 
 
 .. _contract-terms:
 
 Final contract terms
 ^^^^^^^^^^^^^^^^^^^^
 
 The contract terms are the final object that is signed by both
 parties to finalize a purchase. It must have the following structure:
 
 .. ts:def:: ContractTerms
 
   type ContractTerms = ProtoContractTerms & ContractTermsNonce;
 
 .. ts:def:: ContractTermsNonce
 
   interface ContractTermsNonce {
 
     // Nonce generated by the wallet and echoed by the merchant
     // in this field when the order is claimed and converted
     // into a contract that is bound to a wallet.
     nonce: EddsaPublicKey;
   }