commit fc463328c5e9b48c1ea387144ea6d2682faba86c
parent 4f5292abdceaa96aafb343ad6a5216cf4d11a8ee
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 8 Sep 2024 18:39:32 +0200
clean up GET /kyc endpoint, return more comprehensive and consistent data
Diffstat:
| M | core/api-merchant.rst | | | 106 | ++++++++++++++++++++++++++++++++++--------------------------------------------- |
1 file changed, 46 insertions(+), 60 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -1456,29 +1456,16 @@ KYC status checks
the request, the largest HTTP status code that is applicable
is returned.
- :http:statuscode:`202 Accepted`:
- The user should be redirected to the provided locations to perform
- the required KYC checks to open an account. Afterwards, the
- request should be repeated.
+ :http:statuscode:`200 Ok`:
+ The user may be redirected to the provided locations to perform
+ KYC checks.
The response will be a `MerchantAccountKycRedirectsResponse` object.
+ Uses this status code and format only since protocol **v17**.
:http:statuscode:`204 No content`:
- All KYC operations queried have succeeded. This may change in the
- future, but there is no need to check again soon. It is suggested
- to check again at a frequency of hours or days.
- :http:statuscode:`502 Bad gateway`:
- We failed to obtain a response from an exchange (about the KYC status).
- The response will be a `MerchantAccountKycRedirectsResponse` object.
- :http:statuscode:`503 Service unavailable`:
- We do not know our KYC status as the exchange has not yet
- returned the necessary details. This is not an actual failure:
- this is expected to happen if for example a deposit was not yet aggregated
- by the exchange and thus the exchange has not yet initiated
- the KYC process. The client should simply try again later. It is
- suggested to check again at a frequency of minutes to hours.
- :http:statuscode:`504 Gateway Timeout`:
- The merchant did not receive a confirmation from an exchange
- within the specified time period. Used when long-polling for the
- result.
+ 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.
**Details:**
@@ -1486,25 +1473,59 @@ KYC status checks
interface MerchantAccountKycRedirectsResponse {
- // Array of pending KYCs.
- pending_kycs: MerchantAccountKycRedirect[];
+ // Array of KYC status information for
+ // the exchanges and bank accounts selected
+ // by the query.
+ kyc_data: MerchantAccountKycRedirect[];
- // Array of exchanges with no reply.
- timeout_kycs: ExchangeKycTimeout[];
}
.. ts:def:: MerchantAccountKycRedirect
interface MerchantAccountKycRedirect {
+ // Our bank wire account this is about.
+ payto_uri: string;
+
+ // Base URL of the exchange this is about.
+ exchange_url: string;
+
+ // HTTP status code returned by the exchange when we asked for
+ // information about the KYC status.
+ // Since protocol **v17**.
+ exchange_http_status: number;
+
+ // Set to true if we did not get a ``/keys`` response from
+ // the exchange and thus cannot do certain checks, such as
+ // determining default account limits or account eligibility.
+ no_keys: boolean;
+
+ // Set to true if the given account cannot to KYC at the
+ // given exchange because no wire method exists that could
+ // be used to do the KYC auth wire transfer.
+ auth_conflict: boolean;
+
+ // 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**.
+ exchange_code?: number;
+
// URL that the user should open in a browser to
// proceed with the KYC process (as returned
// by the exchange's ``/kyc-check/`` endpoint).
// Optional, missing if the account is blocked
// due to the need for a KYC auth transfer.
// (See ``payto_kycauth`` in that case.)
+ // Deprecated since protocol **v17**. Combine
+ // ``exchange_url``, "/kyc-spa/" and ``access_token``
+ // if this is needed instead.
kyc_url?: string;
+ // Access token needed to open the KYC SPA and/or
+ // access the ``/kyc-info/`` endpoint.
+ access_token?: AccountAccessToken;
+
// Array with limitations that currently apply to this
// account and that may be increased or lifted if the
// KYC check is passed.
@@ -1524,23 +1545,6 @@ KYC status checks
// request that would cause it to exceed hard limits).
limits?: AccountLimit[];
- // Base URL of the exchange this is about.
- exchange_url: string;
-
- // 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**.
- exchange_code?: number;
-
- // HTTP status code returned by the exchange when we asked for
- // information about the KYC status.
- // Since protocol **v17**.
- exchange_http_status: number;
-
- // Our bank wire account this is about.
- payto_uri: string;
-
// Array of wire transfer instructions (including
// optional amount and subject) for a KYC auth wire
// transfer. Set only if this is required
@@ -1553,24 +1557,6 @@ KYC status checks
}
- .. ts:def:: ExchangeKycTimeout
-
- interface ExchangeKycTimeout {
-
- // Base URL of the exchange this is about.
- exchange_url: string;
-
- // Numeric `error code <error-codes>` indicating errors the exchange
- // returned, or TALER_EC_INVALID for none.
- exchange_code: number;
-
- // HTTP status code returned by the exchange when we asked for
- // information about the KYC status.
- // 0 if there was no response at all.
- exchange_http_status: number;
-
- }
-
-------------
Bank Accounts
