GET /kyc-check/$H_NORMALIZED_PAYTO

Checks the KYC status of a particular payment target. That information allows the customer to choose the next KYC measure to satisfy, if any. This endpoint is typically used by wallets or merchants that have been told that a transaction is not happening because it triggered some KYC/AML measure and now want to check how the KYC/AML requirement could be fulfilled (or whether it already has been statisfied and the operation can now proceed). Long-polling may be used to instantly observe a change in the KYC requirement status.

Given a valid pair of a normalized 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 must always be the same endpoint for the same client, as the wallet/merchant backend are not required to check for changes to this endpoint. Clients 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 v21.

Request:

Account-Owner-Signature:

The client must provide Base-32 encoded EdDSA signature with $ACCOUNT_PRIV, affirming the desire to obtain KYC data. Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature. The $ACCOUNT_PRIV is either the (wallet long-term) reserve private key or the merchant instance private key.

Account-Owner-Pub:

The client should provide the Base-32 encoded EdDSA public key of $ACCOUNT_PUB, enabling the exchange to easily locate the correct public key used for the signature in case multiple wire transfers were made to the account in the past.

Query Parameters:

• lpt=TARGET – Optional. Specifies what status change we are long-polling for. Use 1 to wait for the KYC auth transfer (access token available), 2 to wait for an AML investigation to be done, and 3 to wait for the KYC status to be OK. @since protocol v21.

• min_rule=NUMBER – Optional. Specifies the rule_num of the previous kyc-check already known to the client. When long-polling, the server should always respond when it has a more recent rule. @since protocol v26.

• timeout_ms=NUMBER – Optional. If specified, the exchange will wait up to timeout_ms milliseconds if the requirement continues to be mandatory provisioning of KYC data by the client. Ignored if the HTTP status code is already 200 Ok. Note that clients cannot long-poll for AML staff actions, so status information about an account being under AML review needs to be requested periodically.

Response:

200 Ok:

No mandatory KYC actions are required by the client at this time. The client may still visit the KYC URL to initiate voluntary checks. The response will be an AccountKycStatus object which specifies restrictions that currently apply to the account. If the client attempts to exceed soft limits, the status may change to a 202 Accepted. Hard limits cannot be lifted by passing KYC checks.

202 Accepted:

The account holder performed an operation that would have crossed limits (hard or soft) and must be redirected to the provided location to perform the required KYC checks to satisfy the legal requirements. Afterwards, the /kyc-check/ request should be repeated to check whether the user has completed the process. The response will be an AccountKycStatus object.

204 No content:

The exchange is not configured to perform KYC and thus the legal requirements are already satisfied.

403 Forbidden:

The provided signature is not acceptable for the given account. The response will be an KycCheckAccountExpectedResponse object which specifies the expected account public key.

404 Not found:

The account identified by the normalized payto hash is unknown.

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:

interface KycCheckAccountExpectedResponse {

  // Public key for which the signature must be
  // valid to authorize this request.
  expected_account_pub: EddsaPublicKey;
}

interface AccountKycStatus {

  // Current AML state for the target account.  True if
  // operations are not happening due to staff processing
  // paperwork *or* due to legal requirements (so the
  // client cannot do anything but wait).
  //
  // Note that not every AML staff action may be legally
  // exposed to the client, so this is merely a hint that
  // a client should be told that AML staff is currently
  // reviewing the account.  AML staff *may* review
  // accounts without this flag being set!
  aml_review: boolean;

  // Monotonically increasing number identifying the decision.
  // 0 if no decision was taken for this account. Useful for
  // long-polling via min_rule to long-poll for any change
  // to the rules or limits.
  rule_gen: Integer;

  // Access token needed to construct the /kyc-spa/
  // URL that the user should open in a browser to
  // proceed with the KYC process (optional if the status
  // type is 200 Ok, mandatory if the HTTP status
  // is 202 Accepted).
  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.
  // Note that additional limits *may* exist and not be
  // communicated to the client. If such limits are
  // reached, this *may* be indicated by the account
  // going into aml_review state. However, it is
  // also possible that the exchange may legally have
  // to deny operations without being allowed to provide
  // any justification.
  // The limits should be used by the client to
  // possibly structure their operations (e.g. withdraw
  // what is possible below the limit, ask the user to
  // pass KYC checks or withdraw the rest after the time
  // limit is passed, warn the user to not withdraw too
  // much or even prevent the user from generating a
  // request that would cause it to exceed hard limits).
  limits?: AccountLimit[];

}