get-orders-ORDER_ID.rst (7219B)
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:`400 Bad Request`: 64 The request parameters are malformed. 65 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or 66 ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``. 67 :http:statuscode:`402 Payment required`: 68 The response is a `StatusUnpaidResponse`. 69 :http:statuscode:`403 Forbidden`: 70 The ``h_contract`` (or the ``token`` for unclaimed orders) does not match the order 71 and we have no fulfillment URL in the contract. 72 Returned with ``TALER_EC_MERCHANT_GET_ORDERS_ID_INVALID_TOKEN``, 73 ``TALER_EC_MERCHANT_GET_ORDERS_ID_INVALID_CONTRACT_HASH`` or 74 ``TALER_EC_MERCHANT_GENERIC_CONTRACT_HASH_DOES_NOT_MATCH_ORDER``. 75 :http:statuscode:`404 Not found`: 76 The merchant backend is unaware of the order. 77 Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``. 78 :http:statuscode:`406 Not acceptable`: 79 The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.) 80 :http:statuscode:`409 Conflict`: 81 The request is inconsistent. 82 Returned with ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH``. 83 :http:statuscode:`500 Internal Server Error`: 84 The server experienced an internal failure. 85 Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 86 ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH``, 87 ``TALER_EC_GENERIC_ALLOCATION_FAILURE``, 88 ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID`` or 89 ``TALER_EC_MERCHANT_GET_ORDERS_ID_INVALID_CONTRACT_VERSION``. 90 91 **Details:** 92 93 .. ts:def:: StatusPaidResponse 94 95 interface StatusPaidResponse { 96 // FIXME: since when? 97 // URL for the user to be redirected to if available. 98 fulfillment_url?: string; 99 100 // Was the payment refunded (even partially, via refund or abort)? 101 refunded: boolean; 102 103 // Is any amount of the refund still waiting to be picked up (even partially)? 104 refund_pending: boolean; 105 106 // Amount that was refunded in total. 107 refund_amount: Amount; 108 109 // Amount that already taken by the wallet. 110 refund_taken: Amount; 111 } 112 113 .. ts:def:: StatusGotoResponse 114 115 interface StatusGotoResponse { 116 // The client should go to the reorder URL, there a fresh 117 // order might be created as this one is taken by another 118 // customer or wallet (or repurchase detection logic may 119 // apply). 120 public_reorder_url: string; 121 } 122 123 .. ts:def:: StatusUnpaidResponse 124 125 interface StatusUnpaidResponse { 126 // URI that the wallet must process to complete the payment. 127 taler_pay_uri: string; 128 129 // Fulfillment URL of the contract. 130 // If present, it should be possible to create an 131 // equivalent order by redirecting a browser to this 132 // URL. Once the customer has paid, they should see the 133 // order's fulfillment (digital goods, tracking data for 134 // shipping, etc.) under this URL (assuming they use the 135 // same session that the wallet used when making the payment). 136 fulfillment_url?: string; 137 138 // Alternative order ID which was paid for already in the same session. 139 // Only given if the same product was purchased before in the same session. 140 already_paid_order_id?: string; 141 }