1 files changed, 91 insertions, 0 deletions
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
 --------------------