get-kyc-check-H_NORMALIZED_PAYTO.rst (7703B)
1 .. http:get:: /kyc-check/$H_NORMALIZED_PAYTO 2 3 Checks the KYC status of a particular payment target. That information 4 allows the customer to choose the next KYC measure to satisfy, if any. 5 This endpoint is typically used by wallets or merchants that 6 have been told that a transaction is not happening because it triggered 7 some KYC/AML measure and now want to check how the KYC/AML 8 requirement could be fulfilled (or whether it already has been 9 statisfied and the operation can now proceed). Long-polling may be used 10 to instantly observe a change in the KYC requirement status. 11 12 Given a valid pair of a normalized payto hash and account owner signature, the 13 ``/kyc-check/`` endpoint returns either just the KYC status or redirects the 14 client (202) to the next required stage of the KYC process. The redirection 15 must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. It 16 must always be the same endpoint for the same client, as the wallet/merchant 17 backend are not required to check for changes to this endpoint. Clients 18 that received a 202 status code may repeat the request and use long-polling 19 to detect a change of the HTTP status. 20 21 This endpoint exists in this specific form only since protocol **v21**. 22 23 **Request:** 24 25 *Account-Owner-Signature*: 26 The client must provide Base-32 encoded EdDSA signature with 27 ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data. Note that 28 this is merely a simple authentication mechanism, the details of the 29 request are not protected by the signature. The ``$ACCOUNT_PRIV`` is 30 either the (wallet long-term) reserve private key or the merchant instance 31 private key. 32 33 *Account-Owner-Pub*: 34 The client should provide the Base-32 encoded EdDSA public key of 35 ``$ACCOUNT_PUB``, enabling the exchange to easily locate the correct 36 public key used for the signature in case multiple wire transfers 37 were made to the account in the past. 38 39 :query lpt=TARGET: *Optional*. 40 Specifies what status change we are long-polling for. 41 Use 1 to wait for the KYC auth transfer (access token available), 42 2 to wait for an AML investigation to be done, 43 and 3 to wait for the KYC status to be OK. 44 @since protocol **v21**. 45 :query min_rule=NUMBER: *Optional*. 46 Specifies the ``rule_num`` of the previous ``kyc-check`` 47 already known to the client. When long-polling, the server 48 should always respond when it has a more recent rule. 49 @since protocol **v26**. 50 :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will 51 wait up to ``timeout_ms`` milliseconds if the requirement continues 52 to be mandatory provisioning of KYC data by the client. 53 Ignored if the HTTP status code is already ``200 Ok``. Note that 54 clients cannot long-poll for AML staff actions, so status information 55 about an account being under AML review needs to be requested 56 periodically. 57 58 **Response:** 59 60 :http:statuscode:`200 Ok`: 61 No mandatory KYC actions are required by the client at this time. 62 The client *may* still visit the KYC URL to initiate voluntary checks. 63 The response will be an `AccountKycStatus` object which specifies 64 restrictions that currently apply to the account. If the 65 client attempts to exceed *soft* limits, the status may change 66 to a ``202 Accepted``. Hard limits cannot be lifted by passing KYC checks. 67 :http:statuscode:`202 Accepted`: 68 The account holder performed an operation that would have crossed 69 limits (hard or soft) and must be redirected to the provided location to perform 70 the required KYC checks to satisfy the legal requirements. Afterwards, the 71 ``/kyc-check/`` request should be repeated to check whether the 72 user has completed the process. 73 The response will be an `AccountKycStatus` object. 74 :http:statuscode:`204 No content`: 75 The exchange is not configured to perform KYC and thus 76 the legal requirements are already satisfied. 77 :http:statuscode:`400 Bad Request`: 78 The ``$H_NORMALIZED_PAYTO`` path segment is malformed. 79 This response comes with a standard `ErrorDetail` response with 80 a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. 81 :http:statuscode:`403 Forbidden`: 82 The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key. 83 :http:statuscode:`404 Not found`: 84 The account identified by the normalized payto hash is unknown. 85 This response comes with a standard `ErrorDetail` response with 86 a code of ``TALER_EC_EXCHANGE_KYC_CHECK_REQUEST_UNKNOWN``. 87 :http:statuscode:`409 Conflict`: 88 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. 89 This response comes with a standard `ErrorDetail` response with 90 a code of ``TALER_EC_EXCHANGE_KYC_CHECK_AUTHORIZATION_KEY_UNKNOWN``. 91 :http:statuscode:`500 Internal Server Error`: 92 The exchange had an internal error processing the request. 93 This response comes with a standard `ErrorDetail` response. 94 Possible error codes include 95 ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``. 96 97 **Details:** 98 99 .. ts:def:: KycCheckAccountExpectedResponse 100 101 interface KycCheckAccountExpectedResponse { 102 103 // Taler error code, ``TALER_EC_EXCHANGE_KYC_CHECK_AUTHORIZATION_FAILED``. 104 code: Integer; 105 106 // Public key for which the signature must be 107 // valid to authorize this request. 108 expected_account_pub: EddsaPublicKey; 109 } 110 111 .. ts:def:: AccountKycStatus 112 113 interface AccountKycStatus { 114 115 // Current AML state for the target account. True if 116 // operations are not happening due to staff processing 117 // paperwork *or* due to legal requirements (so the 118 // client cannot do anything but wait). 119 // 120 // Note that not every AML staff action may be legally 121 // exposed to the client, so this is merely a hint that 122 // a client should be told that AML staff is currently 123 // reviewing the account. AML staff *may* review 124 // accounts without this flag being set! 125 aml_review: boolean; 126 127 // Monotonically increasing number identifying the decision. 128 // 0 if no decision was taken for this account. Useful for 129 // long-polling via ``min_rule`` to long-poll for any change 130 // to the rules or limits. 131 rule_gen: Integer; 132 133 // Access token needed to construct the ``/kyc-spa/`` 134 // URL that the user should open in a browser to 135 // proceed with the KYC process. 136 access_token: AccountAccessToken; 137 138 // Array with limitations that currently apply to this 139 // account and that may be increased or lifted if the 140 // KYC check is passed. 141 // Note that additional limits *may* exist and not be 142 // communicated to the client. If such limits are 143 // reached, this *may* be indicated by the account 144 // going into ``aml_review`` state. However, it is 145 // also possible that the exchange may legally have 146 // to deny operations without being allowed to provide 147 // any justification. 148 // The limits should be used by the client to 149 // possibly structure their operations (e.g. withdraw 150 // what is possible below the limit, ask the user to 151 // pass KYC checks or withdraw the rest after the time 152 // limit is passed, warn the user to not withdraw too 153 // much or even prevent the user from generating a 154 // request that would cause it to exceed hard limits). 155 limits?: AccountLimit[]; 156 157 }