summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-10-03 14:57:57 +0200
committerChristian Grothoff <christian@grothoff.org>2021-10-03 14:57:57 +0200
commit58f64cdb95e6ecd51c0d9d71d57492861a8fb72e (patch)
treeda0805459a0804ecfb29c7fcd6bdb07656774610 /core
parent8f3c14cf93716f3fe2a60b89107403eb96bc2bec (diff)
downloaddocs-58f64cdb95e6ecd51c0d9d71d57492861a8fb72e.tar.gz
docs-58f64cdb95e6ecd51c0d9d71d57492861a8fb72e.tar.bz2
docs-58f64cdb95e6ecd51c0d9d71d57492861a8fb72e.zip
-spec update
Diffstat (limited to 'core')
-rw-r--r--core/api-exchange.rst77
-rw-r--r--core/api-merchant.rst91
2 files changed, 165 insertions, 3 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 5dfbcc31..dd4450be 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -928,9 +928,61 @@ 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.
+ Provides fee configuration for purses.
+
+ .. note::
+
+ This is a draft API that is not yet implemented.
**Request:**
@@ -948,7 +1000,11 @@ Management operations authorized by master key
.. http:post:: /management/partners
- Enables a partner exchange for wad transfers.
+ Enables a partner exchange for wad transfers.
+
+ .. note::
+
+ This is a draft API that is not yet implemented.
**Request:**
@@ -1379,7 +1435,8 @@ exchange.
transaction or before the client can commit the coin signature to disk, the
coin is not lost.
:http:statuscode:`202 Accepted`:
- This reserve has received funds from a purse and must
+ This reserve has received funds from a purse or the amount withdrawn
+ exceeds another legal threshold and thus the reserve must
be upgraded to an account (with KYC) before the withdraw can
complete. Note that this response does NOT affirm that the
withdraw will ultimately complete with the requested amount.
@@ -1387,6 +1444,20 @@ exchange.
the required KYC checks to open the account before withdrawing.
Afterwards, the request should be repeated.
The response will be an `AccountKycRedirect` object.
+
+ FIXME: Alternatively, we could return only a
+ PAYMENT_TARGET_UUID and expect the client to
+ then do a ``/kyc/`` request. That might be
+ more uniform with other APIs.
+
+ Implementation note: internally, we need to
+ distinguish between upgrading the reserve to an
+ account (due to P2P payment) and identifying the
+ owner of the origin bank account (due to exceeding
+ the withdraw amount threshold), as we need to create
+ a different payto://-URI for the KYC check depending
+ on the case.
+
:http:statuscode:`403 Forbidden`:
The signature is invalid.
:http:statuscode:`404 Not found`:
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index bc68ef26..c9981543 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1199,6 +1199,97 @@ Deleting instances
The latter case only applies if ``purge`` was set.
+KYC status checks
+-----------------
+
+ .. note::
+
+ This is a draft API that is not yet implemented.
+
+
+.. http:GET:: /management/instances/$INSTANCE/kyc
+.. http:GET:: /instances/$INSTANCE/private/kyc
+
+ 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.
+
+ **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 timeout_ms=NUMBER: *Optional.* If specified, the exchange will
+ wait up to ``timeout_ms`` milliseconds for the exchanges to confirm completion of the KYC process(es).
+
+ **Response:**
+
+ If different exchanges cause different errors when processing
+ 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.
+ The response will be an `AccountKycRedirects` object.
+ :http:statuscode:`204 No content`:
+ All KYC operations queried have succeeded.
+ :http:statuscode:`502 Bad gateway`:
+ We failed to obtain a response from an exchange (about the KYC status).
+ The response will be an `AccountKycRedirects` object.
+ :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.
+ The response will be an `AccountKycRedirects` object.
+
+ .. ts:def:: AccountKycRedirects
+
+ interface AccountKycRedirects {
+
+ // Array of pending KYCs.
+ pending_kycs: MerchantAccountKycRedirect[];
+
+ // Array of exchanges with no reply.
+ timeout_kycs: ExchangeKycTimeout[];
+ }
+
+ .. ts:def:: MerchantAccountKycRedirect
+
+ interface MerchantAccountKycRedirect {
+
+ // URL that the user should open in a browser to
+ // proceed with the KYC process (as returned
+ // by the exchange's ``/kyc/`` endpoint).
+ kyc_url: string;
+
+ // Base URL of the exchange this is about.
+ exchange_url: string;
+
+ // Our bank wire account this is about.
+ payto_uri: string;
+
+ }
+
+ .. ts:def:: MerchantAccountKycRedirect
+
+ interface MerchantAccountKycRedirect {
+
+ // 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;
+
+ }
+
--------------------
Inventory management
--------------------