taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

api-merchant.rst (85315B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2014-2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Marcello Stanisci
     17   @author Florian Dold
     18   @author Christian Grothoff
     19   @author Priscilla Huang
     20   @author Martin Schanzenbach
     21 
     22 .. _merchant-api:
     23 
     24 ============================
     25 Merchant Backend RESTful API
     26 ============================
     27 
     28 ---------------
     29 Version History
     30 ---------------
     31 
     32 The currently implemented protocol version is **v45**.
     33 
     34 * The Android PoS app is currently targeting **v20**.
     35 * The SPA is currently targeting **vXX**.
     36 * taler-mdb is currently targeting **v27**.
     37 * anastasis is currently targeting **v27**.
     38 * taler-woocommerce is currently targeting **v29**.
     39 * taler-drupal-turnstile is currently targeting **v29**.
     40 * taler-drupal-commerce is currently targeting **vXX**.
     41 * paivana is currently targeting **v29**.
     42 
     43 **Version history:**
     44 
     45 * ``v21``: Added self-provisioning and two factor authentication
     46 * ``v22``: Added various defaults
     47 * ``v23``: Added various defaults, fields and some new filters
     48 * ``v24``: Make minor changes to refund semantics
     49 * ``v25``: adds features to group amounts internally (say to
     50   separate tips, taxes and revenue in reporting), endpoints
     51   for periodic report generation and inventory-based templates,
     52   new long-polling for KYC and features for templates to support
     53   session-based payments
     54 * ``v26``: adds unclaim endpoint, enhanced settlement reporting
     55 * ``v27``: adds various fields to a few endpoints
     56 * ``v28``: adds the ``/kycauth`` endpoint for wire transfer subject
     57   shortening during KYC Auth wire transfers and expands :http:get:`/config </config>`.
     58 * ``v29``: adds ``max_pickup_duration`` to templates (for Paivana)
     59 * ``v30``: adds ``debit_restrictions`` to GET /exchanges (for SPA)
     60 * ``v31``: adds ``/private/accept-tos-early`` and related API changes
     61 * ``v32``: adds "force" argument for locked product deletion
     62 * ``v33``: adds ``build_version`` to :http:get:`/config </config>` and
     63   ``max_age_s`` to ``[/instances/$INSTANCE]/private/orders``, deprecating
     64   the ``max_age`` query parameter of that endpoint
     65 * ``v34``: adds ``editable_amount`` to the choices of a Paivana template
     66   together with the ``choice_amounts`` request field to instantiate them,
     67   and ``min_amount``/``max_amount`` to bound client-chosen amounts for
     68   templates of any type
     69 * ``v35``: adds ``exchange_payto_uri`` to
     70   :http:get:`[/instances/$INSTANCE]/private/transfers`,
     71   passing on the exchange account reported by exchange protocol **v39**
     72 * ``v36``: allows token families with indefinite validity
     73 * ``v37``: adds expiration filtering to the private order history
     74 * ``v38``: adds reporting and repair of an order's wired status
     75 * ``v39``: returns a login token after a successful password reset
     76 * ``v40``: requires the current password when changing merchant credentials
     77 * ``v41``: returns merchant details and compatible exchange candidates for
     78   wallet templates
     79 * ``v42``: adds the additive ``amount_external`` field for orders settled
     80   partly outside of Taler, the ``/private/orders/$ORDER_ID/collect`` endpoint
     81   for completing zero-Taler orders without a wallet, the
     82   ``/private/orders/$ORDER_ID/refund-external`` endpoint for recording
     83   externally settled refunds, and exposes both through order status
     84   (see :doc:`DD 96 </design-documents/096-partial-payments>`)
     85 * ``v43``: adds ECDSA and EdDSA challenge-based payment confirmations.
     86   The OTP-device API generates signing keys and exposes the public key.
     87   Order creation and template instantiation accept a ``challenge``; after
     88   successful payment, the backend returns its signature in ``pos_confirmation``
     89   (see :doc:`DD 97 </design-documents/097-challenge-confirmations>`).
     90   Also adds token fountain management and wallet APIs for retrieving grants
     91   and withdrawing blind-signed promotional tokens without creating an order
     92   (see :doc:`DD 98 </design-documents/098-token-fountains>`)
     93 * ``v44``: adds unauthenticated :http:get:`[/instances/$INSTANCE]/units`
     94   to retrieve all active measurement units for one merchant instance,
     95   including built-in units with instance overrides and custom units.
     96   Also adds ``limit``/``offset`` pagination to
     97   :http:get:`[/instances/$INSTANCE]/private/fountains`, using the new
     98   ``fountain_serial`` response field as an exclusive cursor
     99 
    100 * ``v45``: adds report test sends and delivery history
    101 
    102 **Upcoming versions:**
    103 
    104 * ``vTAXES``: adds features to manage taxes
    105 * ``vDonauReceipts``: returns donation receipts from ``/pay`` in the new
    106   ``donau_sigs`` field instead of inside ``token_sigs`` (breaking for orders
    107   with a donation receipt output), answers a Donau failure after a
    108   successful payment with a 502 that carries the payment confirmation, and
    109   refuses to replay ``/pay`` after a refund
    110 
    111 **Ideas for future version:**
    112 
    113 * ``vXXX``: marker for features not yet targeted for release
    114 
    115 -----------------------
    116 Base URLs and Instances
    117 -----------------------
    118 
    119 A single merchant backend installation can host multiple merchant instances.
    120 This is useful when multiple businesses want to share the same payment
    121 infrastructure.
    122 
    123 Merchant backends have one special ``admin`` instance.  This ``admin``
    124 instance is used when no explicit instance is specified.  Note that using
    125 ``/instances/admin/$ANYTHING`` is deprecated and will result in a permanent
    126 redirect (HTTP status 308) to ``$ANYTHING``. Despite its name, this instance
    127 must be created after the installation.
    128 
    129 Each instance (admin and others) has a base URL.  The resources under
    130 this base URL are divided into the following categories:
    131 
    132 * Public endpoints that are exposed to the Internet
    133 * Private endpoints (under ``/private/*``) that are only supposed to be exposed
    134   to the merchant internally, and must not be exposed on the
    135   Internet.
    136 * Management endpoints (under ``/management/*``) are also private and dedicated
    137   to CRUD operation over instances and reset authentication settings over all
    138   instances. Only accessible with the admin instance authentication token.
    139 
    140 Examples:
    141 
    142 .. code-block:: none
    143 
    144    Base URL of the merchant (admin instance) at merchant-backend.example.com:
    145    https://merchant-backend.example.com/
    146 
    147    A private endpoint (admin instance):
    148    https://merchant-backend.example.com/private/orders
    149 
    150    A public endpoint (admin instance and order id "ABCD"):
    151    https://merchant-backend.example.com/orders/ABCD
    152 
    153    A private endpoint ("myinst" instance):
    154    https://merchant-backend.example.com/instances/myinst/private/orders
    155 
    156    A public endpoint ("myinst" instance and order id "ABCD"):
    157    https://merchant-backend.example.com/instances/myinst/orders/ABCD
    158 
    159    A private endpoint (explicit "admin" instance):
    160    https://merchant-backend.example.com/private/orders
    161 
    162    A public endpoint (explicit "admin" instance):
    163    https://merchant-backend.example.com/orders
    164 
    165    Endpoints to manage other instances (ONLY for implicit "admin" instance):
    166    https://merchant-backend.example.com/management/instances
    167    https://merchant-backend.example.com/management/instances/$ID
    168 
    169    Endpoints to manage own instance:
    170    https://merchant-backend.example.com/private
    171    https://merchant-backend.example.com/private/auth
    172    https://merchant-backend.example.com/instances/$ID/private
    173    https://merchant-backend.example.com/instances/$ID/forgot-password
    174    https://merchant-backend.example.com/instances/$ID/private/auth
    175 
    176    Unavailabe endpoints (will return 404):
    177    https://merchant-backend.example.com/instances/myinst/private/instances
    178 
    179 .. _merchant-session-id:
    180 
    181 -----------
    182 Session IDs
    183 -----------
    184 
    185 Payments can be bound to a *session*, which is identified by a session ID.
    186 Session IDs are chosen by the merchant's frontend (or by the client device,
    187 as is the case for the Paivana IDs given to
    188 :http:post:`[/instances/$INSTANCE]/templates/$TEMPLATE_ID`); the backend
    189 merely stores them and uses them to match a payment against the session it
    190 was made for.
    191 
    192 .. ts:def:: SessionID
    193 
    194   // Identifier of the session a payment is bound to.  Like a `Slug`,
    195   // a session ID must only use ASCII alphanumeric characters
    196   // ("A-Z", "a-z", "0-9") and the punctuation characters "-", ".",
    197   // "_", ":" and "~", and must not be "." or "..".  Unlike a slug, a
    198   // session ID may also contain "=" and may be empty.
    199   // Session IDs are case-sensitive.
    200   type SessionID = string;
    201 
    202 A session ID is thus *not* a slug.  It additionally permits ``=`` because
    203 session IDs are frequently base64-encoded identifiers, which may end in
    204 padding.  And it may be empty: the empty session ID means that a payment is
    205 not bound to any session.  Clients must expect to encounter it, as the
    206 backend itself puts an empty session ID into the ``taler://pay/`` URI of an
    207 order that has no session (the session is the last path component of that
    208 URI and thus cannot simply be omitted), and wallets send back what they were
    209 given.  Endpoints for which only an actual session makes sense say so
    210 explicitly and reject the empty session ID.
    211 
    212 -----------------
    213 Generic Responses
    214 -----------------
    215 
    216 The following (error) responses are applicable to all endpoints
    217 unless specified otherwise.
    218 
    219 .. include:: merchant/any-star.rst
    220 
    221 .. _merchant-api-authentication:
    222 
    223 --------------
    224 Authentication
    225 --------------
    226 
    227 Each merchant instance has separate authentication settings for the private API resources
    228 of that instance.
    229 
    230 Currently, the ``/private/auth/`` API supports two main authentication methods in the `InstanceAuthConfigurationMessage`:
    231 
    232 * ``external``: (@deprecated since **v20**) With this method, no checks are done by the merchant backend.
    233   Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
    234 * ``token`` (**@since v19**): With this method, the client must provide an authorization header
    235   that contains a bearer token  when accessing a protected endpoint in the form
    236   ``Authorization: Bearer secret-token:$TOKEN``.
    237   ``$TOKEN`` is an authentication token retrieved from the ``/private/token`` endpoint using basic authorization.
    238   The respective username is the instance ``$ID``, and the password the instance password (``$INSTANCE_PASSWORD``).
    239   A login token is commonly only valid for a limited period of time and scoped to specific permissions.
    240   A login token that is unknown or has expired is rejected with a ``401 Unauthorized``
    241   and ``TALER_EC_GENERIC_TOKEN_UNKNOWN`` or ``TALER_EC_GENERIC_TOKEN_EXPIRED`` respectively.
    242   If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a password
    243   using the ``taler-merchant-passwd`` command-line tool.
    244 * ``token`` (@deprecated since **v19**): With this method, the client must provide an authentication token in
    245   the format ``secret-token: $INSTANCE_PASSWORD``.
    246   The behaviour is then equivalent to the ``token`` method above.
    247   Any API may be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``.
    248   Notice that this behaviour is deprecated and will be phased out in favor of login tokens.
    249   The bearer token is only interpreted as the instance password if it is not a well-formed login token.
    250   The backend refuses the instance password as a bearer token if the instance has a usable MFA channel
    251   (a validated e-mail address with ``HELPER_EMAIL`` configured, or a validated phone number
    252   with ``HELPER_SMS`` configured), as it would bypass the MFA required by ``/private/token``,
    253   and always if the backend runs with ``STRICT_PROTOCOL_V19 = YES``.
    254   Such requests fail with a ``401 Unauthorized`` and ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
    255   Clients must then obtain a login token from ``/private/token`` using basic authorization;
    256   for instances with MFA, that request requires solving MFA challenges.
    257 
    258 For testing, the service may be started with the configuration option ``DISABLE_AUTHENTICATION = YES``
    259 in section ``[merchant]`` (@since **v20**).
    260 
    261 .. _merchant-api-scopes:
    262 
    263 Scopes and permissions
    264 ^^^^^^^^^^^^^^^^^^^^^^
    265 
    266 Authorization in the merchant backend is expressed with *permissions*.  Every
    267 endpoint that requires authorization requires exactly one permission, which is
    268 stated as **Required permission** in the documentation of that endpoint.
    269 Permission names have the form ``$RESOURCE-$ACTION``, where ``$ACTION`` is
    270 usually ``read`` (for operations that only inspect state) or ``write`` (for
    271 operations that change it).
    272 
    273 Clients do not request individual permissions.  Instead, an access token is
    274 issued for a *scope*, which is a fixed, named set of permissions.  A request is
    275 authorized if the permission required by the endpoint is covered by the scope
    276 of the access token that was used.
    277 
    278 Permissions
    279 """""""""""
    280 
    281 The following permissions exist:
    282 
    283 .. list-table::
    284   :widths: 25 75
    285   :header-rows: 1
    286 
    287   * - Permission
    288     - Grants access to
    289   * - ``accounts-read``
    290     - Listing and inspecting the bank accounts of the instance, and starting
    291       KYC authentication for one of them.
    292   * - ``accounts-write``
    293     - Adding, modifying and deleting bank accounts of the instance, and
    294       accepting the terms of service of an exchange ahead of time.
    295   * - ``auth-write``
    296     - Changing the authentication settings of the instance itself
    297       (via the instance's own ``/private/auth`` endpoint).
    298   * - ``categories-read``
    299     - Listing and inspecting product categories.
    300   * - ``categories-write``
    301     - Creating, modifying and deleting product categories.
    302   * - ``donau-read``
    303     - Listing the linked Donau charity instances.
    304   * - ``donau-write``
    305     - Adding and removing Donau charity instance links.
    306   * - ``fountains-read``
    307     - Listing and inspecting token fountains.  Since **v43**.
    308   * - ``fountains-write``
    309     - Creating, modifying and deleting token fountains.
    310       Since **v43**.
    311   * - ``groups-read``
    312     - Listing product groups.
    313   * - ``groups-write``
    314     - Creating, modifying and deleting product groups.
    315   * - ``instances-auth-write``
    316     - Changing the authentication settings of *any* instance via the
    317       ``/management/`` API.  Only the ``admin`` instance can hold this
    318       permission in a useful way.
    319   * - ``instances-kyc-read``
    320     - Querying the KYC status of *any* instance via the ``/management/`` API.
    321   * - ``instances-read``
    322     - Reading the configuration of the instance itself.
    323   * - ``instances-write``
    324     - Creating, inspecting, modifying and deleting instances.  Note that this
    325       permission is required for *all* operations on the ``/management/``
    326       instance API, including the ``GET`` operations that merely list or
    327       inspect instances, as well as for modifying or deleting the instance
    328       itself via its own private API.
    329   * - ``kyc-read``
    330     - Querying the KYC status of the instance itself.
    331   * - ``orders-read``
    332     - Listing orders and checking their payment, refund and wire transfer
    333       status.
    334   * - ``orders-write``
    335     - Creating orders, forgetting parts of a contract, collecting zero-amount
    336       orders and deleting orders.
    337   * - ``orders-refund``
    338     - Granting refunds and recording externally settled refunds.
    339   * - ``otp-devices-read``
    340     - Listing and inspecting one-time-password (OTP) devices.
    341   * - ``otp-devices-write``
    342     - Creating, modifying and deleting OTP devices.
    343   * - ``pos-read``
    344     - Downloading the full point-of-sale configuration
    345       (:http:get:`[/instances/$INSTANCE]/private/pos`).
    346   * - ``pots-read``
    347     - Listing and inspecting money pots.
    348   * - ``pots-write``
    349     - Creating, modifying and deleting money pots.
    350   * - ``products-read``
    351     - Listing and inspecting products in the inventory.
    352   * - ``products-write``
    353     - Adding, modifying and deleting products in the inventory.
    354   * - ``products-lock``
    355     - Locking products in the inventory
    356       (:http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`).
    357   * - ``reports-read``
    358     - Listing and inspecting report schedules and delivery attempts,
    359       including tests sent from drafts or saved schedules.
    360   * - ``reports-write``
    361     - Creating, modifying and deleting report schedules, and sending a test
    362       report to a destination specified in the request.
    363   * - ``statistics-read``
    364     - Reading counter, amount and transaction statistics.
    365   * - ``templates-read``
    366     - Listing and inspecting order templates.
    367   * - ``templates-write``
    368     - Creating, modifying and deleting order templates.
    369   * - ``tokenfamilies-read``
    370     - Listing and inspecting token families.
    371   * - ``tokenfamilies-write``
    372     - Creating, modifying and deleting token families.
    373   * - ``tokens-read``
    374     - Listing the access tokens that were issued for the instance.
    375   * - ``tokens-write``
    376     - Revoking access tokens of the instance by serial.
    377   * - ``token-refresh``
    378     - Obtaining a new access token from
    379       :http:post:`[/instances/$INSTANCE]/private/token` using an existing
    380       access token.  This permission is special: it is *not* part of any
    381       scope's permission set and is not implied by ``*``.  It is granted
    382       exactly if the access token used is refreshable (see below).
    383   * - ``transfers-read``
    384     - Listing expected and actual wire transfers, including incoming
    385       transfers.
    386   * - ``transfers-write``
    387     - Informing the backend about wire transfers and deleting such records.
    388   * - ``units-read``
    389     - Listing and inspecting measurement units.
    390   * - ``units-write``
    391     - Creating, modifying and deleting measurement units.
    392   * - ``webhooks-read``
    393     - Listing and inspecting webhooks.
    394   * - ``webhooks-write``
    395     - Creating, modifying and deleting webhooks.
    396 
    397 Endpoints of the wallet-facing (public) API, such as those used to claim, pay
    398 for or abort an order, require no permission at all and are documented as
    399 "**Required permission:** none".
    400 
    401 Scopes
    402 """"""
    403 
    404 Access tokens can be requested with a (limiting) scope.  The available scopes
    405 and the permissions they grant are:
    406 
    407 .. list-table::
    408   :widths: 15 45 40
    409   :header-rows: 1
    410 
    411   * - Scope
    412     - Permissions
    413     - Remarks
    414   * - ``readonly``
    415     - ``*-read``
    416     - Every permission ending in ``-read``.  Note that this does *not* include
    417       the ``/management/`` instance API, which requires ``instances-write``
    418       even for ``GET`` requests.
    419   * - ``all``
    420     - ``*``
    421     - Every permission.  Tokens with this scope are always refreshable.
    422       @since **v19**
    423   * - ``write``
    424     - ``*``
    425     - @deprecated since **v19**, identical to ``all``.
    426   * - ``spa``
    427     - ``*``
    428     - Every permission; used by the merchant backoffice SPA.  Unlike ``all``,
    429       this scope is not implicitly refreshable.  @since **v20**
    430   * - ``order-simple``
    431     - ``orders-read``, ``orders-write``
    432     - Allows the creation of orders and checking of payment status.
    433       @since **v19**
    434   * - ``order-pos``
    435     - ``orders-read``, ``orders-write``, ``pos-read``, ``products-lock``,
    436       ``products-read``, ``orders-refund``
    437     - Same as ``order-simple`` and allows inventory locking (@since **v19**),
    438       ``products-read`` since **v32**, and granting refunds.
    439   * - ``order-mgmt``
    440     - ``orders-read``, ``orders-write``, ``pos-read``, ``orders-refund``
    441     - Same as ``order-simple``, plus reading the point-of-sale configuration
    442       and granting refunds.  @since **v19**
    443   * - ``order-full``
    444     - ``orders-read``, ``orders-write``, ``pos-read``, ``products-lock``,
    445       ``orders-refund``
    446     - ``order-pos`` and ``order-mgmt`` combined.  @since **v19**
    447 
    448 .. note::
    449 
    450    The ``products-lock`` permission granted by ``order-pos`` and ``order-full``
    451    is only required for explicitly locking products via
    452    :http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`.
    453    Creating an order (which locks inventory as a side effect) requires only
    454    ``orders-write``.
    455 
    456 .. ts:def:: TokenScope
    457 
    458   // Scope of an access token.  Since **v19**, the scope may be
    459   // suffixed with ":refreshable" (see below), for example
    460   // "order-pos:refreshable".  "write" is deprecated since **v19**
    461   // and is equivalent to "all".
    462   type TokenScope = "readonly" | "all" | "spa" | "order-simple" | "order-pos" | "order-mgmt" | "order-full" | "write";
    463 
    464 Matching rules
    465 """"""""""""""
    466 
    467 Given the permission ``$P`` required by an endpoint and the permission set of
    468 the scope of the access token used, access is granted if any of the following
    469 holds:
    470 
    471 * the scope contains ``*``;
    472 * the scope contains ``*-read`` and ``$P`` ends in ``-read``;
    473 * the scope contains ``*-write`` and ``$P`` ends in ``-write``;
    474 * the scope contains ``$P`` literally.
    475 
    476 The permission ``token-refresh`` is handled separately and is granted if and
    477 only if the access token is refreshable, regardless of the scope's permission
    478 set.
    479 
    480 Refreshable tokens
    481 """"""""""""""""""
    482 
    483 Since **v19** the scope may be suffixed with ``:refreshable``, e.g.
    484 ``order-pos:refreshable``.
    485 This allows the token to be refreshed at the token endpoint.
    486 This behaviour replaces the deprecated ``refreshable`` field in the `LoginTokenRequest`.
    487 Tokens with the ``all`` (or the deprecated ``write``) scope are always
    488 refreshable.
    489 
    490 When requesting a token from
    491 :http:post:`[/instances/$INSTANCE]/private/token` with an existing access
    492 token, the requested scope must be a subset of the scope of the token used,
    493 and a non-refreshable token can never be used to obtain a refreshable one.
    494 
    495 -----------------
    496 Configuration API
    497 -----------------
    498 
    499 The configuration API exposes basic information about a merchant backend,
    500 such as the implemented version of the protocol and the currency used.
    501 
    502 .. include:: merchant/get-config.rst
    503 
    504 .. include:: tos.rst
    505 
    506 -------------------
    507 Exchange Status API
    508 -------------------
    509 
    510 The exchange status API exposes basic information about the exchanges
    511 configured for a merchant backend, in particular the acceptable
    512 currencies, master public keys and the status of the merchant backend's
    513 download of the :http:get:`/keys </keys>` from the exchange.  This is mostly useful
    514 to diagnose configuration problems.
    515 
    516 .. include:: merchant/get-exchanges.rst
    517 
    518 ---------------
    519 Two Factor Auth
    520 ---------------
    521 
    522 202 Challenge Responses
    523 ^^^^^^^^^^^^^^^^^^^^^^^
    524 
    525 Various APIs generate ``202 Accepted`` HTTP status codes when multi-factor
    526 authentication (MFA) is required.  In this case, the response will be a
    527 `ChallengeResponse`.  In these cases, the client must first request and solve
    528 one or more challenges before repeating the request. When repeating the
    529 request, they must include a list of comma-separated challenge IDs of the
    530 solved challenges in a ``Taler-Challenge-Ids`` HTTP header. The body must
    531 remain absolutely unchanged.
    532 
    533 Challenge IDs are bound to the merchant instance, the critical operation,
    534 the required authentication factor, and the exact request body for which
    535 they were issued.  A solved challenge is therefore authorization to retry
    536 that particular transaction.  It is not proof of a generic privilege
    537 elevation or merely of an MFA authentication performed recently, and it
    538 MUST NOT authorize an operation for another instance.  Binding challenges
    539 to their merchant instance is required since protocol **v39**.
    540 
    541 Clients should retain challenge IDs only while transmitting or confirming
    542 the challenges and completing or retrying the protected request.  They must
    543 not attach challenge IDs to unrelated requests or reuse them for another
    544 instance, operation, or request body.
    545 
    546 .. note::
    547 
    548   If all allowed attempts to solve the MFA challenge(s) fail, the endpoint
    549   may start to return ``403 Forbidden`` until the issued challenges expire,
    550   preventing the request from being completed for a while.  In this case,
    551   repeating the request with a different body may still be allowed!
    552 
    553 .. ts:def:: ChallengeResponse
    554 
    555   // @since v21
    556   interface ChallengeResponse {
    557     // List of challenge IDs that must be solved before the
    558     // client may proceed.
    559     challenges: Challenge[];
    560 
    561     // True if **all** challenges must be solved (AND), false if
    562     // it is sufficient to solve one of them (OR).
    563     combi_and: boolean;
    564 
    565   }
    566 
    567 .. ts:def:: Challenge
    568 
    569   interface Challenge {
    570     // Unique identifier of the challenge to solve to run this protected
    571     // operation.
    572     challenge_id: Slug;
    573 
    574     // Channel of the last successful transmission of the TAN challenge.
    575     tan_channel: TanChannel;
    576 
    577     // Info of the last successful transmission of the TAN challenge.
    578     // Hint to show to the user as to where the challenge was
    579     // sent or what to use to solve the challenge. May not
    580     // contain the full address for privacy.
    581     tan_info: string;
    582 
    583   }
    584 
    585 Requesting challenges
    586 ^^^^^^^^^^^^^^^^^^^^^
    587 
    588 .. include:: merchant/post-challenge-CHALLENGE_ID.rst
    589 
    590 Solving challenges
    591 ^^^^^^^^^^^^^^^^^^
    592 
    593 .. include:: merchant/post-challenge-CHALLENGE_ID-confirm.rst
    594 
    595 ----------
    596 Wallet API
    597 ----------
    598 
    599 This section describes (public) endpoints that wallets must be able
    600 to interact with directly (without HTTP-based authentication). These
    601 endpoints are used to process payments (claiming an order, paying
    602 for the order, checking payment/refund status and aborting payments),
    603 and to process refunds (checking refund status, obtaining the refund).
    604 
    605 
    606 Claiming an order
    607 ^^^^^^^^^^^^^^^^^
    608 
    609 The first step of processing any Taler payment consists of the
    610 (authorized) wallet claiming the order for itself. In this process,
    611 the wallet provides a wallet-generated nonce that is added
    612 into the contract terms.  This step prevents two different
    613 wallets from paying for the same contract, which would be bad
    614 especially if the merchant only has finite stocks.
    615 
    616 A claim token can be used to ensure that the wallet claiming an
    617 order is actually authorized to do so. This is useful in cases
    618 where order IDs are predictable and malicious actors may try to
    619 claim orders (say in a case where stocks are limited).
    620 
    621 
    622 .. include:: merchant/post-orders-ORDER_ID-claim.rst
    623 
    624 .. include:: merchant/post-orders-ORDER_ID-unclaim.rst
    625 
    626 
    627 Making the payment
    628 ^^^^^^^^^^^^^^^^^^
    629 
    630 .. include:: merchant/post-orders-ORDER_ID-pay.rst
    631 
    632 
    633 Querying payment status
    634 ^^^^^^^^^^^^^^^^^^^^^^^
    635 
    636 .. include:: merchant/get-orders-ORDER_ID.rst
    637 
    638 .. include:: merchant/get-sessions-SESSION_ID.rst
    639 
    640 
    641 Demonstrating payment
    642 ^^^^^^^^^^^^^^^^^^^^^
    643 
    644 In case a wallet has already paid for an order, this is a fast way of proving
    645 to the merchant that the order was already paid. The alternative would be to
    646 replay the original payment, but simply providing the merchant's signature
    647 saves bandwidth and computation time.
    648 
    649 Demonstrating payment is useful in case a digital good was made available
    650 only to clients with a particular session ID: if that session ID expired or
    651 if the user is using a different client, demonstrating payment will allow
    652 the user to regain access to the digital good without having to pay for it
    653 again.
    654 
    655 .. include:: merchant/post-orders-ORDER_ID-paid.rst
    656 
    657 
    658 Aborting incomplete payments
    659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    660 
    661 In rare cases (such as a wallet restoring from an outdated backup) it is possible
    662 that a wallet fails to complete a payment because it runs out of e-cash in the
    663 middle of the process. The abort API allows the wallet to abort the payment for
    664 such an incomplete payment and to regain control over the coins that were spent
    665 so far. Aborts are not permitted for payments that have completed.  In contrast to
    666 refunds, aborts do not require approval by the merchant because aborts always
    667 are for incomplete payments for an order and never for established contracts.
    668 
    669 
    670 .. _order-abort:
    671 .. include:: merchant/post-orders-ORDER_ID-abort.rst
    672 
    673 
    674 Obtaining refunds
    675 ^^^^^^^^^^^^^^^^^
    676 
    677 Refunds allow merchants to fully or partially restitute e-cash to a wallet,
    678 for example because the merchant determined that it could not actually fulfill
    679 the contract. Refunds must be approved by the merchant's business logic.
    680 
    681 .. include:: merchant/post-orders-ORDER_ID-refund.rst
    682 
    683 
    684 -------------------
    685 Instance management
    686 -------------------
    687 
    688 Instances allow one merchant backend to be shared by multiple merchants.
    689 Every backend must have at least one instance, typically the "admin"
    690 instance setup before it can be used to manage inventory or process payments.
    691 
    692 
    693 Setting up instances
    694 ^^^^^^^^^^^^^^^^^^^^
    695 
    696 .. include:: merchant/post-instances.rst
    697 
    698 .. include:: merchant/post-instances-INSTANCE-forgot-password.rst
    699 
    700 .. include:: merchant/post-management-instances.rst
    701 
    702 .. include:: merchant/post-management-instances-INSTANCE-auth.rst
    703 
    704 Access control tokens
    705 ^^^^^^^^^^^^^^^^^^^^^
    706 
    707 .. include:: merchant/post-private-token.rst
    708 
    709 .. include:: merchant/get-private-tokens.rst
    710 
    711 .. include:: merchant/delete-private-tokens-SERIAL.rst
    712 
    713 .. include:: merchant/delete-private-token.rst
    714 
    715 .. include:: merchant/patch-management-instances-INSTANCE.rst
    716 
    717 
    718 Inspecting instances
    719 ^^^^^^^^^^^^^^^^^^^^
    720 
    721 .. _instances:
    722 .. include:: merchant/get-management-instances.rst
    723 
    724 .. include:: merchant/get-management-instances-INSTANCE.rst
    725 
    726 
    727 Getting statistics
    728 ^^^^^^^^^^^^^^^^^^
    729 
    730 .. include:: merchant/get-private-statistics-amount-SLUG.rst
    731 
    732 .. include:: merchant/get-private-statistics-counter-SLUG.rst
    733 
    734 .. include:: merchant/get-private-statistics-report-NAME.rst
    735 
    736 
    737 Deleting instances
    738 ^^^^^^^^^^^^^^^^^^
    739 
    740 .. include:: merchant/delete-management-instances-INSTANCE.rst
    741 
    742 
    743 KYC status checks
    744 ^^^^^^^^^^^^^^^^^
    745 
    746 .. _merchantkycstatus:
    747 
    748 .. include:: merchant/get-private-kyc.rst
    749 
    750 .. include:: merchant/post-private-accept-tos-early.rst
    751 
    752 
    753 -------------
    754 Bank Accounts
    755 -------------
    756 
    757 One or more bank accounts must be associated with an instance
    758 so that the instance can receive payments.  Payments may be made
    759 into any of the active bank accounts of an instance.
    760 
    761 .. include:: merchant/post-private-accounts.rst
    762 
    763 .. include:: merchant/patch-private-accounts-H_WIRE.rst
    764 
    765 .. include:: merchant/get-private-accounts.rst
    766 
    767 .. include:: merchant/get-private-accounts-H_WIRE.rst
    768 
    769 .. include:: merchant/delete-private-accounts-H_WIRE.rst
    770 
    771 .. include:: merchant/post-private-accounts-H_WIRE-kycauth.rst
    772 
    773 
    774 --------------------
    775 Inventory management
    776 --------------------
    777 
    778 .. _inventory:
    779 
    780 Inventory management is an *optional* backend feature that can be used to
    781 manage limited stocks of products and to auto-complete product descriptions in
    782 contracts (such that the frontends have to do less work).  You can use the
    783 Taler merchant backend to process payments *without* using its inventory
    784 management.
    785 
    786 .. _decimal-quantity:
    787 
    788 Decimal quantities
    789 ^^^^^^^^^^^^^^^^^^
    790 
    791 .. ts:def:: DecimalQuantity
    792 
    793   // Fixed-point decimal string in the form "<integer>[.<fraction>]".
    794   // Fractional part has up to six digits.
    795   // "-1" is only valid for fields that explicitly allow "infinity".
    796   // Since protocol **v25**; used in template selection since **v25**.
    797   type DecimalQuantity = string;
    798 
    799 
    800 Managing measurement units
    801 ^^^^^^^^^^^^^^^^^^^^^^^^^^
    802 
    803 .. include:: merchant/get-units.rst
    804 
    805 .. include:: merchant/get-private-units.rst
    806 
    807 .. include:: merchant/get-private-units-UNIT.rst
    808 
    809 .. include:: merchant/post-private-units.rst
    810 
    811 .. include:: merchant/patch-private-units-UNIT.rst
    812 
    813 .. include:: merchant/delete-private-units-UNIT.rst
    814 
    815 
    816 Managing product categories
    817 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    818 
    819 .. include:: merchant/get-private-categories.rst
    820 
    821 .. include:: merchant/get-private-categories-CATEGORY_ID.rst
    822 
    823 .. include:: merchant/post-private-categories.rst
    824 
    825 .. include:: merchant/patch-private-categories-CATEGORY_ID.rst
    826 
    827 .. include:: merchant/delete-private-categories-CATEGORY_ID.rst
    828 
    829 
    830 Managing products in the inventory
    831 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    832 
    833 .. include:: merchant/post-private-products.rst
    834 
    835 .. include:: merchant/patch-private-products-PRODUCT_ID.rst
    836 
    837 .. include:: merchant/get-private-products.rst
    838 
    839 .. include:: merchant/get-private-products-PRODUCT_ID.rst
    840 
    841 .. include:: merchant/delete-private-products-PRODUCT_ID.rst
    842 
    843 
    844 
    845 Providing configuration data for point-of-sale terminals
    846 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    847 
    848 .. include:: merchant/get-private-pos.rst
    849 
    850 
    851 Fetching product images
    852 ^^^^^^^^^^^^^^^^^^^^^^^
    853 
    854 .. include:: merchant/get-products-IMAGE_HASH-image.rst
    855 
    856 
    857 
    858 Reserving inventory
    859 ^^^^^^^^^^^^^^^^^^^
    860 
    861 .. include:: merchant/post-private-products-PRODUCT_ID-lock.rst
    862 
    863 
    864 ------------------
    865 Payment processing
    866 ------------------
    867 
    868 To process Taler payments, a merchant must first set up an order with
    869 the merchant backend. The order is then claimed by a wallet, and
    870 paid by the wallet. The merchant can check the payment status of the
    871 order. Once the order is paid, the merchant may (for a limited time)
    872 grant refunds on the order.
    873 
    874 Creating orders
    875 ^^^^^^^^^^^^^^^
    876 
    877 .. _post-order:
    878 
    879 .. include:: merchant/post-private-orders.rst
    880 
    881 Inspecting orders
    882 ^^^^^^^^^^^^^^^^^
    883 
    884 .. include:: merchant/get-private-orders.rst
    885 
    886 .. include:: merchant/get-private-orders-ORDER_ID.rst
    887 
    888 
    889 .. _collect-order:
    890 
    891 Collecting zero-Taler orders
    892 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    893 
    894 Orders whose Taler ``amount`` is zero, for example because the full total
    895 was settled through ``amount_external``, can be completed by the merchant
    896 backend itself instead of a customer wallet.
    897 
    898 .. include:: merchant/post-private-orders-ORDER_ID-collect.rst
    899 
    900 
    901 .. _private-order-data-cleanup:
    902 
    903 Private order data cleanup
    904 ^^^^^^^^^^^^^^^^^^^^^^^^^^
    905 
    906 Some orders may contain sensitive information that the merchant may not want
    907 to retain after fulfillment, such as the customer's shipping address.  By
    908 initially labeling these order components as forgettable, the merchant can
    909 later tell the backend to forget those details (without changing the hash of
    910 the contract!) to minimize risks from information leakage.
    911 
    912 A member is marked as forgettable by adding its name to the
    913 ``$forgettable`` object in the same parent object.  The value is a random salt
    914 encoded using upper-case Crockford Base32.  Order-creation requests may use
    915 ``true`` instead of a salt; the merchant backend then generates the random
    916 salt before producing the final contract terms.  The boolean form is not valid
    917 in final contract terms.
    918 
    919 Forgetting a member removes both its value and its salt and adds an entry with
    920 the same name to ``$forgotten``.  The entry is a 64-byte HKDF-SHA-512 result,
    921 encoded using upper-case Crockford Base32.  The HKDF input key material is the
    922 RFC 8785 canonical JSON representation of the recursively scrubbed member
    923 value followed by one zero byte.  The HKDF salt is the UTF-8 representation of
    924 the salt string followed by one zero byte, and the HKDF context is empty.  Scrubbing an object
    925 recursively forgets all members marked by ``$forgettable``.  These rules make
    926 the hash of the contract terms invariant under authorized forgetting.
    927 
    928 Objects that participate in this mechanism may use ordinary member names
    929 matching ``^[-0-9A-Za-z_]+$`` and the two reserved names ``$forgettable`` and
    930 ``$forgotten``.  Numbers must be safe integers; floating-point values are not
    931 permitted.
    932 
    933 The following object is the interoperability reference vector::
    934 
    935   {
    936     "k1": 1,
    937     "$forgettable": { "k1": "SALT" },
    938     "k2": {
    939       "n1": true,
    940       "$forgettable": { "n1": "salt" }
    941     },
    942     "k3": { "n1": "string" }
    943   }
    944 
    945 Its Crockford-Base32-encoded contract hash is
    946 ``VDE8JPX0AEEE3EX1K8E11RYEWSZQKGGZCV6BWTE4ST1C8711P7H850Z7F2Q2HSSYETX87ERC2JNHWB7GTDWTDWMM716VKPSRBXD7SRR``.
    947 
    948 .. include:: merchant/patch-private-orders-ORDER_ID-forget.rst
    949 
    950 .. include:: merchant/delete-private-orders-ORDER_ID.rst
    951 
    952 
    953 .. _merchant_refund:
    954 
    955 -----------------
    956 Approving Refunds
    957 -----------------
    958 
    959 .. include:: merchant/post-private-orders-ORDER_ID-refund.rst
    960 
    961 .. include:: merchant/post-private-orders-ORDER_ID-refund-external.rst
    962 
    963 
    964 -----------------------
    965 Tracking Wire Transfers
    966 -----------------------
    967 
    968 This API is used by merchants that want to track the payments from the
    969 exchange to be sure that they have been paid on time. By telling the merchant
    970 backend about all incoming wire transfers, the backend can detect if an
    971 exchange failed to perform a wire transfer that was due.
    972 
    973 
    974 Informing the backend about incoming wire transfers
    975 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    976 
    977 .. include:: merchant/post-private-transfers.rst
    978 
    979 
    980 Querying known wire transfers
    981 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    982 
    983 .. include:: merchant/get-private-transfers.rst
    984 
    985 
    986 
    987 Querying expected wire transfers
    988 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    989 
    990 .. include:: merchant/get-private-incoming.rst
    991 
    992 
    993 .. include:: merchant/get-private-incoming-ID.rst
    994 
    995 
    996 Deleting confirmed wire transfer
    997 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    998 
    999 Deleting a wire transfer can be useful in case of a data entry
   1000 mistake. In particular, if the exchange base URL was entered
   1001 badly, deleting the old entry and adding a correct one is a
   1002 good idea. Note that deleting wire transfers is not possible
   1003 if they were expected.
   1004 
   1005 .. include:: merchant/delete-private-transfers-TID.rst
   1006 
   1007 
   1008 .. _merchant-otp-device-api:
   1009 
   1010 -----------
   1011 OTP Devices
   1012 -----------
   1013 
   1014 OTP devices can be used to allow offline merchants
   1015 to validate that a customer made a payment.
   1016 
   1017 
   1018 .. include:: merchant/post-private-otp-devices.rst
   1019 
   1020 
   1021 .. include:: merchant/patch-private-otp-devices-DEVICE_ID.rst
   1022 
   1023 
   1024 .. include:: merchant/get-private-otp-devices.rst
   1025 
   1026 .. include:: merchant/get-private-otp-devices-DEVICE_ID.rst
   1027 
   1028 .. include:: merchant/delete-private-otp-devices-DEVICE_ID.rst
   1029 
   1030 
   1031 .. _merchant-template-api:
   1032 
   1033 ---------
   1034 Templates
   1035 ---------
   1036 
   1037 The template is a backend feature that is used to allow wallets to create an
   1038 order. This is useful in cases where a store does not have Internet
   1039 connectivity or where a Web site wants to enable payments on a purely static
   1040 Web page (for example to collect donations). In these cases, the GNU Taler
   1041 wallet can be used to setup an order (and then of course pay for it).
   1042 
   1043 Templates can describe a fixed contract (``fixed-order``), an inventory-backed
   1044 cart where the wallet picks products and quantities (``inventory-cart``), or a
   1045 session-based template (``paivana``). The template type controls which fields
   1046 appear in the contract and which inputs are required during instantiation.
   1047 
   1048 The template itself primarily provides order details that cannot be changed
   1049 by the customer when the wallet creates the order.  The idea is that the user
   1050 *may* be prompted to enter certain information, such as the amount to be paid,
   1051 or the order summary (as a reminder to themselves or a message to the store),
   1052 while the template provides all of the other contract details.
   1053 
   1054 The typical user-experience with templates is that the user first scans a QR
   1055 code or clicks on a taler://-URI which contains a ``pay-template`` (see `LSD
   1056 0006 <https://lsd.gnunet.org/lsd0006/>`__). The URI specifies which values the
   1057 user should supply, currently either nothing, the amount, the order summary or
   1058 both.  The URI may also specify defaults or partial defaults for those
   1059 values. After the user has supplied those values, the wallet will use the
   1060 public template API to create the order, then fetch the order details, and
   1061 proceed as if it had been given the respective ``pay`` URI in the first place:
   1062 show the full contract details and allow the user to make a payment.  If the
   1063 user chooses to abort the payment, the wallet should give the user the
   1064 opportunity to edit the values and create another order with different values.
   1065 If the template does not include any values that the user is allowed to edit
   1066 (so it is basically a fixed contract), the wallet should directly create the
   1067 order and immediately proceed to the contract acceptance dialog.
   1068 
   1069 The business process for the templating API is also pretty simple. First, the
   1070 private API is used to setup (or edit) the template, providing all of the
   1071 contract terms that subsequently cannot be changed by the customer/wallet.
   1072 This template data is then stored under the template ID which can be freely
   1073 chosen and must be in URL-encoded format. The SPA should also make it easy
   1074 for the merchant to convert the template ID into a taler://-URI and/or QR code.
   1075 Here, the merchant must additionally specify the defaults (if any) for the
   1076 customer-editable values. Afterwards, the merchant can print out the QR code
   1077 for display at the store, add a link to the taler://-URI and/or embed the
   1078 respective QR-code image into their Web page.
   1079 
   1080 To receive a payment confirmation, the mechant may choose to configure a
   1081 webhook in the merchant backend on the ``pay`` action, for example to send an
   1082 SMS to their mobile phone.  For points-of-sale without a mobile phone or
   1083 Internet connectivity, the OTP mechanism can also be used to confirm payments.
   1084 
   1085 
   1086 Adding templates
   1087 ^^^^^^^^^^^^^^^^
   1088 
   1089 .. include:: merchant/post-private-templates.rst
   1090 
   1091 
   1092 Editing templates
   1093 ^^^^^^^^^^^^^^^^^
   1094 
   1095 .. include:: merchant/patch-private-templates-TEMPLATE_ID.rst
   1096 
   1097 
   1098 Inspecting template
   1099 ^^^^^^^^^^^^^^^^^^^
   1100 
   1101 .. include:: merchant/get-private-templates.rst
   1102 
   1103 .. include:: merchant/get-private-templates-TEMPLATE_ID.rst
   1104 
   1105 
   1106 Removing template
   1107 ^^^^^^^^^^^^^^^^^
   1108 
   1109 .. include:: merchant/delete-private-templates-TEMPLATE_ID.rst
   1110 
   1111 
   1112 Using template
   1113 ^^^^^^^^^^^^^^
   1114 
   1115 .. include:: merchant/get-templates-TEMPLATE_ID.rst
   1116 
   1117 .. include:: merchant/post-templates-TEMPLATE_ID.rst
   1118 
   1119 .. _merchant-webhooks:
   1120 
   1121 --------
   1122 Webhooks
   1123 --------
   1124 
   1125 The webhook is a backend feature that is used to trigger an HTTP request
   1126 to some business logic of the merchant in real-time whenever a specified
   1127 type of event happens.  Depending on the type of the event, webhooks
   1128 may include additional meta-data, such as the amount or contract paid
   1129 by the customer. For details on setup and supported event payloads, see the
   1130 `Merchant manual – Setting up a webhook <https://docs.taler.net/taler-merchant-manual.html#setting-up-a-webhook>`_.
   1131 
   1132 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
   1133 validate their payloads without guesswork:
   1134 
   1135 .. ts:def:: WebhookEventType
   1136 
   1137    enum WebhookEventType {
   1138       ORDER_CREATED = "order_created",
   1139       PAY = "pay",
   1140       REFUND = "refund",
   1141       ORDER_SETTLED = "order_settled",
   1142       CATEGORY_ADDED = "category_added",
   1143       CATEGORY_UPDATED = "category_updated",
   1144       CATEGORY_DELETED = "category_deleted",
   1145       INVENTORY_ADDED = "inventory_added",
   1146       INVENTORY_UPDATED = "inventory_updated",
   1147       INVENTORY_DELETED = "inventory_deleted"
   1148    }
   1149 
   1150 - ``order_created``: fired whenever a new order is created and exposes the ``order_id``, contract, and owning ``instance_id``.
   1151 - ``pay``: emitted after a payment succeeds; the payload contains the paid contract terms and ``order_id``.
   1152 - ``refund``: triggered when a refund is approved and includes timestamp, refunded amount, and reason.
   1153 - ``order_settled``: sent when reconciliation links a wire transfer to an order (includes ``order_id`` and ``wtid``).
   1154 - ``category_added`` / ``category_updated`` / ``category_deleted``: cover lifecycle changes to product categories.
   1155 - ``inventory_added`` / ``inventory_updated`` / ``inventory_deleted``: cover lifecycle changes to inventory items, including descriptive fields and stock state.
   1156 
   1157 For the full payloads associated with each event consult the merchant manual section linked above.
   1158 
   1159 
   1160 Adding webhooks
   1161 ^^^^^^^^^^^^^^^
   1162 
   1163 .. include:: merchant/post-private-webhooks.rst
   1164 
   1165 
   1166 Editing webhooks
   1167 ^^^^^^^^^^^^^^^^
   1168 
   1169 .. include:: merchant/patch-private-webhooks-WEBHOOK_ID.rst
   1170 
   1171 
   1172 Inspecting webhook
   1173 ^^^^^^^^^^^^^^^^^^
   1174 
   1175 .. include:: merchant/get-private-webhooks.rst
   1176 
   1177 .. include:: merchant/get-private-webhooks-WEBHOOK_ID.rst
   1178 
   1179 
   1180 Removing webhook
   1181 ^^^^^^^^^^^^^^^^
   1182 
   1183 .. include:: merchant/delete-private-webhooks-WEBHOOK_ID.rst
   1184 
   1185 
   1186 -------
   1187 Reports
   1188 -------
   1189 
   1190 Reports are a backend feature that is used to send periodic
   1191 reports to the merchant. Reports are sent using notification
   1192 helper programs which must be configured for each merchant backend.
   1193 
   1194 Since protocol **v25**.
   1195 
   1196 Generating reports
   1197 ^^^^^^^^^^^^^^^^^^
   1198 
   1199 .. include:: merchant/post-reports-REPORT_ID.rst
   1200 
   1201 
   1202 Scheduling periodic reports
   1203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1204 
   1205 .. include:: merchant/post-private-reports.rst
   1206 
   1207 
   1208 Editing scheduled reports
   1209 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1210 
   1211 .. include:: merchant/patch-private-reports-REPORT_ID.rst
   1212 
   1213 
   1214 Inspecting reporting schedules
   1215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1216 
   1217 .. include:: merchant/get-private-reports.rst
   1218 
   1219 .. include:: merchant/get-private-reports-REPORT_ID.rst
   1220 
   1221 
   1222 Removing scheduled reports
   1223 ^^^^^^^^^^^^^^^^^^^^^^^^^^
   1224 
   1225 .. include:: merchant/delete-private-reports-REPORT_ID.rst
   1226 
   1227 
   1228 Report test sends and delivery history
   1229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1230 
   1231 .. include:: merchant/report-deliveries.rst
   1232 
   1233 
   1234 --------------
   1235 Product groups
   1236 --------------
   1237 
   1238 Product groups are used to manage taxes. Each product is in
   1239 exactly one group and that group is typically used to determine
   1240 the applicable tax rules. Products that are not assigned explicitly
   1241 to a group are considered to be in the *default* product group.
   1242 
   1243 Product groups are different from categories as a product can be
   1244 in multiple categories. Furthermore, categories are used to make
   1245 it easier to find products in user interfaces, while product
   1246 groups are used to make it easier to manage taxes.
   1247 
   1248 Since protocol **v25**.
   1249 
   1250 Adding groups
   1251 ^^^^^^^^^^^^^
   1252 
   1253 .. include:: merchant/post-private-groups.rst
   1254 
   1255 
   1256 Editing groups
   1257 ^^^^^^^^^^^^^^
   1258 
   1259 .. include:: merchant/patch-private-groups-GROUP_ID.rst
   1260 
   1261 
   1262 Inspecting groups
   1263 ^^^^^^^^^^^^^^^^^
   1264 
   1265 .. include:: merchant/get-private-groups.rst
   1266 
   1267 
   1268 Removing groups
   1269 ^^^^^^^^^^^^^^^
   1270 
   1271 .. include:: merchant/delete-private-groups-GROUP_ID.rst
   1272 
   1273 
   1274 ----
   1275 Pots
   1276 ----
   1277 
   1278 Pots are a backend feature that is used for accounting. Transacted
   1279 amounts can be assigned into pots, for example to separate out
   1280 tips and taxes from revenue for reporting.
   1281 
   1282 Since protocol **v25**.
   1283 
   1284 Adding pots
   1285 ^^^^^^^^^^^
   1286 
   1287 .. include:: merchant/post-private-pots.rst
   1288 
   1289 
   1290 Editing pots
   1291 ^^^^^^^^^^^^
   1292 
   1293 .. include:: merchant/patch-private-pots-POT_ID.rst
   1294 
   1295 
   1296 Inspecting pots
   1297 ^^^^^^^^^^^^^^^
   1298 
   1299 .. include:: merchant/get-private-pots.rst
   1300 
   1301 .. include:: merchant/get-private-pots-POT_ID.rst
   1302 
   1303 
   1304 Removing pots
   1305 ^^^^^^^^^^^^^
   1306 
   1307 .. include:: merchant/delete-private-pots-POT_ID.rst
   1308 
   1309 
   1310 ----------------------------------------
   1311 Token Families: Subscriptions, Discounts
   1312 ----------------------------------------
   1313 
   1314 This API provides functionalities for the issuance, management, and revocation
   1315 of token families. Tokens facilitate the implementation of subscriptions and
   1316 discounts, engaging solely the merchant and the user. Each token family
   1317 encapsulates details pertaining to its respective tokens, guiding the merchant's
   1318 backend on the appropriate processing and handling.
   1319 
   1320 
   1321 Creating token families
   1322 ^^^^^^^^^^^^^^^^^^^^^^^
   1323 
   1324 .. include:: merchant/post-private-tokenfamilies.rst
   1325 
   1326 
   1327 Updating token families
   1328 ^^^^^^^^^^^^^^^^^^^^^^^
   1329 
   1330 .. include:: merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
   1331 
   1332 
   1333 
   1334 Inspecting token families
   1335 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1336 
   1337 .. include:: merchant/get-private-tokenfamilies.rst
   1338 
   1339 .. include:: merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
   1340 
   1341 
   1342 
   1343 Deleting token families
   1344 ^^^^^^^^^^^^^^^^^^^^^^^
   1345 
   1346 .. include:: merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
   1347 
   1348 
   1349 .. _merchant-fountain-api:
   1350 
   1351 -----------------------------------------
   1352 Fountains: Promotional Token Distribution
   1353 -----------------------------------------
   1354 
   1355 A fountain is a bearer credential that entitles a wallet to withdraw
   1356 blind-signed promotional tokens for a set of token families without
   1357 creating an order per withdrawal.  An institution can distribute a fountain
   1358 to one recipient or share it for a campaign
   1359 (see :doc:`DD 98 </design-documents/098-token-fountains>`).
   1360 
   1361 Wallets receive the credential as a
   1362 ``taler://fountain/$MERCHANT_HOST[/$INSTANCE_PATH]/$FOUNTAIN_ID/$FOUNTAIN_SECRET``
   1363 URI. All fountain endpoints are available since protocol
   1364 **v43**.
   1365 
   1366 Managing fountains
   1367 ^^^^^^^^^^^^^^^^^^
   1368 
   1369 .. include:: merchant/post-private-fountains.rst
   1370 
   1371 .. include:: merchant/patch-private-fountains-FOUNTAIN_ID.rst
   1372 
   1373 .. include:: merchant/get-private-fountains.rst
   1374 
   1375 .. include:: merchant/get-private-fountains-FOUNTAIN_ID.rst
   1376 
   1377 .. include:: merchant/delete-private-fountains-FOUNTAIN_ID.rst
   1378 
   1379 
   1380 Wallet fountain API
   1381 ^^^^^^^^^^^^^^^^^^^
   1382 
   1383 .. include:: merchant/get-fountain-info.rst
   1384 
   1385 .. include:: merchant/post-fountain-withdraw.rst
   1386 
   1387 
   1388 -----------------------
   1389 Donau Charity Instances
   1390 -----------------------
   1391 
   1392 A merchant instance can link one or more **Donau charity instances**.
   1393 Each link associates the instance’s own public key with a charity registered
   1394 at some Donau service.  These links are managed under the private API.
   1395 
   1396 Permissions
   1397 ^^^^^^^^^^^
   1398 
   1399 * ``donau-read``  — list linked charities.
   1400 * ``donau-write`` — add or remove charity links.
   1401 
   1402 See :ref:`Scopes <merchant-api-scopes>` for how permissions relate to the
   1403 scope of an access token.
   1404 
   1405 Listing charity instances
   1406 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1407 
   1408 .. include:: merchant/get-private-donau.rst
   1409 
   1410 Adding a charity instance
   1411 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1412 
   1413 .. include:: merchant/post-private-donau.rst
   1414 
   1415 Deleting a charity instance
   1416 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1417 
   1418 .. include:: merchant/delete-private-donau-DONAU_SERIAL.rst
   1419 
   1420 
   1421 ------------------
   1422 The Contract Terms
   1423 ------------------
   1424 
   1425 This section describes the overall structure of templates, orders and contract
   1426 terms that are the foundation for Taler payments.
   1427 
   1428 .. _template-contract-details:
   1429 
   1430 Templates
   1431 ^^^^^^^^^
   1432 
   1433 The template contract is like the most raw form where many choices are still
   1434 open or deferred.
   1435 
   1436 
   1437 .. ts:def:: TemplateContractDetails
   1438 
   1439   type TemplateContractDetails = (TemplateContractFixedOrder | TemplateContractInventoryCart | TemplateContractPaivana) & TemplateContractCommon;
   1440 
   1441 .. ts:def:: TemplateContractCommon
   1442 
   1443   interface TemplateContractCommon {
   1444     // Template type to apply. Defaults to "fixed-order" if omitted.
   1445     // Prescribes which interface has to be followed
   1446     // Since protocol **v25**.
   1447     template_type?: TemplateType;
   1448 
   1449     // Human-readable summary for the template.
   1450     summary?: string;
   1451 
   1452     // Required currency for payments to the template.
   1453     // This parameter is optional and should not be present
   1454     // if "amount" is given.
   1455     currency?: string;
   1456 
   1457     // Lower bound (inclusive) on amounts the client gets to choose
   1458     // when instantiating this template.  Excludes any tip.  Only
   1459     // amounts the client had an influence on are checked against
   1460     // this bound: the amount given in the request for a "fixed-order"
   1461     // template, the total of the selected products for an
   1462     // "inventory-cart" template, and the amount of an editable choice
   1463     // for a "paivana" template.  Requires "currency" to be given and
   1464     // to match, must be in the same currency as "max_amount", and
   1465     // must not exceed it.
   1466     // Since protocol **v34**.
   1467     min_amount?: Amount;
   1468 
   1469     // Upper bound (inclusive) on amounts the client gets to choose
   1470     // when instantiating this template.  Excludes any tip.  Checked
   1471     // against the same amounts as "min_amount".  Requires "currency"
   1472     // to be given and to match.
   1473     // Since protocol **v34**.
   1474     max_amount?: Amount;
   1475 
   1476     // Time available to pay before the order expires unpaid.  If omitted or
   1477     // zero, the instance's default pay delay is used.  "forever" is invalid.
   1478     pay_duration?: RelativeTime;
   1479 
   1480     // How long will customers have to access / read / pick-up
   1481     // the resource they are buying? Will turn into
   1482     // max_pickup_time in the contract for every template type,
   1483     // measured from order creation (not from payment or a repeat visit).
   1484     // Optional; if omitted or "forever", access has no deadline.
   1485     // Zero gives an immediately expired access window.
   1486     // Since protocol **v29**.
   1487     max_pickup_duration?: RelativeTime;
   1488 
   1489     // Minimum age buyer must have (in years). Default is 0.
   1490     minimum_age?: Integer;
   1491 
   1492     // Inventory-cart: request a tip during instantiation.
   1493     // Since protocol **v25**.
   1494     request_tip?: boolean;
   1495   }
   1496 
   1497 .. ts:def:: TemplateType
   1498 
   1499   enum TemplateType {
   1500     FIXED_ORDER = "fixed-order",
   1501     INVENTORY_CART = "inventory-cart",
   1502     PAIVANA = "paivana"
   1503   }
   1504 
   1505 .. ts:def:: TemplateContractFixedOrder
   1506 
   1507   interface TemplateContractFixedOrder {
   1508 
   1509     // The price is imposed by the merchant and cannot be changed by the customer.
   1510     // This parameter is optional.
   1511     amount?: Amount;
   1512 
   1513   }
   1514 
   1515 .. ts:def:: TemplateContractInventoryCart
   1516 
   1517   interface TemplateContractInventoryCart {
   1518 
   1519     // Inventory-cart: allow any inventory item to be selected.
   1520     // Since protocol **v25**.
   1521     selected_all?: boolean;
   1522 
   1523     // Inventory-cart: only products in these categories are selectable.
   1524     // Since protocol **v25**.
   1525     selected_categories?: Integer[];
   1526 
   1527     // Inventory-cart: only these products are selectable.
   1528     // Since protocol **v25**.
   1529     selected_products?: string[];
   1530 
   1531     // Inventory-cart: require exactly one selection entry.
   1532     // Since protocol **v25**.
   1533     choose_one?: boolean;
   1534 
   1535     // Inventory-cart: backend-provided payload with selectable data.
   1536     // Only present in ``GET /templates/$TEMPLATE_ID`` responses.
   1537     // Since protocol **v25**.
   1538     inventory_payload?: InventoryPayload;
   1539  }
   1540 
   1541 .. ts:def:: TemplateContractPaivana
   1542 
   1543   interface TemplateContractPaivana {
   1544 
   1545     // POSIX extended regular expression over URLs for which
   1546     // this template is valid.  Matched against the absolute
   1547     // URL, and anchored: it must match that URL in its
   1548     // entirety, not merely occur within it.
   1549     // Optional, if not given all URLs are accepted.
   1550     // Since protocol **v25**.
   1551     website_regex?: string;
   1552 
   1553     // Methods to pay for the contract.
   1554     choices: TemplateOrderChoice[];
   1555  }
   1556 
   1557 The backend only stores ``website_regex``; it is the paywall proxy
   1558 reading these templates that evaluates it.  ``paivana-httpd`` matches
   1559 it against the **absolute** URL of the request (``BASE_URL`` or the
   1560 scheme and ``Host`` of the request, followed by the path) and anchors
   1561 it, so an expression written against the path alone, or meant as a
   1562 substring rule, will not apply.  See :ref:`Paivana-Templates` in the
   1563 :doc:`Paivana operator manual <../taler-paivana-manual>` for the
   1564 matching rules and worked examples.
   1565 
   1566 If exactly one of the ``choices`` of a Paivana template has
   1567 ``editable_amount`` set, the template may also carry an ``amount`` in its
   1568 ``editable_defaults`` to tell the user interface to offer a single amount
   1569 field with that default; the client then submits it as the ``amount`` of
   1570 the `UsingTemplateCommonRequest`.  With more than one editable choice, the
   1571 defaults are the ``amount`` values of the choices themselves and the client
   1572 must use ``choice_amounts``.
   1573 
   1574 .. _template-choice:
   1575 
   1576 Template Choices
   1577 ^^^^^^^^^^^^^^^^
   1578 
   1579 The `OrderChoice` object describes a possible choice within an order. The
   1580 choice is done by the wallet and consists of in- and outputs. In the example
   1581 of buying an article, the merchant could present the customer with the
   1582 choice to use a valid subscription token or pay using a gift
   1583 voucher. Available since protocol **v21**.
   1584 
   1585 .. ts:def:: OrderChoice
   1586 
   1587   interface OrderChoice {
   1588     // Total price for the choice. The exchange will subtract deposit
   1589     // fees from that amount before transferring it to the merchant.
   1590     amount: Amount;
   1591 
   1592     // Optional tip amount. Must match the currency of ``amount``.
   1593     // Since protocol **v25**.
   1594     tip?: Amount;
   1595 
   1596     // Human readable description of the semantics of the choice
   1597     // within the contract to be shown to the user at payment.
   1598     description?: string;
   1599 
   1600     // Map from IETF 47 language tags to localized descriptions.
   1601     description_i18n?: { [lang_tag: string]: string };
   1602 
   1603     // Inputs that must be provided by the customer, if this choice is selected.
   1604     // Defaults to empty array if not specified.
   1605     inputs?: OrderInput[];
   1606 
   1607     // Outputs provided by the merchant, if this choice is selected.
   1608     // Defaults to empty array if not specified.
   1609     outputs?: OrderOutput[];
   1610 
   1611     // Maximum total deposit fee accepted by the merchant for this contract.
   1612     // Overrides defaults of the merchant instance.
   1613     max_fee?: Amount;
   1614   }
   1615 
   1616 A choice of a *template* contract may additionally allow the client to
   1617 replace the amount when the template is instantiated.
   1618 
   1619 .. ts:def:: TemplateOrderChoice
   1620 
   1621   interface TemplateOrderChoice extends OrderChoice {
   1622     // If true, the client may replace "amount" when instantiating
   1623     // the template; "amount" then merely provides the default.  The
   1624     // client may only change the value, never the currency.  The
   1625     // resulting amount is subject to the "min_amount" and
   1626     // "max_amount" bounds of the template (if any).
   1627     // Defaults to false, in which case the amount is fixed by the
   1628     // merchant.
   1629     // Since protocol **v34**.
   1630     editable_amount?: boolean;
   1631   }
   1632 
   1633 .. ts:def:: OrderInput
   1634 
   1635   // For now, only token inputs are supported.
   1636   type OrderInput = OrderInputToken;
   1637 
   1638 .. ts:def:: OrderInputToken
   1639 
   1640   interface OrderInputToken {
   1641 
   1642     // Token input.
   1643     type: "token";
   1644 
   1645     // Token family slug as configured in the merchant backend. Slug is unique
   1646     // across all configured tokens of a merchant.
   1647     token_family_slug: Slug;
   1648 
   1649     // How many units of the input are required.
   1650     // Defaults to 1 if not specified. Output with count == 0 are ignored by
   1651     // the merchant backend.
   1652     count?: Integer;
   1653 
   1654   }
   1655 
   1656 .. ts:def:: OrderOutput
   1657 
   1658   type OrderOutput = OrderOutputToken | OrderOutputTaxReceipt;
   1659 
   1660 .. ts:def:: OrderOutputToken
   1661 
   1662   interface OrderOutputToken {
   1663 
   1664     // Token output.
   1665     type: "token";
   1666 
   1667     // Token family slug as configured in the merchant backend. Slug is unique
   1668     // across all configured tokens of a merchant.
   1669     token_family_slug: Slug;
   1670 
   1671     // How many units of the output are issued by the merchant.
   1672     // Defaults to 1 if not specified. Output with count == 0 are ignored by
   1673     // the merchant backend.
   1674     count?: Integer;
   1675 
   1676     // When should the output token be valid. Can be specified if the
   1677     // desired validity period should be in the future (like selling
   1678     // a subscription for the next month). Optional. If not given,
   1679     // the validity is supposed to be "now" (time of order creation).
   1680     valid_at?: Timestamp;
   1681 
   1682   }
   1683 
   1684 .. ts:def:: OrderOutputTaxReceipt
   1685 
   1686   interface OrderOutputTaxReceipt {
   1687 
   1688     // Tax receipt output.
   1689     type: "tax-receipt";
   1690 
   1691     // Donation amount. Useful if the donation is only for
   1692     // part of the total.
   1693     // Optional, if not given the purchase total amount is
   1694     // assumed to be the donation amount.
   1695     amount?: Amount;
   1696   }
   1697 
   1698 .. _contract-base-terms:
   1699 
   1700 Contract base terms
   1701 ^^^^^^^^^^^^^^^^^^^
   1702 
   1703 These are the basic terms that are shared terms between orders and contracts
   1704 and basically present (or optional) all the time.
   1705 
   1706 .. ts:def:: ContractBaseTerms
   1707 
   1708   interface ContractBaseTerms {
   1709     // Human-readable description of the whole purchase.
   1710     summary: string;
   1711 
   1712     // Map from IETF BCP 47 language tags to localized summaries.
   1713     summary_i18n?: { [lang_tag: string]: string };
   1714 
   1715     // Unique, free-form identifier for the proposal.
   1716     // Must be unique within a merchant instance.
   1717     // For merchants that do not store proposals in their DB
   1718     // before the customer paid for them, the ``order_id`` can be used
   1719     // by the frontend to restore a proposal from the information
   1720     // encoded in it (such as a short product identifier and timestamp).
   1721     order_id: Slug;
   1722 
   1723     // URL where the same contract could be ordered again (if
   1724     // available). Returned also at the public order endpoint
   1725     // for people other than the actual buyer (hence public,
   1726     // in case order IDs are guessable).
   1727     public_reorder_url?: WebURL;
   1728 
   1729     // URL that will show that the order was successful after
   1730     // it has been paid for.  Optional, but either ``fulfillment_url``
   1731     // or ``fulfillment_message`` must be specified in every
   1732     // contract terms.
   1733     //
   1734     // If a non-unique fulfillment URL is used, a customer can only
   1735     // buy the order once and will be redirected to a previous purchase
   1736     // when trying to buy an order with the same fulfillment URL a second
   1737     // time, while the previous purchase's max_pickup_time still permits
   1738     // access. This is useful for digital goods that a customer should
   1739     // be able to repeatedly download during the purchased access period.
   1740     //
   1741     // For orders where the customer is expected to be able to make
   1742     // repeated purchases (for equivalent goods), the fulfillment URL
   1743     // should be made unique for every order. The easiest way to do
   1744     // this is to include a unique order ID in the fulfillment URL.
   1745     //
   1746     // When POSTing to the merchant, the placeholder text "${ORDER_ID}"
   1747     // is be replaced with the actual order ID (useful if the
   1748     // order ID is generated server-side and needs to be
   1749     // in the URL). Note that this placeholder can only be used once.
   1750     // Front-ends may use other means to generate a unique fulfillment URL.
   1751     // Because of that placeholder, the value given here is merely a
   1752     // string and not yet a `WebURL`; only after the substitution has
   1753     // been performed is the result a `WebURL`.
   1754     fulfillment_url?: string;
   1755 
   1756     // Message shown to the customer after paying for the order.
   1757     // Either fulfillment_url or fulfillment_message must be specified.
   1758     fulfillment_message?: string;
   1759 
   1760     // Map from IETF BCP 47 language tags to localized fulfillment
   1761     // messages.
   1762     fulfillment_message_i18n?: { [lang_tag: string]: string };
   1763 
   1764     // Delivery location for (all!) products.
   1765     delivery_location?: Location;
   1766 
   1767     // Time indicating when the order should be delivered.
   1768     // May be overwritten by individual products.
   1769     delivery_date?: Timestamp;
   1770 
   1771     // Specifies for how long the wallet should try to get an
   1772     // automatic refund for the purchase. If this field is
   1773     // present, the wallet should wait for a few seconds after
   1774     // the purchase and then automatically attempt to obtain
   1775     // a refund.  The wallet should probe until "delay"
   1776     // after the payment was successful (i.e. via long polling
   1777     // or via explicit requests with exponential back-off).
   1778     //
   1779     // In particular, if the wallet is offline
   1780     // at that time, it MUST repeat the request until it gets
   1781     // one response from the merchant after the delay has expired.
   1782     // If the refund is granted, the wallet MUST automatically
   1783     // recover the payment.  This is used in case a merchant
   1784     // knows that it might be unable to satisfy the contract and
   1785     // desires for the wallet to attempt to get the refund without any
   1786     // customer interaction.  Note that it is NOT an error if the
   1787     // merchant does not grant a refund.
   1788     auto_refund?: RelativeTime;
   1789 
   1790     // Extra data that is only interpreted by the merchant frontend.
   1791     // Useful when the merchant needs to store extra information on a
   1792     // contract without storing it separately in their database.
   1793     // Must really be an Object (not a string, integer, float or array).
   1794     extra?: Object;
   1795 
   1796     // Minimum age the buyer must have (in years). Default is 0.
   1797     // This value is at least as large as the maximum over all
   1798     // mimimum age requirements of the products in this contract.
   1799     // It might also be set independent of any product, due to
   1800     // legal requirements.
   1801     minimum_age?: Integer;
   1802 
   1803     // Default money pot to use for this order, applies to the
   1804     // amount remaining that was not claimed by money pots of
   1805     // products or taxes.  Not useful to wallets, only for
   1806     // merchant-internal accounting.  If not given, the remaining
   1807     // account is simply not accounted for in any money pot.
   1808     // Since **v25**.
   1809     order_default_money_pot?: Integer;
   1810 
   1811     // Latest time until which the good or service specified in the
   1812     // contract may be picked up by the customer. This is usually
   1813     // for digital goods where the customer has a finite window
   1814     // for downloading the resource(s). Absent or "never" means unlimited.
   1815     // Once this time is reached, wallets must not reuse the purchase to
   1816     // satisfy a new order with the same fulfillment_url. A new payment
   1817     // requires the customer's confirmation.
   1818     max_pickup_time?: Timestamp;
   1819 
   1820   }
   1821 
   1822 .. _order-details:
   1823 
   1824 Orders
   1825 ^^^^^^
   1826 
   1827 The `Order` object represents the starting point for new `ContractTerms`.
   1828 After validating and sanitizing all inputs, the merchant backend will add
   1829 additional information to the order and create a new `ContractTerms` object
   1830 that will be stored in the database.
   1831 
   1832 .. ts:def:: Order
   1833 
   1834   type Order = ContractBaseTerms & (OrderV0 | OrderV1) & OrderCommon;
   1835 
   1836 .. ts:def:: OrderV0
   1837 
   1838   interface OrderV0 {
   1839     // Optional, defaults to 0 if not set.
   1840     version?: 0;
   1841 
   1842     // Total price for the transaction, including tip. The exchange will
   1843     // subtract deposit fees from that amount before transferring it to
   1844     // the merchant.
   1845     amount: Amount;
   1846 
   1847     // Optional tip amount. Must match the currency of ``amount``.
   1848     // Since protocol **v25**.
   1849     tip?: Amount;
   1850 
   1851     // Maximum total deposit fee accepted by the merchant for this contract.
   1852     // Overrides defaults of the merchant instance.
   1853     max_fee?: Amount;
   1854   }
   1855 
   1856 .. ts:def:: OrderV1
   1857 
   1858   interface OrderV1 {
   1859     // Version 1 order support discounts and subscriptions.
   1860     // https://docs.taler.net/design-documents/046-mumimo-contracts.html
   1861     // @since protocol **v21**
   1862     version: 1;
   1863 
   1864     // List of contract choices that the customer can select from.
   1865     // @since protocol **v21**
   1866     choices: OrderChoice[];
   1867   }
   1868 
   1869 
   1870 .. ts:def:: OrderCommon
   1871 
   1872   interface OrderCommon {
   1873 
   1874     // List of products that are part of the purchase.
   1875     products?: ProductEntry[];
   1876 
   1877     // After this deadline has passed, no refunds will be accepted.
   1878     // Overrides deadline calculated from ``refund_delay`` in
   1879     // `PostOrderRequest`.
   1880     // A value of "never" is not allowed.
   1881     refund_deadline?: Timestamp;
   1882 
   1883     // After this deadline, the merchant won't accept payments for the contract.
   1884     // Overrides deadline calculated from default pay delay configured in
   1885     // merchant backend.
   1886     // A value of "never" is not allowed.
   1887     pay_deadline?: Timestamp;
   1888 
   1889     // Transfer deadline for the exchange. Must be in the deposit permissions
   1890     // of coins used to pay for this order.
   1891     // Overrides deadline calculated from default wire transfer delay
   1892     // configured in merchant backend. Must be after refund deadline.
   1893     // A value of "never" is not allowed.
   1894     wire_transfer_deadline?: Timestamp;
   1895 
   1896     // Payments for this order that were settled outside of Taler,
   1897     // for example in cash or by card. The ``amount`` field above (or
   1898     // the selected choice's ``amount`` for v1 orders) remains the
   1899     // amount paid with Taler; the full order total is the sum of that
   1900     // amount and all entries here. If present, all entries and (for
   1901     // v1 orders) all choices must use the currency of the Taler
   1902     // ``amount``. Never contains a ``taler`` entry.
   1903     // @since protocol **v42**.
   1904     amount_external?: ExternalPaymentInfo[];
   1905 
   1906   }
   1907 
   1908 .. ts:def:: ExternalPaymentInfo
   1909 
   1910   interface ExternalPaymentInfo {
   1911     // External payment method, for example "cash" or "card".
   1912     // Must be a stable, non-empty identifier of ASCII
   1913     // alphanumerics and "-", and must never be "taler".
   1914     method: string;
   1915 
   1916     // Identifier of the payment action within the order, unique
   1917     // among the entries of this ``amount_external`` array.
   1918     // Examples: "cash1", "card1", "card2".
   1919     id: string;
   1920 
   1921     // Amount covered by this payment action. Must use the same
   1922     // currency as the Taler ``amount`` of the order.
   1923     amount: Amount;
   1924 
   1925     // Additional method-specific fields for reconciliation or audit,
   1926     // for example a cashier number, terminal identifier or
   1927     // authorization code. These must be flat scalar values (no
   1928     // nested objects or arrays) so that the merchant portal can
   1929     // render ``amount_external`` as a generic table.
   1930     [field: string]: string | Amount | Integer | boolean | null;
   1931   }
   1932 
   1933 .. _product-entry:
   1934 
   1935 Product entries
   1936 ^^^^^^^^^^^^^^^
   1937 
   1938 .. ts:def:: ProductEntry
   1939 
   1940   type ProductEntry = (ProductSold | MinimalInventoryProduct);
   1941 
   1942 
   1943 The following `MinimalInventoryProduct` can be provided if the parts of the
   1944 order are inventory-based, that is if the `PostOrderRequest` uses
   1945 ``inventory_products``. For such products, which must be in the backend's
   1946 inventory, the backend can automatically fill in the amount and other details
   1947 about the product that are known to it from its ``products`` table.  Note that
   1948 the ``inventory_products`` will be appended to the list of ``products`` that
   1949 the frontend already put into the ``order``.  So the frontend can sell
   1950 additional non-inventory products together with ``inventory_products``.  Note
   1951 that the backend will NOT update the ``amount`` of the ``order``, so the
   1952 frontend must already have calculated the total price --- including the
   1953 ``inventory_products``.
   1954 
   1955 .. ts:def:: MinimalInventoryProduct
   1956 
   1957   // Note that if the frontend does give details beyond these,
   1958   // it will override those details (including price or taxes)
   1959   // that the backend would otherwise fill in via the inventory.
   1960   interface MinimalInventoryProduct {
   1961 
   1962     // Which product is requested (here mandatory!).
   1963     product_id: Slug;
   1964 
   1965     // Legacy integer quantity.
   1966     // Deprecated since **v25**;
   1967     // defaults to 1 if both ``quantity`` and ``unit_quantity`` are absent.
   1968     quantity?: Integer;
   1969 
   1970     // Preferred quantity string using "<integer>[.<fraction>]" syntax.
   1971     // @since **v25**;
   1972     unit_quantity?: string
   1973 
   1974     // Money pot to use for this product, overrides value from
   1975     // the inventory if given.
   1976     // Since **v25**.
   1977     product_money_pot?: Integer;
   1978 
   1979   }
   1980 
   1981 Clients must supply either ``quantity`` or ``unit_quantity`` when referencing
   1982 inventory products. If both are missing the backend assumes a quantity of
   1983 one. ``unit_quantity`` follows the same decimal-string rules as
   1984 ``unit_total_stock``.
   1985 
   1986 
   1987 .. _contract-token-family:
   1988 
   1989 Contract token family
   1990 ^^^^^^^^^^^^^^^^^^^^^
   1991 
   1992 The contract token family provides additional meta-data about
   1993 input and output tokens associated with a particular choice of
   1994 payment.
   1995 
   1996 .. ts:def:: ContractTokenFamily
   1997 
   1998   interface ContractTokenFamily {
   1999     // Human-readable name of the token family.
   2000     name: string;
   2001 
   2002     // Human-readable description of the semantics of
   2003     // this token family (for display).
   2004     description: string;
   2005 
   2006     // Map from IETF BCP 47 language tags to localized descriptions.
   2007     description_i18n?: { [lang_tag: string]: string };
   2008 
   2009     // Public keys used to validate tokens issued by this token family.
   2010     keys: TokenIssuePublicKey[];
   2011 
   2012     // Kind-specific information of the token
   2013     details: ContractTokenDetails;
   2014 
   2015     // Must a wallet understand this token type to
   2016     // process contracts that use or issue it?
   2017     critical: boolean;
   2018   };
   2019 
   2020 .. ts:def:: TokenIssuePublicKey
   2021 
   2022   type TokenIssuePublicKey =
   2023     | TokenIssueRsaPublicKey
   2024     | TokenIssueCsPublicKey;
   2025 
   2026 .. ts:def:: TokenIssueRsaPublicKey
   2027 
   2028   interface TokenIssueRsaPublicKey {
   2029     cipher: "RSA";
   2030 
   2031     // RSA public key.
   2032     rsa_pub: RsaPublicKey;
   2033 
   2034     // Start time of this key's signatures validity period.
   2035     signature_validity_start: Timestamp;
   2036 
   2037     // End time of this key's signatures validity period.
   2038     signature_validity_end: Timestamp;
   2039 
   2040   }
   2041 
   2042 .. ts:def:: TokenIssueCsPublicKey
   2043 
   2044   interface TokenIssueCsPublicKey {
   2045     cipher: "CS";
   2046 
   2047     // CS public key.
   2048     cs_pub: Cs25519Point;
   2049 
   2050     // Start time of this key's signatures validity period.
   2051     signature_validity_start: Timestamp;
   2052 
   2053     // End time of this key's signatures validity period.
   2054     signature_validity_end: Timestamp;
   2055 
   2056   }
   2057 
   2058 .. ts:def:: ContractTokenDetails
   2059 
   2060   type ContractTokenDetails =
   2061     | ContractSubscriptionTokenDetails
   2062     | ContractDiscountTokenDetails;
   2063 
   2064 .. ts:def:: ContractSubscriptionTokenDetails
   2065 
   2066   interface ContractSubscriptionTokenDetails {
   2067     class: "subscription";
   2068 
   2069     // Array of domain names where this subscription
   2070     // can be safely used (e.g. the issuer warrants that
   2071     // these sites will re-issue tokens of this type
   2072     // if the respective contract says so).  May contain
   2073     // "*" for any domain or subdomain.
   2074     trusted_domains: string[];
   2075   };
   2076 
   2077 .. ts:def:: ContractDiscountTokenDetails
   2078 
   2079   interface ContractDiscountTokenDetails {
   2080     class: "discount";
   2081 
   2082     // Array of domain names where this discount token
   2083     // is intended to be used.  May contain "*" for any
   2084     // domain or subdomain.  Users should be warned about
   2085     // sites proposing to consume discount tokens of this
   2086     // type that are not in this list that the merchant
   2087     // is accepting a coupon from a competitor and thus
   2088     // may be attaching different semantics (like get 20%
   2089     // discount for my competitors 30% discount token).
   2090     expected_domains: string[];
   2091   };
   2092 
   2093 
   2094 .. _proto-contract-terms:
   2095 
   2096 Proto contract terms
   2097 ^^^^^^^^^^^^^^^^^^^^
   2098 
   2099 The proto-contract terms are the proposed contract that a merchant
   2100 is about to present to a wallet, but that lacks the wallet's *nonce*
   2101 and is thus not yet buyer-specific.
   2102 
   2103 
   2104 
   2105 .. ts:def:: ProtoContractTerms
   2106 
   2107   type ProtoContractTerms = ContractBaseTerms & (ContractTermsV0 | ContractTermsV1) & ContractTermsCommon;
   2108 
   2109 
   2110 .. ts:def:: ContractTermsV0
   2111 
   2112   interface ContractTermsV0 {
   2113     // Defaults to version 0.
   2114     version?: 0;
   2115 
   2116     // Total price for the transaction, including tip.
   2117     // The exchange will subtract deposit fees from that amount
   2118     // before transferring it to the merchant.
   2119     amount: Amount;
   2120 
   2121     // Optional tip amount. Must match the currency of ``amount``.
   2122     // Since protocol **v25**.
   2123     tip?: Amount;
   2124 
   2125     // Maximum total deposit fee accepted by the merchant for this contract.
   2126     // Overrides defaults of the merchant instance.
   2127     max_fee: Amount;
   2128   }
   2129 
   2130 .. ts:def:: ContractTermsV1
   2131 
   2132   interface ContractTermsV1 {
   2133     // Version 1 supports the ``choices`` array, see
   2134     // https://docs.taler.net/design-documents/046-mumimo-contracts.html.
   2135     // @since protocol **v21**
   2136     version: 1;
   2137 
   2138     // List of contract choices that the customer can select from.
   2139     // @since protocol **v21**
   2140     choices: ContractChoice[];
   2141 
   2142     // Map of storing metadata and issue keys of
   2143     // token families referenced in this contract.
   2144     // @since protocol **v21**
   2145     token_families: { [token_family_slug: Slug]: ContractTokenFamily };
   2146   }
   2147 
   2148 .. ts:def:: ContractTermsCommon
   2149 
   2150   interface ContractTermsCommon {
   2151 
   2152     // Time when this contract was generated.
   2153     timestamp: Timestamp;
   2154 
   2155     // After this deadline has passed, no refunds will be accepted.
   2156     refund_deadline: Timestamp;
   2157 
   2158     // After this deadline, the merchant won't accept payments for the contract.
   2159     pay_deadline: Timestamp;
   2160 
   2161     // Transfer deadline for the exchange.  Must be in the
   2162     // deposit permissions of coins used to pay for this order.
   2163     wire_transfer_deadline: Timestamp;
   2164 
   2165     // Merchant's public key used to sign this proposal; this information
   2166     // is typically added by the backend. Note that this can be an ephemeral key.
   2167     merchant_pub: EddsaPublicKey;
   2168 
   2169     // Base URL of the (public!) merchant backend API.
   2170     // Must be an absolute URL that ends with a slash.
   2171     merchant_base_url: WebURL;
   2172 
   2173     // More info about the merchant, see below.
   2174     merchant: Merchant;
   2175 
   2176     // List of products that are part of the purchase (see `ProductSold`).
   2177     products: ProductSold[];
   2178 
   2179     // The hash of the merchant instance's wire details.
   2180     h_wire: HashCode;
   2181 
   2182     // Wire transfer method identifier for the wire method associated with ``h_wire``.
   2183     // The wallet may only select exchanges via a matching auditor if the
   2184     // exchange also supports this wire method.
   2185     // The wire transfer fees must be added based on this wire transfer method.
   2186     wire_method: string;
   2187 
   2188     // Exchanges that the merchant accepts even if it does not accept any auditors that audit them.
   2189     exchanges: Exchange[];
   2190 
   2191     // Payments for this order that were settled outside of Taler,
   2192     // for example in cash or by card. The ``amount`` field (or the
   2193     // selected choice's ``amount`` for v1 contracts) remains the amount
   2194     // paid with Taler; the full order total is the sum of that amount
   2195     // and all entries here. See `ExternalPaymentInfo`.
   2196     // @since protocol **v42**.
   2197     amount_external?: ExternalPaymentInfo[];
   2198 
   2199   }
   2200 
   2201 .. ts:def:: ContractChoice
   2202 
   2203   interface ContractChoice {
   2204     // Price to be paid for this choice. Could be 0.
   2205     // The price is in addition to other instruments,
   2206     // such as rations and tokens.
   2207     // The exchange will subtract deposit fees from that amount
   2208     // before transferring it to the merchant.
   2209     amount: Amount;
   2210 
   2211     // Optional tip amount. Must match the currency of ``amount``.
   2212     // Since protocol **v25**.
   2213     tip?: Amount;
   2214 
   2215     // Human readable description of the semantics of the choice
   2216     // within the contract to be shown to the user at payment.
   2217     description?: string;
   2218 
   2219     // Map from IETF 47 language tags to localized descriptions.
   2220     description_i18n?: { [lang_tag: string]: string };
   2221 
   2222     // List of inputs the wallet must provision (all of them) to
   2223     // satisfy the conditions for the contract.
   2224     inputs: ContractInput[];
   2225 
   2226     // List of outputs the merchant promises to yield (all of them)
   2227     // once the contract is paid.
   2228     outputs: ContractOutput[];
   2229 
   2230     // Maximum total deposit fee accepted by the merchant for this contract.
   2231     max_fee: Amount;
   2232   }
   2233 
   2234 .. ts:def:: ContractInput
   2235 
   2236   // For now, only tokens are supported as inputs.
   2237   type ContractInput = ContractInputToken;
   2238 
   2239 .. ts:def:: ContractInputToken
   2240 
   2241   interface ContractInputToken {
   2242     type: "token";
   2243 
   2244     // Slug of the token family in the
   2245     // ``token_families`` map on the order.
   2246     token_family_slug: Slug;
   2247 
   2248     // Number of tokens of this type required.
   2249     // Defaults to one if the field is not provided.
   2250     count?: Integer;
   2251   };
   2252 
   2253 .. ts:def:: ContractOutput
   2254 
   2255   // For now, only tokens are supported as outputs.
   2256   type ContractOutput = ContractOutputToken | ContractOutputTaxReceipt;
   2257 
   2258 .. ts:def:: ContractOutputToken
   2259 
   2260   interface ContractOutputToken {
   2261     type: "token";
   2262 
   2263     // Slug of the token family in the
   2264     // 'token_families' map on the top-level.
   2265     token_family_slug: Slug;
   2266 
   2267     // Number of tokens to be issued.
   2268     // Defaults to one if the field is not provided.
   2269     count?: Integer;
   2270 
   2271     // When should the output token be valid. Can be specified if the
   2272     // desired validity period should be in the future (like selling
   2273     // a subscription for the next month). Optional. If not given,
   2274     // the validity is supposed to be "now" (time of order creation).
   2275     valid_at?: Timestamp;
   2276 
   2277     // Index of the public key for this output token
   2278     // in the `ContractTokenFamily` ``keys`` array.
   2279     key_index: Integer;
   2280 
   2281   }
   2282 
   2283 .. ts:def:: ContractOutputTaxReceipt
   2284 
   2285   interface ContractOutputTaxReceipt {
   2286 
   2287     // Tax receipt output.
   2288     type: "tax-receipt";
   2289 
   2290     // Array of base URLs of donation authorities that can be
   2291     // used to issue the tax receipts. The client must select one.
   2292     donau_urls: WebURL[];
   2293 
   2294     // Total amount that will be on the tax receipt.
   2295     amount: Amount;
   2296 
   2297   }
   2298 
   2299 
   2300 Product listing
   2301 ^^^^^^^^^^^^^^^
   2302 
   2303 The `ProductSold` object describes a product and the quantity
   2304 being purchased from the merchant as well as possibly the price
   2305 and applicable taxes.
   2306 It has the following structure:
   2307 
   2308 .. ts:def:: ProductSold
   2309 
   2310   interface ProductSold {
   2311 
   2312     // Merchant-internal identifier for the product.
   2313     product_id?: Slug;
   2314 
   2315     // Name of the product.
   2316     // Since API version **v20**.  Optional only for
   2317     // backwards-compatibility, should be considered mandatory
   2318     // moving forward!
   2319     product_name?: string;
   2320 
   2321     // Human-readable product description.
   2322     description: string;
   2323 
   2324     // Map from IETF BCP 47 language tags to localized descriptions.
   2325     description_i18n?: { [lang_tag: string]: string };
   2326 
   2327     // Legacy integer portion of the quantity to deliver defaults to 1 if not specified.
   2328     quantity?: Integer;
   2329 
   2330     // Preferred quantity string using "<integer>[.<fraction>]" syntax with up to six fractional digits.
   2331     unit_quantity?: string;
   2332 
   2333     // Unit in which the product is measured (liters, kilograms, packages, etc.).
   2334     unit?: Slug;
   2335 
   2336     // The price of the product;
   2337     // Deprecated since **v25**;
   2338     // this is the total price
   2339     // for ``quantity`` times ``unit`` of this product.
   2340     price?: Amount;
   2341 
   2342     // Price of ``unit_quantity`` units of the product in various currencies.
   2343     // Zero or absent implies that the product is not sold
   2344     // separately.
   2345     // Since API version **v25**.
   2346     prices?: Amount[];
   2347 
   2348     // True if the ``prices`` given are the net price,
   2349     // false if they are the gross price.  Note that even ``prices`` are the
   2350     // gross price, ``taxes`` may be missing if the merchant configured
   2351     // gross ``prices`` but did not configure any ``taxes``.
   2352     // Similarly, the merchant may have configured net ``prices``
   2353     // for products but deals with taxes on a per-order basis. Thus, it
   2354     // may not always be possible to compute the gross price from the net
   2355     // price for an individual product, necessitating this flag.
   2356     // Since protocol **vTAXES**.
   2357     prices_are_net: boolean;
   2358 
   2359     // An optional base64-encoded product image.
   2360     image?: ImageDataUrl;
   2361 
   2362     // A list of taxes paid by the merchant for this product. Can be empty.
   2363     // Will likely change soon!
   2364     taxes?: Tax[];
   2365 
   2366     // Time indicating when this product should be delivered.
   2367     delivery_date?: Timestamp;
   2368 
   2369     // Money pot to use for this product, overrides value from
   2370     // the inventory if given.  Not useful to wallets, only for
   2371     // merchant-internal accounting.
   2372     // Since **v25**.
   2373     product_money_pot?: Integer;
   2374 
   2375   }
   2376 
   2377 .. ts:def:: Tax
   2378 
   2379   interface Tax {
   2380     // The name of the tax.
   2381     name: string;
   2382 
   2383     // Amount paid in tax.
   2384     tax: Amount;
   2385   }
   2386 
   2387 .. ts:def:: Merchant
   2388 
   2389   interface Merchant {
   2390     // The merchant's legal name of business.
   2391     name: string;
   2392 
   2393     // Email address for contacting the merchant.
   2394     email?: string;
   2395 
   2396     // Merchant public website.
   2397     website?: WebURL;
   2398 
   2399     // An optional base64-encoded product image.
   2400     logo?: ImageDataUrl;
   2401 
   2402     // Label for a location with the business address of the merchant.
   2403     address?: Location;
   2404 
   2405     // Label for a location that denotes the jurisdiction for disputes.
   2406     // Some of the typical fields for a location (such as a street address) may be absent.
   2407     jurisdiction?: Location;
   2408   }
   2409 
   2410 
   2411 .. ts:def:: Location
   2412 
   2413   // Delivery location, loosely modeled as a subset of
   2414   // ISO20022's PostalAddress25.
   2415   interface Location {
   2416     // Nation with its own government.
   2417     country?: string;
   2418 
   2419     // Identifies a subdivision of a country such as state, region, county.
   2420     country_subdivision?: string;
   2421 
   2422     // Identifies a subdivision within a country sub-division.
   2423     district?: string;
   2424 
   2425     // Name of a built-up area, with defined boundaries, and a local government.
   2426     town?: string;
   2427 
   2428     // Specific location name within the town.
   2429     town_location?: string;
   2430 
   2431     // Identifier consisting of a group of letters and/or numbers that
   2432     // is added to a postal address to assist the sorting of mail.
   2433     post_code?: string;
   2434 
   2435     // Name of a street or thoroughfare.
   2436     street?: string;
   2437 
   2438     // Name of the building or house.
   2439     building_name?: string;
   2440 
   2441     // Number that identifies the position of a building on a street.
   2442     building_number?: string;
   2443 
   2444     // Free-form address lines, should not exceed 7 elements.
   2445     address_lines?: string[];
   2446   }
   2447 
   2448 
   2449 Exchanges
   2450 ^^^^^^^^^
   2451 
   2452 The wallet must select an exchange that the merchant accepts by
   2453 listing it in the exchanges array.
   2454 
   2455 .. ts:def:: Exchange
   2456 
   2457   interface Exchange {
   2458     // The exchange's base URL.
   2459     url: WebURL;
   2460 
   2461     // How much would the merchant like to use this exchange.
   2462     // The wallet should use a suitable exchange with high
   2463     // priority. The following priority values are used, but
   2464     // it should be noted that they are NOT in any way normative.
   2465     //
   2466     // 0: likely it will not work (recently seen with account
   2467     //    restriction that would be bad for this merchant)
   2468     // 512: merchant does not know, might be down (merchant
   2469     //    did not yet get /wire response).
   2470     // 1024: good choice (recently confirmed working)
   2471     priority: Integer;
   2472 
   2473     // Master public key of the exchange.
   2474     master_pub: EddsaPublicKey;
   2475 
   2476     // Maximum amount that the merchant could be paid
   2477     // using this exchange (due to legal limits).
   2478     // New in protocol **v17**.
   2479     // Optional, no limit if missing.
   2480     max_contribution?: Amount;
   2481   }
   2482 
   2483 In addition to the fields described above,
   2484 each object (from `ContractTerms` down)
   2485 can mark certain fields as "forgettable" by listing the names of those fields
   2486 in a special peer field ``$forgettable``.
   2487 (See :ref:`Private order data cleanup <private-order-data-cleanup>`.)
   2488 
   2489 
   2490 .. _contract-terms:
   2491 
   2492 Final contract terms
   2493 ^^^^^^^^^^^^^^^^^^^^
   2494 
   2495 The contract terms are the final object that is signed by both
   2496 parties to finalize a purchase. It must have the following structure:
   2497 
   2498 .. ts:def:: ContractTerms
   2499 
   2500   type ContractTerms = ProtoContractTerms & ContractTermsNonce;
   2501 
   2502 .. ts:def:: ContractTermsNonce
   2503 
   2504   interface ContractTermsNonce {
   2505 
   2506     // Nonce generated by the wallet and echoed by the merchant
   2507     // in this field when the order is claimed and converted
   2508     // into a contract that is bound to a wallet.
   2509     nonce: EddsaPublicKey;
   2510   }