commit cc092f4de2f92cf71347534b2e75fb0fd1b8992a
parent 800a5bc18bd84a68c727966417381e10a74e0891
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 3 Sep 2024 01:00:19 +0200
breaking API change: /kyc-check/REQUIREMENT_ROW replaced by H_PAYTO
Diffstat:
2 files changed, 24 insertions(+), 21 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -851,6 +851,8 @@ body.
// Hash of the payto:// account URI for which KYC
// is required.
+ // The account holder can uses the ``/kyc-check/$H_PAYTO``
+ // endpoint to check the KYC status or initiate the KYC process.
h_payto: PaytoHash;
// Public key associated with the account. The client must sign
@@ -865,13 +867,11 @@ body.
account_pub?: EddsaPublicKey;
// Identifies a set of measures that were triggered and that are
- // now preventing this operation from proceeding. Gives the
- // account holder a starting point for understanding why the
- // transaction was blocked and how to lift it. The account holder
- // should use the number to check for the account's AML/KYC status
- // using the ``/kyc-check/$REQUIREMENT_ROW`` endpoint.
- // Can be zero (which means there is no requirement row)
- // if ``bad_kyc_auth`` is set.
+ // now preventing this operation from proceeding. Gives developers
+ // a starting point for understanding why the transaction was
+ // blocked and how to lift it.
+ // Can be zero (which means there is no requirement row),
+ // especially if ``bad_kyc_auth`` is set.
requirement_row: Integer;
// True if the operation was denied because the
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -3777,12 +3777,10 @@ typically also view the balance.)
interface TrackTransactionAcceptedResponse {
- // Legitimization target that the merchant should
- // use to check for its KYC status using
- // the ``/kyc-check/$REQUIREMENT_ROW/...`` endpoint.
- // Optional, not present if the deposit has not
+ // Legitimization row. Largely useless, except
+ // not present if the deposit has not
// yet been aggregated to the point that a KYC
- // need has been evaluated.
+ // requirement has been evaluated.
requirement_row?: Integer;
// Current AML state for the target account. Non-zero
@@ -4745,7 +4743,7 @@ regulatory compliance.
}
-.. http:get:: /kyc-check/$REQUIREMENT_ROW
+.. http:get:: /kyc-check/$H_PAYTO
Checks the KYC status of a particular payment target and possibly begins a
KYC process by allowing the customer to choose the next KYC measure to
@@ -4756,11 +4754,7 @@ regulatory compliance.
statisfied and the operation can now proceed). Long-polling may be used
to instantly observe a change in the KYC requirement status.
- The requirement row of the ``/kyc-check/`` endpoint encodes the
- legitimization measure's serial number. It is returned in
- `LegitimizationNeededResponse` responses via the ``requirement_row`` field.
-
- Given a valid pair of requirement row and account owner signature, the
+ Given a valid pair of payto hash and account owner signature, the
``/kyc-check/`` endpoint returns either just the KYC status or redirects the
client (202) to the next required stage of the KYC process. The redirection
must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. It
@@ -4769,7 +4763,7 @@ regulatory compliance.
that received a 202 status code may repeat the request and use long-polling
to detect a change of the HTTP status.
- This endpoint exists in this specific form only since protocol **v20**.
+ This endpoint exists in this specific form only since protocol **v21**.
**Request:**
@@ -4810,14 +4804,23 @@ regulatory compliance.
The exchange is not configured to perform KYC and thus
the legal requirements are already satisfied.
:http:statuscode:`403 Forbidden`:
- The provided signature is not acceptable for the requirement row. The (base32) encoding of the public key we expect signatures to be made with is returned in the ``detail`` field.
+ The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key.
:http:statuscode:`404 Not found`:
- The requirement row is unknown.
+ The account identified by the payto hash is unknown.
:http:statuscode:`409 Conflict`:
The bank account is not (yet) associated with a public key. The account owner must do a wire transfer to the exchange with the account public key in the wire transfer subject to enable authentication.
**Details:**
+ .. ts:def:: KycCheckAccountExpectedResponse
+
+ interface KycCheckAccountExpectedResponse {
+
+ // Public key for which the signature must be
+ // valid to authorize this request.
+ expected_account_pub: EddsaPublicKey;
+ }
+
.. ts:def:: AccountKycStatus
interface AccountKycStatus {
