commit 417f3516904a42cbd04f4062621b4118cf26f222
parent 2932c14c4d3d648205f6e26bf1b645061f5576d3
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 26 Jan 2026 03:22:12 +0100
protocol updates for long-polling on any order change
Diffstat:
1 file changed, 21 insertions(+), 7 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -2433,19 +2433,19 @@ KYC status checks
If multiple accounts or exchanges match the query,
any account reaching the TARGET state will cause
the response to be returned.
- @since protocol **v17**. @deprecated with **vKYCLP**, use ``lp_*``-query parameters instead.
+ @since protocol **v17**. @deprecated with **v25**, use ``lp_*``-query parameters instead.
:query lp_status=STATUS: *Optional*.
Specifies what status change we are long-polling for.
If specified, the endpoint will only return once the status *matches* the given value.
If multiple accounts or exchanges match the query,
any account reaching the STATUS will cause the response to be returned.
- @since protocol **vKYCLP**.
+ @since protocol **v25**.
:query lp_not_status=STATUS: *Optional*.
Specifies what status change we are long-polling for.
If specified, the endpoint will only return once the status no longer matches the given value.
If multiple accounts or exchanges *no longer matches* the given STATUS
will cause the response to be returned.
- @since protocol **vKYCLP**.
+ @since protocol **v25**.
:query lp_not_etag=ETAG: *Optional*.
Specifies what status change we are long-polling for.
If specified, the endpoint will only return once the returned "Etag"
@@ -2456,7 +2456,7 @@ KYC status checks
using this query parameter should probably also set a "If-not-modified"
HTTP header so that if the ``timeout_ms`` expires, they can get back
a "304 Not modified" with an empty body if nothing changed.
- @since protocol **vKYCLP**.
+ @since protocol **v25**.
:query timeout_ms=NUMBER: *Optional.* If specified, the merchant will
wait up to ``timeout_ms`` milliseconds for the exchanges to confirm completion of the KYC process(es).
@@ -2473,12 +2473,12 @@ KYC status checks
Uses this status code and format only since protocol **v17**.
:http:statuscode:`204 No content`:
No possibilities for KYC operations exist.
- @since protocol **vKYCLP** only returned if this instance has no bank
+ @since protocol **v25** only returned if this instance has no bank
accounts or no exchanges are configured for the merchant backend.
:http:statuscode:`304 Not modified`:
The ``ETag`` in the response did not change compared to the one
given in the ``If-not-modified`` HTTP header specified by the client.
- @since protocol **vKYCLP**.
+ @since protocol **v25**.
**Details:**
@@ -2529,7 +2529,7 @@ KYC status checks
payto_uri: string;
// Currency used by the exchange.
- // @since protocol **vKYCLP**.
+ // @since protocol **v25**.
exchange_currency: string;
// Hash of the salted payto://-URI of our bank wire
@@ -4609,12 +4609,26 @@ Inspecting orders
: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 timeout_ms: *Optional*. Timeout in milliseconds to wait for a payment if the answer would otherwise be negative (long polling).
+ :query lp_not_etag=ETAG: *Optional*.
+ Specifies what status change we are long-polling for.
+ If specified, the endpoint will only return once the returned "Etag"
+ would differ from the ETAG specified by the client. The "Etag"
+ is computed over the entire response body, and thus assured to change
+ whenever any data point in the response changes. This is ideal for
+ clients that want to learn about any change in the response. Clients
+ using this query parameter should probably also set a "If-not-modified"
+ HTTP header so that if the ``timeout_ms`` expires, they can get back
+ a "304 Not modified" with an empty body if nothing changed.
: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:**
:http:statuscode:`200 OK`:
Returns a `MerchantOrderStatusResponse`, whose format can differ based on the status of the payment.
+ :http:statuscode:`304 Not modified`:
+ The ``ETag`` in the response did not change compared to the one
+ given in the ``If-not-modified`` HTTP header specified by the client.
+ @since protocol **v25**.
:http:statuscode:`404 Not found`:
The order or instance is unknown to the backend. Error code
is set to either ``MERCHANT_GENERIC_ORDER_UNKNOWN`` or
