POST /kyc-wallet

The /kyc-wallet POST endpoint allows a wallet to notify an exchange if it will cross a balance threshold. Here, the balance specified should be the threshold (from the wallet_balance_limit_without_kyc array) that the wallet would cross, and not the exact balance of the wallet. The exchange will respond with a wire target UUID. The wallet can then use this UUID to being the KYC process at /kyc-check/. The wallet must only proceed to obtain funds exceeding the threshold after the KYC process has concluded. While wallets could be “hacked” to bypass this measure (we cannot cryptographically enforce this), such modifications are a terms of service violation which may have legal consequences for the user.

Setup KYC identification for a wallet. Returns the KYC UUID. This endpoint is used by compliant Taler wallets when they are about to hit the balance threshold and thus need to have the customer provide their personal details to the exchange. The wallet is identified by its long-lived reserve public key (which is used for P2P payments, not for withdrawals).

Request:

The request body must be a WalletKycRequest object.

Response:

200 Ok:

The balance is below the threshold that requires KYC, or this wallet already satisfied the KYC check for the given balance. The WalletKycCheckResponse body give details about the next applicable KYC check requirements.

204 No Content:

KYC is disabled at this exchange.

403 Forbidden:

The provided signature is invalid. This response comes with a standard ErrorDetail response.

451 Unavailable for Legal Reasons:

The wallet must undergo a KYC check. A KYC ID was created. The response will be a LegitimizationNeededResponse object.

Details:

 interface WalletKycRequest {

  // Balance threshold (not necessarily exact balance)
  // to be crossed by the wallet that (may) trigger
  // additional KYC requirements.
  balance: Amount;

  // EdDSA signature of the wallet affirming the
  // request, must be of purpose
  // TALER_SIGNATURE_WALLET_ACCOUNT_SETUP
  reserve_sig: EddsaSignature;

  // long-term wallet reserve-account
  // public key used to create the signature.
  reserve_pub: EddsaPublicKey;
}

interface WalletKycCheckResponse {

  // Next balance limit above which a KYC check
  // may be required. Optional, not given if no
  // threshold exists (assume infinity).
  next_threshold?: Amount;

  // When does the current set of AML/KYC rules
  // expire and the wallet needs to check again
  // for updated thresholds.
  expiration_time: Timestamp;

}