taler-docs

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

post-private-orders-ORDER_ID-collect.rst (4184B)

      1 .. http:post:: [/instances/$INSTANCE]/private/orders/$ORDER_ID/collect
      2 
      3   Complete a zero-Taler order without a customer wallet.  This is used for
      4   orders whose Taler ``amount`` is zero, for example because the full total
      5   was settled through ``amount_external``.  The merchant backend acts like a
      6   customer wallet collecting a free order: it claims the order with a
      7   backend-generated nonce and then has the order paid.  The payment itself is
      8   not reimplemented: the request is handed to the same logic that handles a
      9   payment by a wallet, so payment notifications, webhooks, triggers and
     10   inventory updates behave exactly as for a wallet payment of a free order,
     11   and the response of this endpoint is the response of that payment.
     12 
     13   The operation is idempotent: the backend derives the claim nonce
     14   deterministically from the instance public key and the order identifier, so
     15   repeating the request after a success (or a crash between the claim and the
     16   payment step) completes or replays harmlessly.
     17 
     18   Collection is only possible while the order is unclaimed.  If a customer
     19   wallet has already claimed the order, the wallet owns the order and must
     20   execute the free payment itself.  A point-of-sale application should
     21   therefore offer the order QR code first and only collect after the customer
     22   declined collecting it with own wallet.
     23 
     24   Collection is restricted to genuinely free Taler payments: the Taler
     25   ``amount`` must be zero and, for v1 contracts, the selected choice must have
     26   no ``inputs`` and no ``outputs``.
     27 
     28   **Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`)
     29 
     30   Since protocol **vMixedPayments**.
     31 
     32   **Request:**
     33 
     34   The request body is a `CollectRequest` object.
     35 
     36   **Response:**
     37 
     38   :http:statuscode:`200 OK`:
     39     The order was successfully collected (or had already been collected).
     40     The response is that of paying the order, a `PaymentResponse`.
     41   :http:statuscode:`401 Unauthorized`:
     42     The request is unauthorized.
     43   :http:statuscode:`400 Bad Request`:
     44     The ``choice_index`` does not fit the contract.
     45     Returned with
     46     ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISSING``
     47     if the contract is a v1 contract and no ``choice_index`` was given,
     48     or with
     49     ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_OUT_OF_BOUNDS``
     50     if the given ``choice_index`` does not exist in the contract, which
     51     includes naming any choice for a v0 contract.
     52   :http:statuscode:`404 Not found`:
     53     The order is unknown to the merchant.
     54     Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``.
     55   :http:statuscode:`409 Conflict`:
     56     The order cannot be collected by the backend.
     57     Returned with
     58     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_COLLECT_ALREADY_CLAIMED``
     59     if the order was already claimed by a customer wallet, with
     60     ``TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_COLLECT_NOT_FREE``
     61     if the Taler amount is not zero or the selected choice redeems or
     62     issues tokens, or with
     63     ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISMATCH``
     64     if the order was already collected, but completing a different
     65     choice than the one given in this request.  As for a payment, the
     66     response then is an `AlreadyPaidChoiceResponse` naming the choice
     67     the order was actually paid with.
     68   :http:statuscode:`500 Internal Server Error`:
     69     The server experienced an internal failure.
     70     Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or
     71     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``.
     72 
     73   **Details:**
     74 
     75   .. ts:def:: CollectRequest
     76 
     77     interface CollectRequest {
     78       // Session ID to store with the payment, like the ``session_id`` of
     79       // a wallet payment. Allows a point-of-sale device to tag and later
     80       // list the orders it collected. Absent for no session.
     81       session_id?: SessionID;
     82 
     83       // For v1 contracts, the index of the choice to complete within
     84       // the ``choices`` array of the contract terms. Mandatory for v1
     85       // contracts: the backend never selects a choice on its own, just
     86       // as a wallet has to select one when paying. Must be absent for
     87       // v0 contracts, which have no choices.
     88       choice_index?: Integer;
     89     }