taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-kyc-wallet.rst (2934B)

      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.
     39   :http:statuscode:`451 Unavailable for Legal Reasons`:
     40     The wallet must undergo a KYC check. A KYC ID was created.
     41     The response will be a `LegitimizationNeededResponse` object.
     42 
     43   **Details:**
     44 
     45   .. ts:def:: WalletKycRequest
     46 
     47      interface WalletKycRequest {
     48 
     49       // Balance threshold (not necessarily exact balance)
     50       // to be crossed by the wallet that (may) trigger
     51       // additional KYC requirements.
     52       balance: Amount;
     53 
     54       // EdDSA signature of the wallet affirming the
     55       // request, must be of purpose
     56       // ``TALER_SIGNATURE_WALLET_ACCOUNT_SETUP``
     57       reserve_sig: EddsaSignature;
     58 
     59       // long-term wallet reserve-account
     60       // public key used to create the signature.
     61       reserve_pub: EddsaPublicKey;
     62     }
     63 
     64   .. ts:def:: WalletKycCheckResponse
     65 
     66      interface WalletKycCheckResponse {
     67 
     68        // Next balance limit above which a KYC check
     69        // may be required. Optional, not given if no
     70        // threshold exists (assume infinity).
     71        next_threshold?: Amount;
     72 
     73        // When does the current set of AML/KYC rules
     74        // expire and the wallet needs to check again
     75        // for updated thresholds.
     76        expiration_time: Timestamp;
     77 
     78      }