post-kyc-wallet.rst (3700B)
1 .. http:post:: /kyc-wallet 2 3 The ``/kyc-wallet`` POST endpoint allows a wallet to notify an exchange if 4 it will cross a balance threshold. Here, the ``balance`` specified should be 5 the threshold (from the ``wallet_balance_limit_without_kyc`` array) that the 6 wallet would cross, and *not* the *exact* balance of the wallet. The exchange 7 will respond with a wire target UUID. The wallet can then use this UUID to 8 being the KYC process at ``/kyc-check/``. The wallet must only proceed to 9 obtain funds exceeding the threshold after the KYC process has concluded. 10 While wallets could be "hacked" to bypass this measure (we cannot 11 cryptographically enforce this), such modifications are a terms of service 12 violation which may have legal consequences for the user. 13 14 Setup KYC identification for a wallet. Returns the KYC UUID. 15 This endpoint is used by compliant Taler wallets when they 16 are about to hit the balance threshold and thus need to have 17 the customer provide their personal details to the exchange. 18 The wallet is identified by its long-lived reserve public key 19 (which is used for P2P payments, not for withdrawals). 20 21 **Request:** 22 23 The request body must be a `WalletKycRequest` object. 24 25 **Response:** 26 27 :http:statuscode:`200 Ok`: 28 The balance 29 is below the threshold that requires KYC, or this 30 wallet already satisfied the KYC check for the 31 given balance. The `WalletKycCheckResponse` body 32 give details about the next applicable KYC check 33 requirements. 34 :http:statuscode:`204 No Content`: 35 KYC is disabled at this exchange. 36 :http:statuscode:`403 Forbidden`: 37 The provided signature is invalid. 38 This response comes with a standard `ErrorDetail` response with 39 a code of ``TALER_EC_EXCHANGE_KYC_WALLET_SIGNATURE_INVALID``. 40 :http:statuscode:`413 Request entity too large`: 41 The uploaded body is to long, it exceeds the size limit. 42 Returned with an error code of 43 ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 44 :http:statuscode:`500 Internal server error`: 45 The server had an internal error processing the request. 46 Returned with one of various error codes, including: 47 48 - ``TALER_EC_EXCHANGE_KYC_GENERIC_AML_LOGIC_BUG`` 49 - ``TALER_EC_GENERIC_DB_STORE_FAILED`` 50 - ``TALER_EC_EXCHANGE_KYC_RECURSIVE_RULE_DETECTED`` 51 - ``TALER_EC_GENERIC_DB_FETCH_FAILED`` 52 - ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` 53 - ``TALER_EC_EXCHANGE_KYC_AML_PROGRAM_FAILURE`` 54 - ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` 55 - ``TALER_EC_EXCHANGE_GENERIC_KYC_FALLBACK_FAILED`` 56 - ``TALER_EC_EXCHANGE_KYC_AML_PROGRAM_MALFORMED_RESULT`` 57 - ``TALER_EC_EXCHANGE_GENERIC_KYC_FALLBACK_UNKNOWN`` 58 59 **Details:** 60 61 .. ts:def:: WalletKycRequest 62 63 interface WalletKycRequest { 64 65 // Balance threshold (not necessarily exact balance) 66 // to be crossed by the wallet that (may) trigger 67 // additional KYC requirements. 68 balance: Amount; 69 70 // EdDSA signature of the wallet affirming the 71 // request, must be of purpose 72 // ``TALER_SIGNATURE_WALLET_ACCOUNT_SETUP`` 73 reserve_sig: EddsaSignature; 74 75 // long-term wallet reserve-account 76 // public key used to create the signature. 77 reserve_pub: EddsaPublicKey; 78 } 79 80 .. ts:def:: WalletKycCheckResponse 81 82 interface WalletKycCheckResponse { 83 84 // Next balance limit above which a KYC check 85 // may be required. Optional, not given if no 86 // threshold exists (assume infinity). 87 next_threshold?: Amount; 88 89 // When does the current set of AML/KYC rules 90 // expire and the wallet needs to check again 91 // for updated thresholds. 92 expiration_time: Timestamp; 93 94 }