commit b517fcdf4808d18e3ecaf16946de9fe17cf35485
parent 1646c07abee282ce28e8bb4395dafb301beaf2db
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 2 Mar 2024 22:48:23 +0100
spec merchant api v10, see #8357
Diffstat:
1 file changed, 49 insertions(+), 11 deletions(-)
diff --git 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
