[taler-docs] branch master updated: spec merchant api v10, see #8357

[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 b517fcdf spec merchant api v10, see #8357
b517fcdf is described below

commit b517fcdf4808d18e3ecaf16946de9fe17cf35485
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Mar 2 22:48:23 2024 +0100

    spec merchant api v10, see #8357
---
 core/api-merchant.rst | 60 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 49 insertions(+), 11 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index d3044505..24a9a29e 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -123,7 +123,7 @@ such as the implemented version of the protocol and the 
currency used.
 .. http:get:: /config
 
   Return the protocol version and currency supported by this merchant backend.
-  This specification corresponds to ``current`` protocol being version **9**.
+  This specification corresponds to ``current`` protocol being version **10**.
 
   **Response:**
 
@@ -142,7 +142,7 @@ such as the implemented version of the protocol and the 
currency used.
       name: "taler-merchant";
 
       // URN of the implementation (needed to interpret 'revision' in version).
-      // @since v8, may become mandatory in the future.
+      // @since **v8**, may become mandatory in the future.
       implementation?: string;
 
       // Default (!) currency supported by this backend.
@@ -166,7 +166,7 @@ such as the implemented version of the protocol and the 
currency used.
       currencies: { currency : CurrencySpecification};
 
       // Array of exchanges trusted by the merchant.
-      // Since protocol v6.
+      // Since protocol **v6**.
       exchanges: ExchangeConfigInfo[];
 
     }
@@ -412,7 +412,7 @@ Querying payment status
     merchant backend may return a response immediately.
   :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.
-  :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".
+  :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".
 
   **Response:**
 
@@ -1937,7 +1937,7 @@ Creating orders
 
       // The session for which the payment is made (or replayed).
       // Only set for session-based payments.
-      // Since protocol v6.
+      // Since protocol **v6**.
       session_id?: string;
 
       // Specifies that some products are to be included in the
@@ -2070,8 +2070,8 @@ Inspecting orders
   :query date_s: *Optional.* Non-negative date in seconds 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 ``INT64_MAX``, namely the biggest row id possible 
in the database.
   :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.
-  :query session_id: *Optional*. Since protocol v6. Filters by session ID.
-  :query fulfillment_url: *Optional*. Since protocol v6. Filters by 
fulfillment URL.
+  :query session_id: *Optional*. Since protocol **v6**. Filters by session ID.
+  :query fulfillment_url: *Optional*. Since protocol **v6**. Filters by 
fulfillment URL.
 
   **Response:**
 
@@ -2128,9 +2128,9 @@ Inspecting orders
   **Request:**
 
   :query session_id: *Optional*. Session ID that the payment must be bound to. 
 If not specified, the payment is not session-bound.
-  :query transfer: *Deprecated in protocol V6*. *Optional*. If set to "YES", 
try to obtain the wire transfer status for this order from the exchange. 
Otherwise, the wire transfer status MAY be returned if it is available.
+  :query transfer: Deprecated in protocol **V6**. *Optional*. If set to "YES", 
try to obtain the wire transfer status for this order from the exchange. 
Otherwise, the wire transfer status MAY be returned if it is available.
   :query timeout_ms: *Optional*. Timeout in milliseconds to wait for a payment 
if the answer would otherwise be negative (long polling).
-  :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".
+  :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".
 
   **Response:**
 
@@ -2193,7 +2193,7 @@ Inspecting orders
 
       // Reports about trouble obtaining wire transfer details,
       // empty array if no trouble were encountered.
-      // @deprecated in protocol v6
+      // @deprecated in protocol **v6**.
       wire_reports: TransactionWireReport[];
 
       // The refund details for this order.  One entry per
@@ -2638,7 +2638,7 @@ to validate that a customer made a payment.
       // "NONE" or 0: No algorithm (no pos confirmation will be generated)
       // "TOTP_WITHOUT_PRICE" or 1: Without amounts (typical OTP device)
       // "TOTP_WITH_PRICE" or 2: With amounts (special-purpose OTP device)
-      // The "String" variants are supported @since protocol v7.
+      // The "String" variants are supported @since protocol **v7**.
       otp_algorithm: Integer | string;
 
       // Counter for counter-based OTP devices.
@@ -2720,6 +2720,17 @@ to validate that a customer made a payment.
 
   This is used to obtain detailed information about a specific OTP device.
 
+  The client can provide additional inputs in the query to allow the backend
+  to compute and return a sample OTP code.  Note that it is not an error if
+  the client provides query arguments that are not being used *or* that are
+  insufficient for the server to compute the ``otp_code``: If the client
+  provides inadequate query parameters, the ``otp_code`` is simply omitted
+  from the response.
+
+  **Query:**
+
+  :query faketime=TIMESTAMP: *Optional*. Timestamp in seconds to use when 
calculating the current OTP code of the device. Since protocol **v10**.
+  :query price=AMOUNT: *Optional*. Price to use when calculating the current 
OTP code of the device. Since protocol **v10**.
 
   **Response:**
 
@@ -2737,11 +2748,38 @@ to validate that a customer made a payment.
       device_description: string;
 
       // Algorithm for computing the POS confirmation.
+      //
+      // Currently, the following numbers are defined:
+      // 0: None
+      // 1: TOTP without price
+      // 2: TOTP with price
       otp_algorithm: Integer;
 
       // Counter for counter-based OTP devices.
       otp_ctr?: Integer;
 
+      // Current OTP code of the device.
+      //
+      // If the ``otp_algorithm`` is time-based, the code is
+      // returned for the current time, or for the ``faketime``
+      // if a TIMESTAMP query argument was provided by the client.
+      //
+      // When using OTP with counters, the counter is **NOT**
+      // increased merely because this endpoint created
+      // an OTP code (this is a GET request, after all!).
+      //
+      // If the ``otp_algorithm`` requires an amount, the
+      // ``amount`` argument must be specified in the
+      // query, otherwise the ``otp_code`` is not
+      // generated.
+      //
+      // This field is *optional* in the response, as it is
+      // only provided if we could compute it based on the
+      // ``otp_algorithm`` and matching client query arguments.
+      //
+      // Available since protocol **v10**.
+      otp_code?: Integer;
+
    }
 
 .. http:delete:: [/instances/$INSTANCE]/private/otp-devices/$DEVICE_ID

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