From 4e706885623ae527e23fa05f7658fafd323b7b6d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 23 Jul 2021 19:39:54 +0200 Subject: -minor doc improvements --- core/api-merchant.rst | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/core/api-merchant.rst b/core/api-merchant.rst index ef84fcd9..11941257 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -339,15 +339,15 @@ Querying payment status **Request:** - :query h_contract=HASH: 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. + :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. :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. :query session_id=STRING: *Optional*. Session ID that the payment must be bound to. If not specified, the payment is not session-bound. :query timeout_ms=NUMBER: *Optional.* If specified, the merchant backend will wait up to ``timeout_ms`` milliseconds for completion of the payment before sending the HTTP response. A client must never rely on this behavior, as the merchant backend may return a response immediately. - :query refund=AMOUNT: *Optional*. Indicates that we are polling for a refund above the given AMOUNT. Only useful in combination with timeout. - :query await_refund_obtained=BOOLEAN: *Optional*. If set to "yes", poll for the order's pending refunds to be picked up. + :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. + :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. **Response:** @@ -355,15 +355,18 @@ Querying payment status The response is a `StatusPaidResponse`. :http:statuscode:`202 Accepted`: The response is a `StatusGotoResponse`. Only returned if the content type requested was not HTML. + The target site may allow the client to setup a fresh order (as this one has been taken) or may + trigger repurchase detection. :http:statuscode:`302 Found`: - The client should go to the indicated location. Only returned if the content type requested was HTML. + The client should go to the indicated location (via HTTP "Location:" header). + Only returned if the content type requested was HTML. + The target site may allow the client to setup a fresh order (as this one has been taken) or may + trigger repurchase detection. :http:statuscode:`402 Payment required`: The response is a `StatusUnpaidResponse`. :http:statuscode:`403 Forbidden`: The ``h_contract`` (or the ``token`` for unclaimed orders) does not match the order and we have no fulfillment URL in the contract. - :http:statuscode:`410 Gone`: - The response is a `StatusGoneResponse`. :http:statuscode:`404 Not found`: The merchant backend is unaware of the order. :http:statuscode:`406 Not acceptable`: @@ -385,9 +388,11 @@ Querying payment status .. ts:def:: StatusGotoResponse interface StatusGotoResponse { - // The client should go to the fulfillment URL, it may be ready or - // might have some other interesting status. - fulfillment_url: string; + // The client should go to the reorder URL, there a fresh + // order might be created as this one is taken by another + // customer or wallet (or repurchase detection logic may + // apply). + public_reorder_url: string; } .. ts:def:: StatusUnpaidResponse @@ -405,15 +410,6 @@ Querying payment status already_paid_order_id?: string; } - .. ts:def:: StatusGoneResponse - - // The client tried to access the order via the claim - // token (and not a valid ``h_contract``), but the order can't be claimed - // anymore, as it is already paid. - interface StatusGoneResponse { - // Fulfillment URL for the order. - fulfillment_url: string; - } Demonstrating payment @@ -461,8 +457,6 @@ again. :http:statuscode:`404 Not found`: The merchant backend could not find the order or the instance and thus cannot process the request. - :http:statuscode:`409 Conflict`: - The provided contract hash does not match this order. .. ts:def:: PaidRequest @@ -1717,9 +1711,9 @@ Inspecting orders :query paid: *Optional*. If set to yes, only return paid orders, if no only unpaid orders. Do not give (or use "all") to see all orders regardless of payment status. :query refunded: *Optional*. If set to yes, only return refunded orders, if no only unrefunded orders. Do not give (or use "all") to see all orders regardless of refund status. :query wired: *Optional*. If set to yes, only return wired orders, if no only orders with missing wire transfers. Do not give (or use "all") to see all orders regardless of wire transfer status. + :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_ms`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_ms``). :query date_ms: *Optional.* Non-negative date in milliseconds after the UNIX Epoc, see ``delta`` for its interpretation. If not specified, we default to the oldest or most recent entry, depending on ``delta``. :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation. Defaults to ``UINT64_MAX``, namely the biggest row id possible in the database. - :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` and ``date_ms`` are returned. Defaults to ``-20`` to return the last 20 entries (before ``start`` and/or ``date_ms``). :query timeout_ms: *Optional*. Timeout in milliseconds to wait for additional orders if the answer would otherwise be negative (long polling). Only useful if delta is positive. Note that the merchant MAY still return a response that contains fewer than ``delta`` orders. **Response:** @@ -2867,6 +2861,12 @@ The contract terms must have the following structure: // before transferring it to the merchant. amount: Amount; + // URL where the same contract could be ordered again (if + // available). Returned also at the public order endpoint + // for people other than the actual buyer (hence public, + // in case order IDs are guessable). + public_reorder_url?: string; + // URL that will show that the order was successful after // it has been paid for. Optional. When POSTing to the // merchant, the placeholder "${ORDER_ID}" will be @@ -2874,6 +2874,7 @@ The contract terms must have the following structure: // order ID is generated server-side and needs to be // in the URL). // Note that this placeholder can only be used once. + // Either fulfillment_url or fulfillment_message must be specified. fulfillment_url?: string; // Message shown to the customer after paying for the order. -- cgit v1.2.3