get-orders-ORDER_ID.rst (6126B)
1 .. http:get:: [/instances/$INSTANCE]/orders/$ORDER_ID 2 3 Query the payment status of an order. This endpoint is for the wallet 4 and possibly for Web shops and other integrations that need an 5 unauthenticated way to query the order status (like when checking 6 it from JavaScript from inside the customer's browser). It is also 7 possible to just redirect a browser to this URL to initiate the 8 payment process. 9 10 When a client (usually a wallet) goes to this URL and it is unpaid, 11 it will be prompted for payment. 12 This endpoint typically also supports requests with the "Accept" header 13 requesting "text/html". In this case, an HTML response suitable for 14 triggering the interaction with the wallet is returned, with ``timeout_ms`` 15 ignored (treated as zero). If the backend installation does not include the 16 required HTML templates, a 406 status code is returned. 17 18 In the case that the request was made with a claim token (even the wrong one) 19 and the order was claimed and paid, the server will redirect the client to 20 the fulfillment URL. This redirection will happen with a 302 status code 21 if the "Accept" header specified "text/html", and with a 202 status code 22 otherwise. 23 24 **Request:** 25 26 :query h_contract=HASH: *Optional*. Hash of the order's contract terms (this is used to authenticate the wallet/customer in case $ORDER_ID is guessable). Required once an order was claimed. 27 :query token=TOKEN: *Optional*. Authorizes the request via the claim token that was returned in the `PostOrderResponse`. Used with unclaimed orders only. Whether token authorization is required is determined by the merchant when the frontend creates the order. 28 :query session_id=STRING: *Optional*. Session ID that the payment must be bound to. If not specified, the payment is not session-bound. 29 :query timeout_ms=NUMBER: *Optional.* If specified, the merchant backend will 30 wait up to ``timeout_ms`` milliseconds for completion of the payment before 31 sending the HTTP response. A client must never rely on this behavior, as the 32 merchant backend may return a response immediately. 33 :query await_refund_obtained=BOOLEAN: *Optional*. If set to "yes", poll for the order's pending refunds to be picked up. ``timeout_ms`` specifies how long we will wait for the refund. 34 :query refund=AMOUNT: *Optional*. Indicates that we are polling for a refund above the given AMOUNT. ``timeout_ms`` will specify how long we will wait for the refund. 35 :query allow_refunded_for_repurchase: *Optional*. Since protocol **v9** refunded orders are only returned under "already_paid_order_id" if this flag is set explicitly to "YES". 36 37 **Response:** 38 39 :http:statuscode:`200 OK`: 40 The response is a `StatusPaidResponse`. 41 :http:statuscode:`202 Accepted`: 42 The response is a `StatusGotoResponse`. 43 Returned only for unauthenticated (no nonce, no contract hash) 44 requests and only if the order was claimed already. 45 Only returned if the content type requested was not HTML, 46 if HTML was requested a ``302 Found`` will be returned instead. 47 The target site may allow the client to setup a fresh 48 order (as this one has been taken) or may 49 trigger repurchase detection. 50 Note that **if** the contract lacks a ``public_reorder_url`` 51 the backend will instead return a ``403 Forbidden`` response. 52 :http:statuscode:`302 Found`: 53 The client should go to the indicated location (via HTTP "Location:" header). 54 Returned only for unauthenticated (no nonce, no contract hash) 55 requests and only if the order was claimed already. 56 Only returned if the content type requested was HTML 57 if HTML was not requested a ``302 Accepted`` will be returned instead. 58 The target site may allow the client to setup a fresh 59 order (as this one has been taken) or may 60 trigger repurchase detection. 61 Note that **if** the contract lacks a ``public_reorder_url`` 62 the backend will instead return a ``403 Forbidden`` response. 63 :http:statuscode:`402 Payment required`: 64 The response is a `StatusUnpaidResponse`. 65 :http:statuscode:`403 Forbidden`: 66 The ``h_contract`` (or the ``token`` for unclaimed orders) does not match the order 67 and we have no fulfillment URL in the contract. 68 :http:statuscode:`404 Not found`: 69 The merchant backend is unaware of the order. 70 :http:statuscode:`406 Not acceptable`: 71 The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.) 72 73 **Details:** 74 75 .. ts:def:: StatusPaidResponse 76 77 interface StatusPaidResponse { 78 // Was the payment refunded (even partially, via refund or abort)? 79 refunded: boolean; 80 81 // Is any amount of the refund still waiting to be picked up (even partially)? 82 refund_pending: boolean; 83 84 // Amount that was refunded in total. 85 refund_amount: Amount; 86 87 // Amount that already taken by the wallet. 88 refund_taken: Amount; 89 } 90 91 .. ts:def:: StatusGotoResponse 92 93 interface StatusGotoResponse { 94 // The client should go to the reorder URL, there a fresh 95 // order might be created as this one is taken by another 96 // customer or wallet (or repurchase detection logic may 97 // apply). 98 public_reorder_url: string; 99 } 100 101 .. ts:def:: StatusUnpaidResponse 102 103 interface StatusUnpaidResponse { 104 // URI that the wallet must process to complete the payment. 105 taler_pay_uri: string; 106 107 // Fulfillment URL of the contract. 108 // If present, it should be possible to create an 109 // equivalent order by redirecting a browser to this 110 // URL. Once the customer has paid, they should see the 111 // order's fulfillment (digital goods, tracking data for 112 // shipping, etc.) under this URL (assuming they use the 113 // same session that the wallet used when making the payment). 114 fulfillment_url?: string; 115 116 // Alternative order ID which was paid for already in the same session. 117 // Only given if the same product was purchased before in the same session. 118 already_paid_order_id?: string; 119 }