post-private-orders-ORDER_ID-collect.rst (3822B)
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`` 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, or 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. 63 :http:statuscode:`500 Internal Server Error`: 64 The server experienced an internal failure. 65 Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or 66 ``TALER_EC_GENERIC_DB_SOFT_FAILURE``. 67 68 **Details:** 69 70 .. ts:def:: CollectRequest 71 72 interface CollectRequest { 73 // Session ID to store with the payment, like the ``session_id`` of 74 // a wallet payment. Allows a point-of-sale device to tag and later 75 // list the orders it collected. Absent for no session. 76 session_id?: string; 77 78 // For v1 contracts, the index of the choice to complete within 79 // the ``choices`` array of the contract terms. Mandatory for v1 80 // contracts: the backend never selects a choice on its own, just 81 // as a wallet has to select one when paying. Must be absent for 82 // v0 contracts, which have no choices. 83 choice_index?: Integer; 84 }