summaryrefslogtreecommitdiff
path: root/core/api-exchange.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-10-05 15:03:45 +0200
committerChristian Grothoff <christian@grothoff.org>2021-10-05 15:03:56 +0200
commitb5a2ce02c784d2303e8af203aa5f1a0a930e9c6d (patch)
tree14787611fe0ed9c7f2d39f00bd439e6bc160bc0f /core/api-exchange.rst
parent8aa010ecfa281765111db376c27c75d7323f03ab (diff)
downloaddocs-b5a2ce02c784d2303e8af203aa5f1a0a930e9c6d.tar.gz
docs-b5a2ce02c784d2303e8af203aa5f1a0a930e9c6d.tar.bz2
docs-b5a2ce02c784d2303e8af203aa5f1a0a930e9c6d.zip
KYC design update
Diffstat (limited to 'core/api-exchange.rst')
-rw-r--r--core/api-exchange.rst87
1 files changed, 26 insertions, 61 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index dd4450be..4f81f5b7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -928,54 +928,6 @@ Management operations authorized by master key
}
-.. http:post:: /management/kyc
-
- Clear the KYC setting from some accounts.
-
- .. note::
-
- This is a draft API that is not yet implemented.
-
- **Request:**
-
- The request must be a `KycRevoke` message.
-
- **Response**
-
- :http:statuscode:`200 Ok`:
- The configuration update has been processed successfully. The body is a `KycStatusUpdate` message.
- :http:statuscode:`403 Forbidden`:
- The signature is invalid.
-
- .. ts:def:: KycRevoke
-
- interface KycRevoke {
-
- // Signature over a `TALER_KycRevocationPS`.
- // Basically signes over the hash of the h_wires.
- master_sig: EddsaSignature;
-
- // Array of hashes of the payto:// URIs for which to
- // revoke the KYC check.
- h_wires: HashCode[];
-
- }
-
- .. ts:def:: KycStatusUpdate
-
- interface KycStatusUpdate {
-
- // Number of accounts that were disabled.
- // Note that it is typically expected that many
- // of the h_wires are simply not in our database
- // or have previously been disabled. So this only
- // returns the number of rows that were effectively
- // changed.
- num_disabled: Integer;
-
- }
-
-
.. http:post:: /management/p2pfees
Provides fee configuration for purses.
@@ -3372,35 +3324,48 @@ KYC status updates
This is a draft API that is not yet implemented.
-.. http:GET:: /kyc/$PAYMENT_TARGET_UUID
+.. http:POST:: /kyc/$PAYMENT_TARGET_UUID
- Check KYC status of a particular payment target.
- Prompts the exchange to inquire with the bank
- as to the KYC status of the respective account
- and returns the result.
+ Check or update KYC status of a particular payment target.
+ Returns the current KYC status of the account and possibly
+ causes the exchange to inquire with its legitimization
+ resource server as to the KYC status of the respective
+ payment target.
**Request:**
:query timeout_ms=NUMBER: *Optional.* If specified, the exchange will
- wait up to ``timeout_ms`` milliseconds for the KYC gateway to
- confirm completion of the KYC process.
-
+ wait up to ``timeout_ms`` milliseconds if the payment target
+ is currently not legitimized. Ignored if the payment target
+ is already legitimized. Note that the legitimization would be
+ triggered by another request to the same endpoint with a valid
+ ``token``.
+ :query token=TOKEN: *Optional.* If specified, TOKEN must be an OAuth
+ access token that the exchange can use to verify that the user has
+ an account with the OAuth resource server that holds the
+ legitimization data.
**Response:**
:http:statuscode:`200 Ok`:
The KYC operation succeeded, the exchange confirms that the
- payment target will receive payments.
+ payment target is now authorized to transact.
The response will be an `AccountKycStatus` object.
:http:statuscode:`202 Accepted`:
The user should be redirected to the provided location to perform
the required KYC checks to open the account. Afterwards, the
- request should be repeated.
+ ``/kyc/`` request should be repeated.
The response will be an `AccountKycRedirect` object.
+ :http:statuscode:`204 No content`:
+ The exchange is not configured to perform KYC and thus
+ generally all accounts are simply considered legitimate.
+ :http:statuscode:`502 Bad Gateway`:
+ The exchange received an invalid reply from the OAuth-based
+ legitimization service.
:http:statuscode:`504 Gateway Timeout`:
- The exchange did not receive a confirmation from the KYC service
- within the specified time period. Used when long-polling for the
- result.
+ The exchange did not receive a reply from the OAuth legitimization
+ service within the specified time period. Used when long-polling
+ for the result.
**Details:**