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 }