get-kyc-check-H_NORMALIZED_PAYTO.rst (7768B)
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 must provide the Base-32 encoded EdDSA public key of 35 ``$ACCOUNT_PUB``, enabling the exchange to 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 This header was previously optional and is mandatory since **v34**. 39 40 :query lpt=TARGET: *Optional*. 41 Specifies what status change we are long-polling for. 42 Use 1 to wait for the KYC auth transfer (access token available), 43 2 to wait for an AML investigation to be done, 44 and 3 to wait for the KYC status to be OK. 45 @since protocol **v21**. 46 :query min_rule=NUMBER: *Optional*. 47 Specifies the ``rule_num`` of the previous ``kyc-check`` 48 already known to the client. When long-polling, the server 49 should always respond when it has a more recent rule. 50 @since protocol **v26**. 51 :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will 52 wait up to ``timeout_ms`` milliseconds if the requirement continues 53 to be mandatory provisioning of KYC data by the client. 54 Ignored if the HTTP status code is already ``200 Ok``. Note that 55 clients cannot long-poll for AML staff actions, so status information 56 about an account being under AML review needs to be requested 57 periodically. 58 59 **Response:** 60 61 :http:statuscode:`200 Ok`: 62 No mandatory KYC actions are required by the client at this time. 63 The client *may* still visit the KYC URL to initiate voluntary checks. 64 The response will be an `AccountKycStatus` object which specifies 65 restrictions that currently apply to the account. If the 66 client attempts to exceed *soft* limits, the status may change 67 to a ``202 Accepted``. Hard limits cannot be lifted by passing KYC checks. 68 :http:statuscode:`202 Accepted`: 69 The account holder performed an operation that would have crossed 70 limits (hard or soft) and must be redirected to the provided location to perform 71 the required KYC checks to satisfy the legal requirements. Afterwards, the 72 ``/kyc-check/`` request should be repeated to check whether the 73 user has completed the process. 74 The response will be an `AccountKycStatus` object. 75 :http:statuscode:`204 No content`: 76 The exchange is not configured to perform KYC and thus 77 the legal requirements are already satisfied. 78 :http:statuscode:`400 Bad Request`: 79 The ``$H_NORMALIZED_PAYTO`` path segment is malformed. 80 This response comes with a standard `ErrorDetail` response with 81 a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. 82 :http:statuscode:`403 Forbidden`: 83 The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key. 84 :http:statuscode:`404 Not found`: 85 The account identified by the normalized payto hash is unknown. 86 This response comes with a standard `ErrorDetail` response with 87 a code of ``TALER_EC_EXCHANGE_KYC_CHECK_REQUEST_UNKNOWN``. 88 :http:statuscode:`409 Conflict`: 89 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. 90 This response comes with a standard `ErrorDetail` response with 91 a code of ``TALER_EC_EXCHANGE_KYC_CHECK_AUTHORIZATION_KEY_UNKNOWN``. 92 :http:statuscode:`500 Internal Server Error`: 93 The exchange had an internal error processing the request. 94 This response comes with a standard `ErrorDetail` response. 95 Possible error codes include 96 ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``. 97 98 **Details:** 99 100 .. ts:def:: KycCheckAccountExpectedResponse 101 102 interface KycCheckAccountExpectedResponse { 103 104 // Taler error code, ``TALER_EC_EXCHANGE_KYC_CHECK_AUTHORIZATION_FAILED``. 105 code: Integer; 106 107 // Public key for which the signature must be 108 // valid to authorize this request. 109 expected_account_pub: EddsaPublicKey; 110 } 111 112 .. ts:def:: AccountKycStatus 113 114 interface AccountKycStatus { 115 116 // Current AML state for the target account. True if 117 // operations are not happening due to staff processing 118 // paperwork *or* due to legal requirements (so the 119 // client cannot do anything but wait). 120 // 121 // Note that not every AML staff action may be legally 122 // exposed to the client, so this is merely a hint that 123 // a client should be told that AML staff is currently 124 // reviewing the account. AML staff *may* review 125 // accounts without this flag being set! 126 aml_review: boolean; 127 128 // Monotonically increasing number identifying the decision. 129 // 0 if no decision was taken for this account. Useful for 130 // long-polling via ``min_rule`` to long-poll for any change 131 // to the rules or limits. 132 rule_gen: Integer; 133 134 // Access token needed to construct the ``/kyc-spa/`` 135 // URL that the user should open in a browser to 136 // proceed with the KYC process. 137 access_token: AccountAccessToken; 138 139 // Array with limitations that currently apply to this 140 // account and that may be increased or lifted if the 141 // KYC check is passed. 142 // Note that additional limits *may* exist and not be 143 // communicated to the client. If such limits are 144 // reached, this *may* be indicated by the account 145 // going into ``aml_review`` state. However, it is 146 // also possible that the exchange may legally have 147 // to deny operations without being allowed to provide 148 // any justification. 149 // The limits should be used by the client to 150 // possibly structure their operations (e.g. withdraw 151 // what is possible below the limit, ask the user to 152 // pass KYC checks or withdraw the rest after the time 153 // limit is passed, warn the user to not withdraw too 154 // much or even prevent the user from generating a 155 // request that would cause it to exceed hard limits). 156 limits?: AccountLimit[]; 157 158 }