[taler-docs] branch master updated: -minor doc improvements

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 4e70688  -minor doc improvements
4e70688 is described below

commit 4e706885623ae527e23fa05f7658fafd323b7b6d
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Jul 23 19:39:54 2021 +0200

    -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 ef84fcd..1194125 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.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.