GET /management/instances/$INSTANCE/kyc

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.

Required permission: instances-kyc-read

Request:

Query Parameters:

• 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.

• 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.

• 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. If multiple accounts or exchanges match the query, any account reaching the TARGET state will cause the response to be returned. @since protocol v17. @deprecated with v25, use lp_*-query parameters instead.

• lp_status=STATUS – Optional. Specifies what status change we are long-polling for. If specified, the endpoint will only return once the status matches the given value. If multiple accounts or exchanges match the query, any account reaching the STATUS will cause the response to be returned. @since protocol v25.

• lp_not_status=STATUS – Optional. Specifies what status change we are long-polling for. If specified, the endpoint will only return once the status no longer matches the given value. If multiple accounts or exchanges no longer matches the given STATUS will cause the response to be returned. @since protocol v25.

• lp_not_etag=ETAG – Optional. Specifies what status change we are long-polling for. If specified, the endpoint will only return once the returned “Etag” would differ from the ETAG specified by the client. The “Etag” is computed over the entire response body, and thus assured to change whenever any data point in the response changes. This is ideal for clients that want to learn about any change in the response. Clients using this query parameter should probably also set a “If-none-match” HTTP header so that if the timeout_ms expires, they can get back a “304 Not modified” with an empty body if nothing changed. @since protocol v25.

• timeout_ms=NUMBER – Optional. If specified, the merchant 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.

200 Ok:

The user may be redirected to the provided locations to perform KYC checks. The response will be a MerchantAccountKycRedirectsResponse object. Uses this status code and format only since protocol v17.

204 No content:

No possibilities for KYC operations exist. @since protocol v25 only returned if this instance has no bank accounts or no exchanges are configured for the merchant backend.

304 Not modified:

The ETag in the response did not change compared to the one given in the If-none-match HTTP header specified by the client. @since protocol v25.

Details:

 interface MerchantAccountKycRedirectsResponse {

   // Array of KYC status information for
   // the exchanges and bank accounts selected
   // by the query.
   kyc_data: MerchantAccountKycRedirect[];

}

interface MerchantAccountKycRedirect {

  // Summary of the status of the KYC process. Possible values are:
  //
  // o "unsupported-account": this exchange does not support the given account (this is unlikely to change automatically, but could be perfectly normal if the account is supported by at least one other exchange). @since protocol **v25**.
  // o "no-exchange-keys": we do not (yet) have the /keys of the exchange
  // - "kyc-wire-impossible": KYC auth transfer needed but not possible
  //   (see also: auth_conflict).
  // @ "kyc-wire-required": KYC auth transfer still needed and possible
  // @ "kyc-required": merchant must supply KYC data to proceed (incl.
  //      in case of exposed zero-limits on deposit/aggregation)
  // + "awaiting-aml-review": account under review by payment provider
  // + "ready": everything is fine, account can be fully used
  // - "logic-bug": merchant backend logic bug
  // o "merchant-internal-error": merchant had an internal error
  // o "exchange-internal-error": exchange had an internal error
  // o "exchange-gateway-timeout": network timeout at gateway
  // o "exchange-unreachable": exchange did not respond at all to our KYC status inquiry
  //   this can be briefly the case even if an exchange is online, as any HTTP request
  //   takes time to be processed; as a result, the KYC status for this account is unknown
  // - "exchange-status-invalid": exchange violated protocol in reply
  //
  // "+" are perfectly normal states, "@" are states where the user
  // must performn an action (show link!); "o" are reasonable transient
  // states that could happen and are we are expected to likely recover
  // from automatically but that we should inform the user about
  // (show in yellow?), "-" are hard error states from which
  // there is likely no good automatic recovery from (show in red?).
  status: string;

  // Full payto URI of the bank wire account this is about.
  payto_uri: string;

  // Currency used by the exchange.
  // @since protocol **v25**.
  exchange_currency: string;

  // Hash of the salted payto://-URI of our bank wire
  // account this is about.
  // @since protocol **v17**.
  h_wire: string;

  // Base URL of the exchange this is about.
  exchange_url: string;

  // HTTP status code returned by the exchange when we asked for
  // information about the KYC status.
  // @since protocol **v17**.
  exchange_http_status: Integer;

  // True if we did not get a /keys response from
  // the exchange and thus cannot do certain checks, such as
  // determining default account limits or account eligibility.
  no_keys: boolean;

  // True if the given account cannot do KYC at the
  // given exchange because no wire method exists that could
  // be used to do the KYC auth wire transfer.
  auth_conflict: boolean;

  // Numeric error code indicating errors the exchange
  // returned, or TALER_EC_INVALID for none.
  // Optional (as there may not always have
  // been an error code).
  // @since protocol **v17**.
  exchange_code?: Integer;

  // Access token needed to open the KYC SPA and/or
  // access the /kyc-info/ endpoint.
  // Optional as without the KYC auth wire transfer we
  // may simply not have an access token yet.
  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[];

  // Array of full payto://-URIs with
  // wire transfer instructions (including
  // optional amount and subject) for a KYC auth wire
  // transfer. Set only if this is (still) required
  // to get the given exchange working.
  // Array because the exchange may have multiple
  // bank accounts, in which case any of these
  // accounts will do.
  // Optional.
  // @since protocol **v17**.
  payto_kycauths?: string[];

}