taler-docs

api-merchant.rst (50654B)

---

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