commit efee06d254de47bd9af586a5f0e7a0862a620d84
parent 4b4fba2eb54103a0d037533f416dad922a972e4f
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Tue, 13 Jan 2026 19:57:58 +0900
propose API change for #10546 / #9770
Diffstat:
1 file changed, 53 insertions(+), 15 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -49,7 +49,8 @@ Android PoS app is currently targeting **v20**.
for template instantiation
* ``vTAXES``: adds features to manage taxes
* ``vPAIVANA``: adds features for templates to support session-based payments
-
+* ``vKYCLP``: new long-polling for KYC
+
**Ideas for future version:**
* ``vXXX``: marker for features not yet targeted for release
@@ -2422,8 +2423,10 @@ KYC status checks
**Request:**
- :query h_wire=H_WIRE: *Optional*. If specified, the KYC check should return the KYC status only for this wire account. Otherwise, for all wire accounts.
- :query exchange_url=URL: *Optional*. If specified, the KYC check should return the KYC status only for the given exchange. Otherwise, for all exchanges we interacted with.
+ :query h_wire=H_WIRE: *Optional*. If specified, the KYC check should
+ return the KYC status only for this wire account. Otherwise, for all wire accounts.
+ :query exchange_url=URL: *Optional*. If specified, the KYC check should
+ return the KYC status only for the given exchange. Otherwise, for all exchanges we interacted with.
:query lpt=TARGET: *Optional*.
Specifies what status change we are long-polling for.
Use 1 to wait for the KYC auth transfer (access token available),
@@ -2432,7 +2435,30 @@ 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**.
+ @since protocol **v17**. @deprecated with **vKYCLP**, 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**.
+ :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**.
+ :query lp_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.
+ @since protocol **vKYCLP**.
: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).
@@ -2449,9 +2475,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.
- This may change in the future, but there is
- no need to check again soon. This will most likely
- change if accounts are added to the instance.
+ @since protocol **vKYCLP** 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**.
**Details:**
@@ -2474,6 +2503,7 @@ KYC status checks
//
// o "no-exchange-keys": we do not (yet) have the /keys of the exchange
// - "kyc-wire-impossible": KYC auth transfer needed but not possible
+ // (see also: auth_conflict).
// @ "kyc-wire-required": KYC auth transfer still needed and possible
// @ "kyc-required": merchant must supply KYC data to proceed (incl.
// in case of exposed zero-limits on deposit/aggregation)
@@ -2497,9 +2527,13 @@ KYC status checks
// Full payto URI of the bank wire account this is about.
payto_uri: string;
- // Hash of the salted payto://-URI of our
- // bank wire account this is about.
- // Since protocol **v17**.
+ // Currency used by the exchange.
+ // @since protocol **vKYCLP**.
+ exchange_currency: string;
+
+ // Hash of the salted payto://-URI of our bank wire
+ // account this is about.
+ // @since protocol **v17**.
h_wire: string;
// Base URL of the exchange this is about.
@@ -2507,7 +2541,7 @@ KYC status checks
// HTTP status code returned by the exchange when we asked for
// information about the KYC status.
- // Since protocol **v17**.
+ // @since protocol **v17**.
exchange_http_status: Integer;
// True if we did not get a ``/keys`` response from
@@ -2515,7 +2549,7 @@ KYC status checks
// determining default account limits or account eligibility.
no_keys: boolean;
- // True if the given account cannot to KYC at the
+ // True if the given account cannot do KYC at the
// given exchange because no wire method exists that could
// be used to do the KYC auth wire transfer.
auth_conflict: boolean;
@@ -2523,11 +2557,14 @@ KYC status checks
// Numeric `error code <error-codes>` indicating errors the exchange
// returned, or TALER_EC_INVALID for none.
// Optional (as there may not always have
- // been an error code). Since protocol **v17**.
+ // been an error code).
+ // @since protocol **v17**.
exchange_code?: Integer;
// Access token needed to open the KYC SPA and/or
// access the ``/kyc-info/`` endpoint.
+ // Optional as without the KYC auth wire transfer we
+ // may simply not have an access token yet.
access_token?: AccountAccessToken;
// Array with limitations that currently apply to this
@@ -2552,12 +2589,13 @@ KYC status checks
// Array of full payto://-URIs with
// wire transfer instructions (including
// optional amount and subject) for a KYC auth wire
- // transfer. Set only if this is required
+ // transfer. Set only if this is (still) required
// to get the given exchange working.
// Array because the exchange may have multiple
// bank accounts, in which case any of these
// accounts will do.
- // Optional. Since protocol **v17**.
+ // Optional.
+ // @since protocol **v17**.
payto_kycauths?: string[];
}
