taler-docs

api-merchant.rst (85558B)

---

 ..
   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 3.0, 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 **v44**.
 
 * 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 :http:get:`/config </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
 * ``v33``: adds ``build_version`` to :http:get:`/config </config>` and
   ``max_age_s`` to ``[/instances/$INSTANCE]/private/orders``, deprecating
   the ``max_age`` query parameter of that endpoint
 * ``v34``: adds ``editable_amount`` to the choices of a Paivana template
   together with the ``choice_amounts`` request field to instantiate them,
   and ``min_amount``/``max_amount`` to bound client-chosen amounts for
   templates of any type
 * ``v35``: adds ``exchange_payto_uri`` to
   :http:get:`[/instances/$INSTANCE]/private/transfers`,
   passing on the exchange account reported by exchange protocol **v39**
 * ``v36``: allows token families with indefinite validity
 * ``v37``: adds expiration filtering to the private order history
 * ``v38``: adds reporting and repair of an order's wired status
 * ``v39``: returns a login token after a successful password reset
 * ``v40``: requires the current password when changing merchant credentials
 * ``v41``: returns merchant details and compatible exchange candidates for
   wallet templates
 * ``v42``: adds the additive ``amount_external`` field for orders settled
   partly outside of Taler, the ``/private/orders/$ORDER_ID/collect`` endpoint
   for completing zero-Taler orders without a wallet, the
   ``/private/orders/$ORDER_ID/refund-external`` endpoint for recording
   externally settled refunds, and exposes both through order status
   (see :doc:`DD 96 </design-documents/096-partial-payments>`)
 * ``v43``: adds ECDSA and EdDSA challenge-based payment confirmations.
   The OTP-device API generates signing keys and exposes the public key.
   Order creation and template instantiation accept a ``challenge``; after
   successful payment, the backend returns its signature in ``pos_confirmation``
   (see :doc:`DD 97 </design-documents/097-challenge-confirmations>`).
   Also adds token fountain management and wallet APIs for retrieving grants
   and withdrawing blind-signed promotional tokens without creating an order
   (see :doc:`DD 98 </design-documents/098-token-fountains>`)
 * ``v44``: adds unauthenticated :http:get:`[/instances/$INSTANCE]/units`
   to retrieve all active measurement units for one merchant instance,
   including built-in units with instance overrides and custom units.
   Also adds ``limit``/``offset`` pagination to
   :http:get:`[/instances/$INSTANCE]/private/fountains`, using the new
   ``fountain_serial`` response field as an exclusive cursor
 
 **Upcoming versions:**
 
 * ``vTAXES``: adds features to manage taxes
 * ``vDonauReceipts``: returns donation receipts from ``/pay`` in the new
   ``donau_sigs`` field instead of inside ``token_sigs`` (breaking for orders
   with a donation receipt output), answers a Donau failure after a
   successful payment with a 502 that carries the payment confirmation, and
   refuses to replay ``/pay`` after a refund
 
 **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``. 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 the following 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
 
 .. _merchant-session-id:
 
 -----------
 Session IDs
 -----------
 
 Payments can be bound to a *session*, which is identified by a session ID.
 Session IDs are chosen by the merchant's frontend (or by the client device,
 as is the case for the Paivana IDs given to
 :http:post:`[/instances/$INSTANCE]/templates/$TEMPLATE_ID`); the backend
 merely stores them and uses them to match a payment against the session it
 was made for.
 
 .. ts:def:: SessionID
 
   // Identifier of the session a payment is bound to.  Like a `Slug`,
   // a session ID must only use ASCII alphanumeric characters
   // ("A-Z", "a-z", "0-9") and the punctuation characters "-", ".",
   // "_", ":" and "~", and must not be "." or "..".  Unlike a slug, a
   // session ID may also contain "=" and may be empty.
   // Session IDs are case-sensitive.
   type SessionID = string;
 
 A session ID is thus *not* a slug.  It additionally permits ``=`` because
 session IDs are frequently base64-encoded identifiers, which may end in
 padding.  And it may be empty: the empty session ID means that a payment is
 not bound to any session.  Clients must expect to encounter it, as the
 backend itself puts an empty session ID into the ``taler://pay/`` URI of an
 order that has no session (the session is the last path component of that
 URI and thus cannot simply be omitted), and wallets send back what they were
 given.  Endpoints for which only an actual session makes sense say so
 explicitly and reject the empty session ID.
 
 -----------------
 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.
   A login token that is unknown or has expired is rejected with a ``401 Unauthorized``
   and ``TALER_EC_GENERIC_TOKEN_UNKNOWN`` or ``TALER_EC_GENERIC_TOKEN_EXPIRED`` respectively.
   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.
   The bearer token is only interpreted as the instance password if it is not a well-formed login token.
   The backend refuses the instance password as a bearer token if the instance has a usable MFA channel
   (a validated e-mail address with ``HELPER_EMAIL`` configured, or a validated phone number
   with ``HELPER_SMS`` configured), as it would bypass the MFA required by ``/private/token``,
   and always if the backend runs with ``STRICT_PROTOCOL_V19 = YES``.
   Such requests fail with a ``401 Unauthorized`` and ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
   Clients must then obtain a login token from ``/private/token`` using basic authorization;
   for instances with MFA, that request requires solving MFA challenges.
 
 For testing, the service may be started with the configuration option ``DISABLE_AUTHENTICATION = YES``
 in section ``[merchant]`` (@since **v20**).
 
 .. _merchant-api-scopes:
 
 Scopes and permissions
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Authorization in the merchant backend is expressed with *permissions*.  Every
 endpoint that requires authorization requires exactly one permission, which is
 stated as **Required permission** in the documentation of that endpoint.
 Permission names have the form ``$RESOURCE-$ACTION``, where ``$ACTION`` is
 usually ``read`` (for operations that only inspect state) or ``write`` (for
 operations that change it).
 
 Clients do not request individual permissions.  Instead, an access token is
 issued for a *scope*, which is a fixed, named set of permissions.  A request is
 authorized if the permission required by the endpoint is covered by the scope
 of the access token that was used.
 
 Permissions
 """""""""""
 
 The following permissions exist:
 
 .. list-table::
   :widths: 25 75
   :header-rows: 1
 
   * - Permission
     - Grants access to
   * - ``accounts-read``
     - Listing and inspecting the bank accounts of the instance, and starting
       KYC authentication for one of them.
   * - ``accounts-write``
     - Adding, modifying and deleting bank accounts of the instance, and
       accepting the terms of service of an exchange ahead of time.
   * - ``auth-write``
     - Changing the authentication settings of the instance itself
       (via the instance's own ``/private/auth`` endpoint).
   * - ``categories-read``
     - Listing and inspecting product categories.
   * - ``categories-write``
     - Creating, modifying and deleting product categories.
   * - ``donau-read``
     - Listing the linked Donau charity instances.
   * - ``donau-write``
     - Adding and removing Donau charity instance links.
   * - ``fountains-read``
     - Listing and inspecting token fountains.  Since **v43**.
   * - ``fountains-write``
     - Creating, modifying and deleting token fountains.
       Since **v43**.
   * - ``groups-read``
     - Listing product groups.
   * - ``groups-write``
     - Creating, modifying and deleting product groups.
   * - ``instances-auth-write``
     - Changing the authentication settings of *any* instance via the
       ``/management/`` API.  Only the ``admin`` instance can hold this
       permission in a useful way.
   * - ``instances-kyc-read``
     - Querying the KYC status of *any* instance via the ``/management/`` API.
   * - ``instances-read``
     - Reading the configuration of the instance itself.
   * - ``instances-write``
     - Creating, inspecting, modifying and deleting instances.  Note that this
       permission is required for *all* operations on the ``/management/``
       instance API, including the ``GET`` operations that merely list or
       inspect instances, as well as for modifying or deleting the instance
       itself via its own private API.
   * - ``kyc-read``
     - Querying the KYC status of the instance itself.
   * - ``orders-read``
     - Listing orders and checking their payment, refund and wire transfer
       status.
   * - ``orders-write``
     - Creating orders, forgetting parts of a contract, collecting zero-amount
       orders and deleting orders.
   * - ``orders-refund``
     - Granting refunds and recording externally settled refunds.
   * - ``otp-devices-read``
     - Listing and inspecting one-time-password (OTP) devices.
   * - ``otp-devices-write``
     - Creating, modifying and deleting OTP devices.
   * - ``pos-read``
     - Downloading the full point-of-sale configuration
       (:http:get:`[/instances/$INSTANCE]/private/pos`).
   * - ``pots-read``
     - Listing and inspecting money pots.
   * - ``pots-write``
     - Creating, modifying and deleting money pots.
   * - ``products-read``
     - Listing and inspecting products in the inventory.
   * - ``products-write``
     - Adding, modifying and deleting products in the inventory.
   * - ``products-lock``
     - Locking products in the inventory
       (:http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`).
   * - ``reports-read``
     - Listing and inspecting reports.
   * - ``reports-write``
     - Creating, modifying and deleting reports.
   * - ``statistics-read``
     - Reading counter, amount and transaction statistics.
   * - ``templates-read``
     - Listing and inspecting order templates.
   * - ``templates-write``
     - Creating, modifying and deleting order templates.
   * - ``tokenfamilies-read``
     - Listing and inspecting token families.
   * - ``tokenfamilies-write``
     - Creating, modifying and deleting token families.
   * - ``tokens-read``
     - Listing the access tokens that were issued for the instance.
   * - ``tokens-write``
     - Revoking access tokens of the instance by serial.
   * - ``token-refresh``
     - Obtaining a new access token from
       :http:post:`[/instances/$INSTANCE]/private/token` using an existing
       access token.  This permission is special: it is *not* part of any
       scope's permission set and is not implied by ``*``.  It is granted
       exactly if the access token used is refreshable (see below).
   * - ``transfers-read``
     - Listing expected and actual wire transfers, including incoming
       transfers.
   * - ``transfers-write``
     - Informing the backend about wire transfers and deleting such records.
   * - ``units-read``
     - Listing and inspecting measurement units.
   * - ``units-write``
     - Creating, modifying and deleting measurement units.
   * - ``webhooks-read``
     - Listing and inspecting webhooks.
   * - ``webhooks-write``
     - Creating, modifying and deleting webhooks.
 
 Endpoints of the wallet-facing (public) API, such as those used to claim, pay
 for or abort an order, require no permission at all and are documented as
 "**Required permission:** none".
 
 Scopes
 """"""
 
 Access tokens can be requested with a (limiting) scope.  The available scopes
 and the permissions they grant are:
 
 .. list-table::
   :widths: 15 45 40
   :header-rows: 1
 
   * - Scope
     - Permissions
     - Remarks
   * - ``readonly``
     - ``*-read``
     - Every permission ending in ``-read``.  Note that this does *not* include
       the ``/management/`` instance API, which requires ``instances-write``
       even for ``GET`` requests.
   * - ``all``
     - ``*``
     - Every permission.  Tokens with this scope are always refreshable.
       @since **v19**
   * - ``write``
     - ``*``
     - @deprecated since **v19**, identical to ``all``.
   * - ``spa``
     - ``*``
     - Every permission; used by the merchant backoffice SPA.  Unlike ``all``,
       this scope is not implicitly refreshable.  @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``, ``pos-read``, ``products-lock``,
       ``products-read``, ``orders-refund``
     - Same as ``order-simple`` and allows inventory locking (@since **v19**),
       ``products-read`` since **v32**, and granting refunds.
   * - ``order-mgmt``
     - ``orders-read``, ``orders-write``, ``pos-read``, ``orders-refund``
     - Same as ``order-simple``, plus reading the point-of-sale configuration
       and granting refunds.  @since **v19**
   * - ``order-full``
     - ``orders-read``, ``orders-write``, ``pos-read``, ``products-lock``,
       ``orders-refund``
     - ``order-pos`` and ``order-mgmt`` combined.  @since **v19**
 
 .. note::
 
    The ``products-lock`` permission granted by ``order-pos`` and ``order-full``
    is only required for explicitly locking products via
    :http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`.
    Creating an order (which locks inventory as a side effect) requires only
    ``orders-write``.
 
 .. ts:def:: TokenScope
 
   // Scope of an access token.  Since **v19**, the scope may be
   // suffixed with ":refreshable" (see below), for example
   // "order-pos:refreshable".  "write" is deprecated since **v19**
   // and is equivalent to "all".
   type TokenScope = "readonly" | "all" | "spa" | "order-simple" | "order-pos" | "order-mgmt" | "order-full" | "write";
 
 Matching rules
 """"""""""""""
 
 Given the permission ``$P`` required by an endpoint and the permission set of
 the scope of the access token used, access is granted if any of the following
 holds:
 
 * the scope contains ``*``;
 * the scope contains ``*-read`` and ``$P`` ends in ``-read``;
 * the scope contains ``*-write`` and ``$P`` ends in ``-write``;
 * the scope contains ``$P`` literally.
 
 The permission ``token-refresh`` is handled separately and is granted if and
 only if the access token is refreshable, regardless of the scope's permission
 set.
 
 Refreshable tokens
 """"""""""""""""""
 
 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`.
 Tokens with the ``all`` (or the deprecated ``write``) scope are always
 refreshable.
 
 When requesting a token from
 :http:post:`[/instances/$INSTANCE]/private/token` with an existing access
 token, the requested scope must be a subset of the scope of the token used,
 and a non-refreshable token can never be used to obtain a refreshable one.
 
 -----------------
 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 :http:get:`/keys </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 a ``Taler-Challenge-Ids`` HTTP header. The body must
 remain absolutely unchanged.
 
 Challenge IDs are bound to the merchant instance, the critical operation,
 the required authentication factor, and the exact request body for which
 they were issued.  A solved challenge is therefore authorization to retry
 that particular transaction.  It is not proof of a generic privilege
 elevation or merely of an MFA authentication performed recently, and it
 MUST NOT authorize an operation for another instance.  Binding challenges
 to their merchant instance is required since protocol **v39**.
 
 Clients should retain challenge IDs only while transmitting or confirming
 the challenges and completing or retrying the protected request.  They must
 not attach challenge IDs to unrelated requests or reuse them for another
 instance, operation, or request body.
 
   .. 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: Slug;
 
     // 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-units.rst
 
 .. 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
 
 
 .. _collect-order:
 
 Collecting zero-Taler orders
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Orders whose Taler ``amount`` is zero, for example because the full total
 was settled through ``amount_external``, can be completed by the merchant
 backend itself instead of a customer wallet.
 
 .. include:: merchant/post-private-orders-ORDER_ID-collect.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.
 
 A member is marked as forgettable by adding its name to the
 ``$forgettable`` object in the same parent object.  The value is a random salt
 encoded using upper-case Crockford Base32.  Order-creation requests may use
 ``true`` instead of a salt; the merchant backend then generates the random
 salt before producing the final contract terms.  The boolean form is not valid
 in final contract terms.
 
 Forgetting a member removes both its value and its salt and adds an entry with
 the same name to ``$forgotten``.  The entry is a 64-byte HKDF-SHA-512 result,
 encoded using upper-case Crockford Base32.  The HKDF input key material is the
 RFC 8785 canonical JSON representation of the recursively scrubbed member
 value followed by one zero byte.  The HKDF salt is the UTF-8 representation of
 the salt string followed by one zero byte, and the HKDF context is empty.  Scrubbing an object
 recursively forgets all members marked by ``$forgettable``.  These rules make
 the hash of the contract terms invariant under authorized forgetting.
 
 Objects that participate in this mechanism may use ordinary member names
 matching ``^[-0-9A-Za-z_]+$`` and the two reserved names ``$forgettable`` and
 ``$forgotten``.  Numbers must be safe integers; floating-point values are not
 permitted.
 
 The following object is the interoperability reference vector::
 
   {
     "k1": 1,
     "$forgettable": { "k1": "SALT" },
     "k2": {
       "n1": true,
       "$forgettable": { "n1": "salt" }
     },
     "k3": { "n1": "string" }
   }
 
 Its Crockford-Base32-encoded contract hash is
 ``VDE8JPX0AEEE3EX1K8E11RYEWSZQKGGZCV6BWTE4ST1C8711P7H850Z7F2Q2HSSYETX87ERC2JNHWB7GTDWTDWMM716VKPSRBXD7SRR``.
 
 .. 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
 
 .. include:: merchant/post-private-orders-ORDER_ID-refund-external.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
 
 
 .. _merchant-otp-device-api:
 
 -----------
 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 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 templates 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 abort 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
 
 
 .. _merchant-fountain-api:
 
 -----------------------------------------
 Fountains: Promotional Token Distribution
 -----------------------------------------
 
 A fountain is a bearer credential that entitles a wallet to withdraw
 blind-signed promotional tokens for a set of token families without
 creating an order per withdrawal.  An institution can distribute a fountain
 to one recipient or share it for a campaign
 (see :doc:`DD 98 </design-documents/098-token-fountains>`).
 
 Wallets receive the credential as a
 ``taler://fountain/$MERCHANT_HOST[/$INSTANCE_PATH]/$FOUNTAIN_ID/$FOUNTAIN_SECRET``
 URI. All fountain endpoints are available since protocol
 **v43**.
 
 Managing fountains
 ^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/post-private-fountains.rst
 
 .. include:: merchant/patch-private-fountains-FOUNTAIN_ID.rst
 
 .. include:: merchant/get-private-fountains.rst
 
 .. include:: merchant/get-private-fountains-FOUNTAIN_ID.rst
 
 .. include:: merchant/delete-private-fountains-FOUNTAIN_ID.rst
 
 
 Wallet fountain API
 ^^^^^^^^^^^^^^^^^^^
 
 .. include:: merchant/get-fountain-info.rst
 
 .. include:: merchant/post-fountain-withdraw.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.
 
 See :ref:`Scopes <merchant-api-scopes>` for how permissions relate to the
 scope of an access token.
 
 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;
 
       // Lower bound (inclusive) on amounts the client gets to choose
       // when instantiating this template.  Excludes any tip.  Only
       // amounts the client had an influence on are checked against
       // this bound: the amount given in the request for a "fixed-order"
       // template, the total of the selected products for an
       // "inventory-cart" template, and the amount of an editable choice
       // for a "paivana" template.  Requires "currency" to be given and
       // to match, must be in the same currency as "max_amount", and
       // must not exceed it.
       // Since protocol **v34**.
       min_amount?: Amount;
 
       // Upper bound (inclusive) on amounts the client gets to choose
       // when instantiating this template.  Excludes any tip.  Checked
       // against the same amounts as "min_amount".  Requires "currency"
       // to be given and to match.
       // Since protocol **v34**.
       max_amount?: Amount;
 
       // Time available to pay before the order expires unpaid.  If omitted or
       // zero, the instance's default pay delay is used.  "forever" is invalid.
       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 for every template type,
       // measured from order creation (not from payment or a repeat visit).
       // Optional; if omitted or "forever", access has no deadline.
       // Zero gives an immediately expired access window.
       // 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 {
 
       // POSIX extended regular expression over URLs for which
       // this template is valid.  Matched against the absolute
       // URL, and anchored: it must match that URL in its
       // entirety, not merely occur within it.
       // Optional, if not given all URLs are accepted.
       // Since protocol **v25**.
       website_regex?: string;
 
       // Methods to pay for the contract.
       choices: TemplateOrderChoice[];
    }
 
   The backend only stores ``website_regex``; it is the paywall proxy
   reading these templates that evaluates it.  ``paivana-httpd`` matches
   it against the **absolute** URL of the request (``BASE_URL`` or the
   scheme and ``Host`` of the request, followed by the path) and anchors
   it, so an expression written against the path alone, or meant as a
   substring rule, will not apply.  See :ref:`Paivana-Templates` in the
   :doc:`Paivana operator manual <../taler-paivana-manual>` for the
   matching rules and worked examples.
 
   If exactly one of the ``choices`` of a Paivana template has
   ``editable_amount`` set, the template may also carry an ``amount`` in its
   ``editable_defaults`` to tell the user interface to offer a single amount
   field with that default; the client then submits it as the ``amount`` of
   the `UsingTemplateCommonRequest`.  With more than one editable choice, the
   defaults are the ``amount`` values of the choices themselves and the client
   must use ``choice_amounts``.
 
 .. _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;
     }
 
   A choice of a *template* contract may additionally allow the client to
   replace the amount when the template is instantiated.
 
   .. ts:def:: TemplateOrderChoice
 
     interface TemplateOrderChoice extends OrderChoice {
       // If true, the client may replace "amount" when instantiating
       // the template; "amount" then merely provides the default.  The
       // client may only change the value, never the currency.  The
       // resulting amount is subject to the "min_amount" and
       // "max_amount" bounds of the template (if any).
       // Defaults to false, in which case the amount is fixed by the
       // merchant.
       // Since protocol **v34**.
       editable_amount?: boolean;
     }
 
   .. 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: Slug;
 
       // 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: Slug;
 
       // 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: Slug;
 
     // 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?: WebURL;
 
     // 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, while the previous purchase's max_pickup_time still permits
     // access. This is useful for digital goods that a customer should
     // be able to repeatedly download during the purchased access period.
     //
     // 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.
     // Because of that placeholder, the value given here is merely a
     // string and not yet a `WebURL`; only after the substitution has
     // been performed is the result a `WebURL`.
     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). Absent or "never" means unlimited.
     // Once this time is reached, wallets must not reuse the purchase to
     // satisfy a new order with the same fulfillment_url. A new payment
     // requires the customer's confirmation.
     max_pickup_time?: Timestamp;
 
   }
 
 .. _order-details:
 
 Orders
 ^^^^^^
 
   The `Order` object represents the starting point for new `ContractTerms`.
   After validating and sanitizing 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;
 
       // Payments for this order that were settled outside of Taler,
       // for example in cash or by card. The ``amount`` field above (or
       // the selected choice's ``amount`` for v1 orders) remains the
       // amount paid with Taler; the full order total is the sum of that
       // amount and all entries here. If present, all entries and (for
       // v1 orders) all choices must use the currency of the Taler
       // ``amount``. Never contains a ``taler`` entry.
       // @since protocol **v42**.
       amount_external?: ExternalPaymentInfo[];
 
     }
 
   .. ts:def:: ExternalPaymentInfo
 
     interface ExternalPaymentInfo {
       // External payment method, for example "cash" or "card".
       // Must be a stable, non-empty identifier of ASCII
       // alphanumerics and "-", and must never be "taler".
       method: string;
 
       // Identifier of the payment action within the order, unique
       // among the entries of this ``amount_external`` array.
       // Examples: "cash1", "card1", "card2".
       id: string;
 
       // Amount covered by this payment action. Must use the same
       // currency as the Taler ``amount`` of the order.
       amount: Amount;
 
       // Additional method-specific fields for reconciliation or audit,
       // for example a cashier number, terminal identifier or
       // authorization code. These must be flat scalar values (no
       // nested objects or arrays) so that the merchant portal can
       // render ``amount_external`` as a generic table.
       [field: string]: string | Amount | Integer | boolean | null;
     }
 
 .. _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 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: Slug;
 
       // 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: Slug]: 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: WebURL;
 
     // 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[];
 
     // Payments for this order that were settled outside of Taler,
     // for example in cash or by card. The ``amount`` field (or the
     // selected choice's ``amount`` for v1 contracts) remains the amount
     // paid with Taler; the full order total is the sum of that amount
     // and all entries here. See `ExternalPaymentInfo`.
     // @since protocol **v42**.
     amount_external?: ExternalPaymentInfo[];
 
   }
 
 .. 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: Slug;
 
     // 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: Slug;
 
     // 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: WebURL[];
 
     // 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?: Slug;
 
     // 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?: Slug;
 
     // 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;
 
     // Merchant public website.
     website?: WebURL;
 
     // 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 the merchant accepts by
 listing it in the exchanges array.
 
 .. ts:def:: Exchange
 
   interface Exchange {
     // The exchange's base URL.
     url: WebURL;
 
     // 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;
   }