summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-07-23 19:39:54 +0200
committerChristian Grothoff <christian@grothoff.org>2021-07-23 19:41:11 +0200
commit4e706885623ae527e23fa05f7658fafd323b7b6d (patch)
treedb6accade1da1db4cb019c78e803144c3e16ba36
parent1a00b47493ce26c064ecccd3ceb3406e6ed558c8 (diff)
downloaddocs-4e706885623ae527e23fa05f7658fafd323b7b6d.tar.gz
docs-4e706885623ae527e23fa05f7658fafd323b7b6d.tar.bz2
docs-4e706885623ae527e23fa05f7658fafd323b7b6d.zip
-minor doc improvements
-rw-r--r--core/api-merchant.rst43
1 files 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.