get-private-kyc.rst (10671B)
1 .. http:GET:: [/instances/$INSTANCE]/private/kyc 2 .. http:GET:: /management/instances/$INSTANCE/kyc 3 4 Check KYC status of a particular payment target. 5 Prompts the merchant to inquire with the exchange 6 as to the KYC status of the respective account 7 and returns the result. 8 9 **Required permission:** ``kyc-read`` on the ``/private`` path, 10 ``instances-kyc-read`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`) 11 12 **Request:** 13 14 *Accept*: 15 The client may specify the desired MIME-type for the result. 16 Supported are the usual "application/json", but also 17 "text/plain". 18 19 :query h_wire=H_WIRE: *Optional*. If specified, the KYC check should 20 return the KYC status only for this wire account. Otherwise, for all wire accounts. 21 :query exchange_url=URL: *Optional*. If specified, the KYC check should 22 return the KYC status only for the given exchange. Otherwise, for all exchanges we interacted with. 23 :query lpt=TARGET: *Optional*. 24 Specifies what status change we are long-polling for. 25 Use 1 to wait for the KYC auth transfer (access token available), 26 2 to wait for an AML investigation to be done, 27 and 3 to wait for the KYC status to be OK. 28 If multiple accounts or exchanges match the query, 29 any account reaching the TARGET state will cause 30 the response to be returned. 31 @since protocol **v17**. @deprecated with **v25**, use ``lp_*``-query parameters instead. 32 :query lp_status=STATUS: *Optional*. 33 Specifies what status change we are long-polling for. 34 If specified, the endpoint will only return once the status *matches* the given value. 35 If multiple accounts or exchanges match the query, 36 any account reaching the STATUS will cause the response to be returned. 37 @since protocol **v25**. 38 :query lp_not_status=STATUS: *Optional*. 39 Specifies what status change we are long-polling for. 40 If specified, the endpoint will only return once the status no longer matches the given value. 41 If multiple accounts or exchanges *no longer matches* the given STATUS 42 will cause the response to be returned. 43 @since protocol **v25**. 44 :query lp_not_etag=ETAG: *Optional*. 45 Specifies what status change we are long-polling for. 46 If specified, the endpoint will only return once the returned "Etag" 47 would differ from the ETAG specified by the client. The "Etag" 48 is computed over the entire response body, and thus assured to change 49 whenever any data point in the response changes. This is ideal for 50 clients that want to learn about any change in the response. Clients 51 using this query parameter should probably also set a "If-none-match" 52 HTTP header so that if the ``timeout_ms`` expires, they can get back 53 a "304 Not modified" with an empty body if nothing changed. 54 @since protocol **v25**. 55 :query timeout_ms=NUMBER: *Optional.* If specified, the merchant will 56 wait up to ``timeout_ms`` milliseconds for the exchanges to confirm completion of the KYC process(es). 57 58 **Response:** 59 60 :http:statuscode:`200 Ok`: 61 The user may be redirected to the provided locations to perform 62 KYC checks. 63 The response will be a `MerchantAccountKycRedirectsResponse` object. 64 Uses this status code and format only since protocol **v17**. 65 :http:statuscode:`204 No content`: 66 No possibilities for KYC operations exist. 67 @since protocol **v25** only returned if this instance has no bank 68 accounts or no exchanges are configured for the merchant backend. 69 :http:statuscode:`304 Not modified`: 70 The ``ETag`` in the response did not change compared to the one 71 given in the ``If-none-match`` HTTP header specified by the client. 72 @since protocol **v25**. 73 :http:statuscode:`400 Bad Request`: 74 A query parameter is malformed. 75 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. 76 :http:statuscode:`401 Unauthorized`: 77 The request is unauthorized. 78 Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``. 79 :http:statuscode:`404 Not found`: 80 The instance is unknown to the backend. 81 Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``. 82 :http:statuscode:`406 Not acceptable`: 83 The merchant backend could not produce a response in the desired format. 84 No error code is returned in this case. 85 :http:statuscode:`500 Internal Server Error`: 86 The server experienced an internal failure. 87 Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 88 :http:statuscode:`503 Service unavailable`: 89 The merchant backend is temporarily unable to process the request. 90 91 **Details:** 92 93 .. ts:def:: MerchantAccountKycRedirectsResponse 94 95 interface MerchantAccountKycRedirectsResponse { 96 97 // Array of KYC status information for 98 // the exchanges and bank accounts selected 99 // by the query. 100 kyc_data: MerchantAccountKycRedirect[]; 101 102 } 103 104 .. ts:def:: MerchantAccountKycRedirect 105 106 interface MerchantAccountKycRedirect { 107 108 // Summary of the status of the KYC process. Possible values are: 109 // 110 // 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**. 111 // o "no-exchange-keys": we do not (yet) have the /keys of the exchange 112 // - "kyc-wire-impossible": KYC auth transfer needed but not possible 113 // (see also: auth_conflict). 114 // @ "kyc-wire-required": KYC auth transfer still needed and possible 115 // @ "kyc-required": merchant must supply KYC data to proceed (incl. 116 // in case of exposed zero-limits on deposit/aggregation) 117 // + "awaiting-aml-review": account under review by payment provider 118 // + "ready": everything is fine, account can be fully used 119 // - "logic-bug": merchant backend logic bug 120 // o "merchant-internal-error": merchant had an internal error 121 // o "exchange-internal-error": exchange had an internal error 122 // o "exchange-gateway-timeout": network timeout at gateway 123 // o "exchange-unreachable": exchange did not respond at all to our KYC status inquiry 124 // this can be briefly the case even if an exchange is online, as any HTTP request 125 // takes time to be processed; as a result, the KYC status for this account is unknown 126 // - "exchange-status-invalid": exchange violated protocol in reply 127 // 128 // "+" are perfectly normal states, "@" are states where the user 129 // must performn an action (show link!); "o" are reasonable transient 130 // states that could happen and are we are expected to likely recover 131 // from automatically but that we should inform the user about 132 // (show in yellow?), "-" are hard error states from which 133 // there is likely no good automatic recovery from (show in red?). 134 status: string; 135 136 // Full payto URI of the bank wire account this is about. 137 payto_uri: string; 138 139 // Currency used by the exchange. 140 // @since protocol **v25**. 141 exchange_currency: string; 142 143 // Hash of the salted payto://-URI of our bank wire 144 // account this is about. 145 // @since protocol **v17**. 146 h_wire: string; 147 148 // Base URL of the exchange this is about. 149 exchange_url: WebURL; 150 151 // HTTP status code returned by the exchange when we asked for 152 // information about the KYC status. 153 // @since protocol **v17**. 154 exchange_http_status: Integer; 155 156 // True if we did not get a ``/keys`` response from 157 // the exchange and thus cannot do certain checks, such as 158 // determining default account limits or account eligibility. 159 no_keys: boolean; 160 161 // True if the given account cannot do KYC at the 162 // given exchange because no wire method exists that could 163 // be used to do the KYC auth wire transfer. 164 auth_conflict: boolean; 165 166 // Numeric `error code <error-codes>` indicating errors the exchange 167 // returned, or TALER_EC_INVALID for none. 168 // Optional (as there may not always have 169 // been an error code). 170 // @since protocol **v17**. 171 exchange_code?: Integer; 172 173 // Access token needed to open the KYC SPA and/or 174 // access the ``/kyc-info/`` endpoint. 175 // Optional as without the KYC auth wire transfer we 176 // may simply not have an access token yet. 177 access_token?: AccountAccessToken; 178 179 // Array with limitations that currently apply to this 180 // account and that may be increased or lifted if the 181 // KYC check is passed. 182 // Note that additional limits *may* exist and not be 183 // communicated to the client. If such limits are 184 // reached, this *may* be indicated by the account 185 // going into ``aml_review`` state. However, it is 186 // also possible that the exchange may legally have 187 // to deny operations without being allowed to provide 188 // any justification. 189 // The limits should be used by the client to 190 // possibly structure their operations (e.g. withdraw 191 // what is possible below the limit, ask the user to 192 // pass KYC checks or withdraw the rest after the time 193 // limit is passed, warn the user to not withdraw too 194 // much or even prevent the user from generating a 195 // request that would cause it to exceed hard limits). 196 limits?: AccountLimit[]; 197 198 // Array of full payto://-URIs with 199 // wire transfer instructions (including 200 // optional amount and subject) for a KYC auth wire 201 // transfer. Set only if this is (still) required 202 // to get the given exchange working. 203 // Array because the exchange may have multiple 204 // bank accounts, in which case any of these 205 // accounts will do. 206 // Optional. 207 // @since protocol **v17**. 208 payto_kycauths?: string[]; 209 210 // Forwarded value of the ``kyc_swap_tos_acceptance`` flag 211 // that the merchant backend observed in the exchange's 212 // ``/keys`` response. Signals to the frontend that it 213 // should swap the terms-of-service and KYC auth 214 // authentication steps in the user experience. 215 // Optional, defaults to false if not given. 216 // @since protocol **v31**. 217 kyc_swap_tos_acceptance?: boolean; 218 219 // ``Taler-Terms-Version`` (see exchange's ``/terms`` 220 // endpoint) of the terms of service that were already 221 // accepted by the user for this exchange. Optional, 222 // absent if no version has been accepted yet by the 223 // user via ``POST /private/accept-tos-early``. 224 // @since protocol **v31**. 225 tos_accepted_early?: string; 226 227 228 }