get-kyc-check-H_NORMALIZED_PAYTO.rst (6961B)
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:`403 Forbidden`: 78 The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key. 79 :http:statuscode:`404 Not found`: 80 The account identified by the normalized payto hash is unknown. 81 :http:statuscode:`409 Conflict`: 82 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. 83 84 **Details:** 85 86 .. ts:def:: KycCheckAccountExpectedResponse 87 88 interface KycCheckAccountExpectedResponse { 89 90 // Public key for which the signature must be 91 // valid to authorize this request. 92 expected_account_pub: EddsaPublicKey; 93 } 94 95 .. ts:def:: AccountKycStatus 96 97 interface AccountKycStatus { 98 99 // Current AML state for the target account. True if 100 // operations are not happening due to staff processing 101 // paperwork *or* due to legal requirements (so the 102 // client cannot do anything but wait). 103 // 104 // Note that not every AML staff action may be legally 105 // exposed to the client, so this is merely a hint that 106 // a client should be told that AML staff is currently 107 // reviewing the account. AML staff *may* review 108 // accounts without this flag being set! 109 aml_review: boolean; 110 111 // Monotonically increasing number identifying the decision. 112 // 0 if no decision was taken for this account. Useful for 113 // long-polling via ``min_rule`` to long-poll for any change 114 // to the rules or limits. 115 rule_gen: Integer; 116 117 // Access token needed to construct the ``/kyc-spa/`` 118 // URL that the user should open in a browser to 119 // proceed with the KYC process (optional if the status 120 // type is ``200 Ok``, mandatory if the HTTP status 121 // is ``202 Accepted``). 122 access_token: AccountAccessToken; 123 124 // Array with limitations that currently apply to this 125 // account and that may be increased or lifted if the 126 // KYC check is passed. 127 // Note that additional limits *may* exist and not be 128 // communicated to the client. If such limits are 129 // reached, this *may* be indicated by the account 130 // going into ``aml_review`` state. However, it is 131 // also possible that the exchange may legally have 132 // to deny operations without being allowed to provide 133 // any justification. 134 // The limits should be used by the client to 135 // possibly structure their operations (e.g. withdraw 136 // what is possible below the limit, ask the user to 137 // pass KYC checks or withdraw the rest after the time 138 // limit is passed, warn the user to not withdraw too 139 // much or even prevent the user from generating a 140 // request that would cause it to exceed hard limits). 141 limits?: AccountLimit[]; 142 143 }