diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 3051 |
1 files changed, 2069 insertions, 982 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index c5a67832..fcd0122f 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2022 Taler Systems SA + Copyright (C) 2014-2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -24,6 +24,9 @@ for all details not specified in the individual requests. The `glossary <https://docs.taler.net/glossary.html#glossary>`_ defines all specific terms used in this section. +.. contents:: Table of Contents + :local: + .. include:: tos.rst .. _keys: @@ -53,6 +56,75 @@ possibly by using HTTPS. returned MUST be mixed with locally generated entropy. +.. http:get:: /config + + Return the protocol version and currency supported by this exchange backend, + as well as the list of possible KYC requirements. This endpoint is largely + for the SPA for AML officers. Merchants should use ``/keys`` which also + contains the protocol version and currency. + This specification corresponds to ``current`` protocol being **v20**. + + **Response:** + + :http:statuscode:`200 OK`: + The body is a `VersionResponse`. + + .. ts:def:: ExchangeVersionResponse + + interface ExchangeVersionResponse { + // libtool-style representation of the Exchange protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Name of the protocol. + name: "taler-exchange"; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since **v18**, may become mandatory in the future. + implementation?: string; + + // Currency supported by this exchange, given + // as a currency code ("USD" or "EUR"). + currency: string; + + // How wallets should render this currency. + currency_specification: CurrencySpecification; + + // Names of supported KYC requirements. + supported_kyc_requirements: string[]; + + } + + .. ts:def:: CurrencySpecification + + interface CurrencySpecification { + // Name of the currency. Like "US Dollar". + name: string; + + // Code of the currency. + // Deprecated in protocol **v18** for the exchange + // and in protocol v6 for the merchant. + currency: string; + + // how many digits the user may enter after the decimal_separator + num_fractional_input_digits: Integer; + + // Number of fractional digits to render in normal font and size. + num_fractional_normal_digits: Integer; + + // Number of fractional digits to render always, if needed by + // padding with zeros. + num_fractional_trailing_zero_digits: Integer; + + // map of powers of 10 to alternative currency names / symbols, must + // always have an entry under "0" that defines the base name, + // e.g. "0 => €" or "3 => k€". For BTC, would be "0 => BTC, -3 => mBTC". + // Communicates the currency symbol to be used. + alt_unit_names: { log10 : string }; + } + + .. http:get:: /keys Get a list of all denomination keys offered by the exchange, @@ -82,9 +154,52 @@ possibly by using HTTPS. // The exchange's base URL. base_url: string; - // The exchange's currency. + // The exchange's currency or asset unit. currency: string; + // How wallets should render this currency. + currency_specification: CurrencySpecification; + + // Absolute cost offset for the STEFAN curve used + // to (over) approximate fees payable by amount. + stefan_abs: Amount; + + // Factor to multiply the logarithm of the amount + // with to (over) approximate fees payable by amount. + // Note that the total to be paid is first to be + // divided by the smallest denomination to obtain + // the value that the logarithm is to be taken of. + stefan_log: Amount; + + // Linear cost factor for the STEFAN curve used + // to (over) approximate fees payable by amount. + // + // Note that this is a scalar, as it is multiplied + // with the actual amount. + stefan_lin: Float; + + // Type of the asset. "fiat", "crypto", "regional" + // or "stock". Wallets should adjust their UI/UX + // based on this value. + asset_type: string; + + // Array of wire accounts operated by the exchange for + // incoming wire transfers. + accounts: WireAccount[]; + + // Object mapping names of wire methods (i.e. "iban" or "x-taler-bank") + // to wire fees. + wire_fees: { method : AggregateTransferFee[] }; + + // List of exchanges that this exchange is partnering + // with to enable wallet-to-wallet transfers. + wads: ExchangePartner[]; + + // Set to true if this exchange allows the use + // of reserves for rewards. + // @deprecated in protocol **v18**. + rewards_allowed: false; + // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. master_public_key: EddsaPublicKey; @@ -99,18 +214,20 @@ possibly by using HTTPS. // Currency must match ``currency``. wallet_balance_limit_without_kyc?: Amount[]; - // Denominations offered by this exchange. - // DEPRECATED: Will eventually be replaced by the - // differently structured "denominations" field. - denoms: Denom[]; - // Denominations offered by this exchange denominations: DenomGroup[]; - // Compact EdDSA `signature` (binary-only) over the XOR of all - // .hash fields (in binary) in the list "denominations". - // Signature of `TALER_ExchangeKeySetPS` - denominations_sig: EddsaSignature; + // Compact EdDSA `signature` (binary-only) over the + // contatentation of all of the master_sigs (in reverse + // chronological order by group) in the arrays under + // "denominations". Signature of `TALER_ExchangeKeySetPS` + exchange_sig: EddsaSignature; + + // Public EdDSA key of the exchange that was used to generate the signature. + // Should match one of the exchange's signing keys from ``signkeys``. It is given + // explicitly as the client might otherwise be confused by clock skew as to + // which signing key was used for the ``exchange_sig``. + exchange_pub: EddsaPublicKey; // Denominations for which the exchange currently offers/requests recoup. recoup: Recoup[]; @@ -127,24 +244,99 @@ possibly by using HTTPS. // The exchange's signing keys. signkeys: SignKey[]; - // Compact EdDSA `signature` (binary-only) over the SHA-512 hash of the - // concatenation of all SHA-512 hashes of the RSA denomination public keys - // in ``denoms`` in the same order as they were in ``denoms``. Note that for - // hashing, the binary format of the RSA public keys is used, and not their - // `base32 encoding <base32>`. Wallets cannot do much with this signature by itself; - // it is only useful when multiple clients need to establish that the exchange - // is sabotaging end-user anonymity by giving disjoint denomination keys to - // different users. If an exchange were to do this, this signature allows the - // clients to demonstrate to the public that the exchange is dishonest. - // Signature of `TALER_ExchangeKeySetPS` - // DEPRICATED: Will eventually replaced by "denominations_sig" - eddsa_sig: EddsaSignature; + // Optional field with a dictionary of (name, object) pairs defining the + // supported and enabled extensions, such as ``age_restriction``. + extensions?: { name: ExtensionManifest }; + + // Signature by the exchange master key of the SHA-256 hash of the + // normalized JSON-object of field extensions, if it was set. + // The signature has purpose TALER_SIGNATURE_MASTER_EXTENSIONS. + extensions_sig?: EddsaSignature; + + } + + The specification for the account object is: + + .. ts:def:: WireAccount + + interface WireAccount { + // ``payto://`` URI identifying the account and wire method + payto_uri: string; + + // URI to convert amounts from or to the currency used by + // this wire account of the exchange. Missing if no + // conversion is applicable. + conversion_url?: string; + + // Restrictions that apply to bank accounts that would send + // funds to the exchange (crediting this exchange bank account). + // Optional, empty array for unrestricted. + credit_restrictions: AccountRestriction[]; + + // Restrictions that apply to bank accounts that would receive + // funds from the exchange (debiting this exchange bank account). + // Optional, empty array for unrestricted. + debit_restrictions: AccountRestriction[]; + + // Signature using the exchange's offline key over + // a `TALER_MasterWireDetailsPS` + // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. + master_sig: EddsaSignature; + + // Display label wallets should use to show this + // bank account. + // Since protocol **v19**. + bank_label?: string; + + // *Signed* integer with the display priority for + // this bank account. Optional, 0 if missing. + // Since protocol **v19**. + priority?: Integer; + + } + + .. ts:def:: AccountRestriction + + type AccountRestriction = + | RegexAccountRestriction + | DenyAllAccountRestriction + + .. ts:def:: DenyAllAccountRestriction + + // Account restriction that disables this type of + // account for the indicated operation categorically. + interface DenyAllAccountRestriction { + + type: "deny"; + } + + .. ts:def:: RegexAccountRestriction + + // Accounts interacting with this type of account + // restriction must have a payto://-URI matching + // the given regex. + interface RegexAccountRestriction { + + type: "regex"; + + // Regular expression that the payto://-URI of the + // partner account must follow. The regular expression + // should follow posix-egrep, but without support for character + // classes, GNU extensions, back-references or intervals. See + // https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html + // for a description of the posix-egrep syntax. Applications + // may support regexes with additional features, but exchanges + // must not use such regexes. + payto_regex: string; + + // Hint for a human to understand the restriction + // (that is hopefully easier to comprehend than the regex itself). + human_hint: string; + + // Map from IETF BCP 47 language tags to localized + // human hints. + human_hint_i18n?: { [lang_tag: string]: string }; - // Public EdDSA key of the exchange that was used to generate the signature. - // Should match one of the exchange's signing keys from ``/keys``. It is given - // explicitly as the client might otherwise be confused by clock skew as to - // which signing key was used. - eddsa_pub: EddsaPublicKey; } .. ts:def:: GlobalFees @@ -194,7 +386,6 @@ possibly by using HTTPS. } - .. ts:def:: AgeMask // Binary representation of the age groups. @@ -280,10 +471,6 @@ possibly by using HTTPS. // Fee charged by the exchange for refunding a coin of this denomination. fee_refund: Amount; - // XOR of all the SHA-512 hash values of the denominations' public keys - // in this group. Note that for hashing, the binary format of the - // public keys is used, and not their base32 encoding. - hash: HashCode; } .. ts:def:: DenomCommon @@ -295,51 +482,27 @@ possibly by using HTTPS. // When does the denomination key become valid? stamp_start: Timestamp; - // When is it no longer possible to deposit coins + // When is it no longer possible to withdraw coins // of this denomination? stamp_expire_withdraw: Timestamp; - // Timestamp indicating by when legal disputes relating to these coins must - // be settled, as the exchange will afterwards destroy its evidence relating to - // transactions involving this coin. - stamp_expire_legal: Timestamp; - } - - .. ts:def:: Denom - - interface Denom { - // How much are coins of this denomination worth? - value: Amount; - - // When does the denomination key become valid? - stamp_start: Timestamp; - // When is it no longer possible to deposit coins // of this denomination? - stamp_expire_withdraw: Timestamp; + stamp_expire_deposit: Timestamp; // Timestamp indicating by when legal disputes relating to these coins must // be settled, as the exchange will afterwards destroy its evidence relating to // transactions involving this coin. stamp_expire_legal: Timestamp; - // Public key for the denomination. - denom_pub: DenominationKey; - - // Fee charged by the exchange for withdrawing a coin of this denomination. - fee_withdraw: Amount; - - // Fee charged by the exchange for depositing a coin of this denomination. - fee_deposit: Amount; - - // Fee charged by the exchange for refreshing a coin of this denomination. - fee_refresh: Amount; - - // Fee charged by the exchange for refunding a coin of this denomination. - fee_refund: Amount; - - // Signature of `TALER_DenominationKeyValidityPS`. - master_sig: EddsaSignature; + // Set to 'true' if the exchange somehow "lost" + // the private key. The denomination was not + // necessarily revoked, but still cannot be used + // to withdraw coins at this time (theoretically, + // the private key could be recovered in the + // future; coins signed with the private key + // remain valid). + lost?: boolean; } .. ts:def:: DenominationKey @@ -463,53 +626,6 @@ possibly by using HTTPS. Both the individual denominations *and* the denomination list is signed, allowing customers to prove that they received an inconsistent list. -.. _wire-req: - -.. http:get:: /wire - - Returns a list of payment methods supported by the exchange. The idea is that wallets may use this information to instruct users on how to perform wire transfers to top up their wallets. - - **Response:** - - :http:statuscode:`200 Ok`: - The exchange responds with a `WireResponse` object. This request should virtually always be successful. - - **Details:** - - .. ts:def:: WireResponse - - interface WireResponse { - - // Master public key of the exchange, must match the key returned in ``/keys``. - master_public_key: EddsaPublicKey; - - // Array of wire accounts operated by the exchange for - // incoming wire transfers. - accounts: WireAccount[]; - - // Object mapping names of wire methods (i.e. "iban" or "x-taler-bank") - // to wire fees. - fees: { method : AggregateTransferFee }; - - // List of exchanges that this exchange is partnering - // with to enable wallet-to-wallet transfers. - wads: ExchangePartner[]; - } - - The specification for the account object is: - - .. ts:def:: WireAccount - - interface WireAccount { - // ``payto://`` URI identifying the account and wire method - payto_uri: string; - - // Signature using the exchange's offline key over - // a `TALER_MasterWireDetailsPS` - // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. - master_sig: EddsaSignature; - } - Aggregate wire transfer fees representing the fees the exchange charges per wire transfer to a merchant must be specified as an array in all wire transfer response objects under ``fees``. The @@ -524,9 +640,6 @@ possibly by using HTTPS. // Per transfer closing fee. closing_fee: Amount; - // Per exchange-to-exchange transfer (wad) fee. - wad_fee: Amount; - // What date (inclusive) does this fee go into effect? // The different fees must cover the full time period in which // any of the denomination keys are valid without overlap. @@ -551,6 +664,9 @@ possibly by using HTTPS. // Public master key of the partner exchange. partner_master_pub: EddsaPublicKey; + // Per exchange-to-exchange transfer (wad) fee. + wad_fee: Amount; + // Exchange-to-exchange wad (wire) transfer frequency. wad_frequency: RelativeTime; @@ -635,8 +751,8 @@ Management operations authorized by master key // transactions involving this coin. stamp_expire_legal: Timestamp; - // Public (RSA) key for the denomination. - denom_pub: RsaPublicKey; + // Public key for the denomination. + denom_pub: DenominationKey; // Fee charged by the exchange for withdrawing a coin of this denomination. fee_withdraw: Amount; @@ -717,7 +833,7 @@ Management operations authorized by master key interface DenomSignature { - // Hash of the public (RSA) key of the denomination. + // Hash of the public key of the denomination. h_denom_pub: HashCode; // Signature over `TALER_DenominationKeyValidityPS`. @@ -892,7 +1008,7 @@ Management operations authorized by master key .. http:post:: /management/wire-fee - This request will be used to configure wire fees. + This request is used to configure wire fees. **Request:** @@ -997,6 +1113,16 @@ Management operations authorized by master key // become active immediately! Used ONLY to detect replay attacks. validity_start: Timestamp; + // Display label wallets should use to show this + // bank account. + // Since protocol **v19**. + bank_label?: string; + + // *Signed* integer with the display priority for + // this bank account. + // Since protocol **v19**. + priority?: Integer; + } .. http:post:: /management/wire/disable @@ -1094,13 +1220,55 @@ Management operations authorized by master key } -.. http:post:: /management/partners +.. http:post:: /management/aml-officers - Enables a partner exchange for wad transfers. + Update settings for an AML Officer status. - .. note:: + **Request:** - This is a draft API that is not yet implemented. + The request must be an `AmlOfficerSetup` message. + + **Response** + + :http:statuscode:`204 No content`: + The officer settings have been updated successfully. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`409 Conflict`: + The exchange has previously received a conflicting configuration message. + + **Details:** + + .. ts:def:: AmlOfficerSetup + + interface AmlOfficerSetup { + + // Public key of the AML officer + officer_pub: EddsaPublicKey; + + // Legal full name of the AML officer + officer_name: string; + + // Is the account active? + is_active: boolean; + + // Is the account read-only? + read_only: boolean; + + // Signature by the exchange master key over a + // `TALER_MasterAmlOfficerStatusPS`. + // Must have purpose ``TALER_SIGNATURE_MASTER_AML_KEY``. + master_sig: EddsaSignature; + + // When will the change take effect? + change_date: Timestamp; + + } + + + .. http:post:: /management/partners + + Enables a partner exchange for wad transfers. **Request:** @@ -1115,497 +1283,643 @@ Management operations authorized by master key :http:statuscode:`409 Conflict`: The exchange has previously received a conflicting configuration message. + **Details:** + .. ts:def:: ExchangePartner + interface ExchangePartner { ---------------- -Auditor actions ---------------- + // Base URL of the partner exchange + partner_base_url: string; -.. _auditor_action: + // Master (offline) public key of the partner exchange. + partner_pub: EddsaPublicKey; -This part of the API is for the use by auditors interacting with the exchange. + // How frequently will wad transfers be made + wad_frequency: RelativeTime; + // Signature by the exchange master key over a + // `TALER_PartnerConfigurationPS`. + // Must have purpose ``TALER_SIGNATURE_MASTER_PARTNER_DETAILS``. + master_sig: EddsaSignature; -.. http:post:: /auditors/$AUDITOR_PUB/$H_DENOM_PUB + // When will the partner relationship start (inclusive). + start_date: Timestamp; - This is used to add an auditor signature to the ``/keys`` response. It - affirms to wallets and merchants that this auditor is indeed auditing - the coins issued by the respective denomination. There is no "delete" - operation for this, as auditors can only stop auditing a denomination - when it expires. + // When will the partner relationship end (exclusive). + end_date: Timestamp; + + // Wad fee to be charged (to customers). + wad_fee: Amount; + + } + +-------------- +AML operations +-------------- + +This API is only for designated AML officers. It is used +to allow exchange staff to monitor suspicious transactions +and freeze or unfreeze accounts suspected of money laundering. + + +.. http:get:: /aml/$OFFICER_PUB/measures + + To enable the AML staff SPA to give AML staff a choice of possible measures, a + new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA + to dynamically GET the list of available measures. It returns a list of known + KYC checks (by name) with their descriptions and a list of AML programs with + information about the required context. + + This endpoint was introduced in protocol **v20**. **Request:** - The request must be a `AuditorSignatureAddMessage`. + *Taler-AML-Officer-Signature*: + The client must provide Base-32 encoded EdDSA signature with + ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that + this is merely a simple authentication mechanism, the details of the + request are not protected by the signature. **Response:** - :http:statuscode:`204 No content`: - The backend has successfully stored the auditor signature. - :http:statuscode:`403 Forbidden`: - The auditor signature is invalid. - :http:statuscode:`404 Not found`: - The denomination key for which the auditor is providing a signature is unknown. - The response will be a `DenominationUnknownMessage`. - :http:statuscode:`410 Gone`: - This auditor is no longer supported by the exchange. - :http:statuscode:`412 Precondition failed`: - This auditor is not yet known to the exchange. + :http:statuscode:`200 Ok`: + Information about possible measures is returned in a + `AvailableMeasureSummary` object. **Details:** - .. ts:def:: DenominationUnknownMessage + .. ts:def:: AvailableMeasureSummary - interface DenominationUnknownMessage { + interface AvailableMeasureSummary { - // Taler error code. - code: number; + // Available original measures that can be + // triggered directly by default rules. + roots: { "$measure_name" : MeasureInformation; }; - // Signature by the exchange over a - // `TALER_DenominationUnknownAffirmationPS`. - // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN``. - exchange_sig: EddsaSignature; + // Available AML programs. + programs: { "$prog_name" : AmlProgramRequirement; }; - // Public key of the exchange used to create - // the 'exchange_sig. - exchange_pub: EddsaPublicKey; + // Available KYC checks. + checks: { "$check_name" : KycCheckInformation; }; - // Hash of the denomination public key that is unknown. - h_denom_pub: HashCode; + } - // When was the signature created. - timestamp: Timestamp; + .. ts:def:: MeasureInformation + + interface MeasureInformation { + + // Name of a KYC check. + check_name: string; + + // Name of an AML program. + prog_name: string; + + // Context for the check. Optional. + context?: Object; } - .. ts:def:: AuditorSignatureAddMessage + .. ts:def:: AmlProgramRequirement - interface AuditorSignatureAddMessage { + interface AmlProgramRequirement { - // Signature by the auditor over a - // `TALER_ExchangeKeyValidityPS`. - // Must have purpose ``TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS``. - auditor_sig: EddsaSignature; + // Description of what the AML program does. + description: string; + + // List of required field names in the context to run this + // AML program. SPA must check that the AML staff is providing + // adequate CONTEXT when defining a measure using this program. + context: string[]; + + // List of required attribute names in the + // input of this AML program. These attributes + // are the minimum that the check must produce + // (it may produce more). + inputs: string[]; } + .. ts:def:: KycCheckInformation ----------- -Withdrawal ----------- + interface KycCheckInformation { -This API is used by the wallet to obtain digital coins. + // Description of the KYC check. Should be shown + // to the AML staff but will also be shown to the + // client when they initiate the check in the KYC SPA. + description: string; + description_i18n: {}; -When transferring money to the exchange such as via SEPA transfers, the exchange creates -a *reserve*, which keeps the money from the customer. The customer must -specify an EdDSA reserve public key as part of the transfer, and can then -withdraw digital coins using the corresponding private key. All incoming and -outgoing transactions are recorded under the corresponding public key by the -exchange. + // Names of the fields that the CONTEXT must provide + // as inputs to this check. + // SPA must check that the AML staff is providing + // adequate CONTEXT when defining a measure using + // this check. + requires: string[]; -.. note:: + // Names of the attributes the check will output. + // SPA must check that the outputs match the + // required inputs when combining a KYC check + // with an AML program into a measure. + outputs: string[]; - Eventually the exchange will need to advertise a policy for how long it will - keep transaction histories for inactive or even fully drained reserves. We - will therefore need some additional handler similar to ``/keys`` to - advertise those terms of service. + // Name of a root measure taken when this check fails. + fallback: string; + } +.. http:get:: /aml/$OFFICER_PUB/kyc-statistics/$NAME -.. http:get:: /reserves/$RESERVE_PUB + Returns the number of KYC events matching the given event type ``$NAME`` in + the specified time range. Note that this query can be slow as the + statistics are computed on-demand. (This is OK as such requests should be + rare.) - Request information about a reserve. + This endpoint was introduced in protocol **v20**. **Request:** - :query timeout_ms=MILLISECONDS: *Optional.* If specified, the exchange will wait up to MILLISECONDS for incoming funds before returning a 404 if the reserve does not yet exist. + *Taler-AML-Officer-Signature*: + The client must provide Base-32 encoded EdDSA signature with + ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that this + is merely a simple authentication mechanism, the details of the request are + not protected by the signature. - **Response:** + :query start_date=TIMESTAMP: + *Optional*. Specifies the date when to + start looking (inclusive). If not given, the start time of the + exchange operation is used. + :query end_date=TIMESTAMP: + *Optional*. Specifies the date when to + stop looking (exclusive). If not given, the current date is used. + **Response:** + :http:statuscode:`200 OK`: - The exchange responds with a `ReserveSummary` object; the reserve was known to the exchange. - :http:statuscode:`404 Not found`: - The reserve key does not belong to a reserve known to the exchange. + The responds will be an `EventCounter` message. **Details:** - .. ts:def:: ReserveSummary + .. ts:def:: EventCounter - interface ReserveSummary { - // Balance left in the reserve. - balance: Amount; + interface EventCounter { + // Number of events of the specified type in + // the given range. + counter: Integer; } -.. http:post:: /reserves/$RESERVE_PUB/status - - Request information about a reserve or an account. +.. http:get:: /aml/$OFFICER_PUB/decisions **Request:** - The request body must be a `ReserveStatusRequest` object. + *Taler-AML-Officer-Signature*: + The client must provide Base-32 encoded EdDSA signature with + ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that + this is merely a simple authentication mechanism, the details of the + request are not protected by the signature. + + This endpoint was introduced in this form in protocol **v20**. + + :query limit: + *Optional*. takes value of the form ``N (-N)``, so that at + most ``N`` values strictly older (younger) than ``start`` are returned. + Defaults to ``-20`` to return the last 20 entries (before ``start``). + :query offset: + *Optional*. Row number threshold, see ``delta`` for its + interpretation. Defaults to ``INT64_MAX``, namely the biggest row id + possible in the database. + :query h_payto: + *Optional*. Account selector. All matching accounts are returned if this + filter is absent, otherwise only decisions for this account. + :query active: + *Optional*. If set to yes, only return active decisions, if no only + decisions that have been superceeded. Do not give (or use "all") to + see all decisions regardless of activity status. + :query investigation: + *Optional*. If set to yes, only return accounts that are under + AML investigation, if no only accounts that are not under investigation. + Do not give (or use "all") to see all accounts regardless of + investigation status. **Response:** :http:statuscode:`200 OK`: - The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. + The responds will be an `AmlDecisions` message. + :http:statuscode:`204 No content`: + There are no matching AML records. :http:statuscode:`403 Forbidden`: - The *TALER_SIGNATURE_RESERVE_STATUS_REQUEST* signature is invalid. - This response comes with a standard `ErrorDetail` response. Alternatively, the provided timestamp is not close to the current time. + The signature is invalid. :http:statuscode:`404 Not found`: - The reserve key does not belong to a reserve known to the exchange. + The designated AML account is not known. + :http:statuscode:`409 Conflict`: + The designated AML account is not enabled. **Details:** - .. ts:def:: ReserveStatusRequest + .. ts:def:: AmlDecisions - interface ReserveStatusRequest { - // Signature of purpose - // ``TALER_SIGNATURE_RESERVE_STATUS_REQUEST`` over - // a `TALER_ReserveStatusRequestSignaturePS`. - reserve_sig: EddsaSignature; + interface AmlDecisions { - // Time when the client made the request. - // Timestamp must be reasonably close to the time of - // the exchange, otherwise the exchange may reject - // the request. - request_timestamp: Timestamp; + // Array of AML decisions matching the query. + records: AmlDecision[]; } - .. ts:def:: ReserveStatus + .. ts:def:: AmlDecision - interface ReserveStatus { - // Balance left in the reserve. - balance: Amount; + interface AmlDecision { - // Transaction history for this reserve. - // May be partial (!). - history: TransactionHistoryItem[]; - } + // Which payto-address is this record about. + // Identifies a GNU Taler wallet or an affected bank account. + h_payto: PaytoHash; - Objects in the transaction history have the following format: + // Row ID of the record. Used to filter by offset. + rowid: Integer; - .. ts:def:: TransactionHistoryItem + // When was the decision made? + decision_time: Timestamp; - // Union discriminated by the "type" field. - type TransactionHistoryItem = - | AccountMergeTransaction - | AccountSetupTransaction - | ReserveHistoryTransaction - | ReserveWithdrawTransaction - | ReserveCreditTransaction - | ReserveClosingTransaction - | ReserveOpenRequestTransaction - | ReserveCloseRequestTransaction - | PurseMergeTransaction; + // Free-form properties about the account. + // Can be used to store properties such as PEP, + // risk category, type of business, hits on + // sanctions lists, etc. + properties?: AccountProperties; - .. ts:def:: PurseMergeTransaction + // What are the new rules? + limits: LegitimizationRuleSet; - interface PurseMergeTransaction { - type: "MERGE"; + // True if the account is under investigation by AML staff + // after this decision. + to_investigate: boolean; - // SHA-512 hash of the contact of the purse. - h_contract_terms: HashCode; + // True if this is the active decision for the + // account. + is_active: boolean; - // EdDSA public key used to approve merges of this purse. - merge_pub: EddsaPublicKey; + } - // Minimum age required for all coins deposited into the purse. - min_age: Integer; + .. ts:def:: AccountProperties - // Number that identifies who created the purse - // and how it was paid for. - flags: Integer; + // All fields in this object are optional. The actual + // properties collected depend fully on the discretion + // of the exchange operator; + // however, some common fields are standardized + // and thus described here. + interface AccountProperties { - // Purse public key. - purse_pub: EddsaPublicKey; + // True if this is a politically exposed account. + // Rules for classifying accounts as politically + // exposed are country-dependent. + pep?: boolean; - // EdDSA signature of the account/reserve affirming the merge - // over a `TALER_AccountMergeSignaturePS`. - // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` - reserve_sig: EddsaSignature; + // True if this is a sanctioned account. + // Rules for classifying accounts as sanctioned + // are country-dependent. + sanctioned?: boolean; - // Client-side timestamp of when the merge request was made. - merge_timestamp: Timestamp; + // True if this is a high-risk account. + // Rules for classifying accounts as at-risk + // are exchange operator-dependent. + high_risk?: boolean; - // Indicative time by which the purse should expire - // if it has not been merged into an account. At this - // point, all of the deposits made should be - // auto-refunded. - purse_expiration: Timestamp; + // Business domain of the account owner. + // The list of possible business domains is + // operator- or country-dependent. + business_domain?: string; - // Purse fee the reserve owner paid for the purse creation. - purse_fee: Amount; + // Is the client's account currently frozen? + is_frozen?: boolean; - // Total amount merged into the reserve. - // (excludes fees). - amount: Amount; + // Was the client's account reported to the authorities? + was_reported?: boolean; - // True if the purse was actually merged. - // If false, only the purse_fee has an impact - // on the reserve balance! - merged: boolean; } - .. ts:def:: ReserveHistoryTransaction + .. ts:def:: LegitimizationRuleSet - interface ReserveHistoryTransaction { - type: "HISTORY"; + interface LegitimizationRuleSet { - // Fee agreed to by the reserve owner. - amount: Amount; - - // Time when the request was made. - request_timestamp: Timestamp; - - // Signature created with the reserve's private key. - // Must be of purpose ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` over - // a `TALER_ReserveHistoryRequestSignaturePS`. - reserve_sig: EddsaSignature; + // When does this set of rules expire and + // we automatically transition to the successor + // measure? + expiration_time: Timestamp; - } + // Name of the measure to apply when the expiration time is + // reached. If not set, we refer to the default + // set of rules (and the default account state). + successor_measure?: string; + + // Legitimization rules that are to be applied + // to this account. + rules: KycRule[]; + + // Custom measures that KYC rules and the + // ``successor_measure`` may refer to. + custom_measures: { "$measure_name" : MeasureInformation; }; + + } + + .. ts:def:: KycRule + + interface KycRule { + + // Type of operation to which the rule applies. + operation_type: string; + + // The measures will be taken if the given + // threshold is crossed over the given timeframe. + threshold: Amount; + + // Over which duration should the ``threshold`` be + // computed. All amounts of the respective + // ``operation_type`` will be added up for this + // duration and the sum compared to the ``threshold``. + timeframe: RelativeTime; + + // Array of names of measures to apply. + // Names listed can be original measures or + // custom measures from the `AmlOutcome`. + // A special measure "verboten" is used if the + // threshold may never be crossed. + measures: string[]; + + // If multiple rules apply to the same account + // at the same time, the number with the highest + // rule determines which set of measures will + // be activated and thus become visible for the + // user. + display_priority: Integer; + + // True if the rule (specifically, operation_type, + // threshold, timeframe) and the general nature of + // the measures (verboten or approval required) + // should be exposed to the client. + // Defaults to "false" if not set. + exposed?: boolean; + + // True if all the measures will eventually need to + // be satisfied, false if any of the measures should + // do. Primarily used by the SPA to indicate how + // the measures apply when showing them to the user; + // in the end, AML programs will decide after each + // measure what to do next. + // Default (if missing) is false. + is_and_combinator?: boolean; + + } + +.. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO + + Obtain attributes obtained as part of AML/KYC processes for a + given account. + + This endpoint was introduced in protocol **v20**. + + **Request:** - .. ts:def:: AccountSetupTransaction + *Taler-AML-Officer-Signature*: + The client must provide Base-32 encoded EdDSA signature with + ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that + this is merely a simple authentication mechanism, the details of the + request are not protected by the signature. + + :query limit: + *Optional*. takes value of the form ``N (-N)``, so that at + most ``N`` values strictly older (younger) than ``start`` are returned. + Defaults to ``-20`` to return the last 20 entries (before ``start``). + :query offset: + *Optional*. Row number threshold, see ``delta`` for its + interpretation. Defaults to ``INT64_MAX``, namely the biggest row id + possible in the database. - interface AccountSetupTransaction { - type: "SETUP"; + **Response:** - // KYC fee agreed to by the reserve owner. - kyc_fee: Amount; + :http:statuscode:`200 OK`: + The responds will be an `KycAttributes` message. + :http:statuscode:`204 No content`: + There are no matching KYC attributes. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`404 Not found`: + The designated AML account is not known. + :http:statuscode:`409 Conflict`: + The designated AML account is not enabled. - // Time when the KYC was triggered. - kyc_timestamp: Timestamp; + .. ts:def:: KycAttributes - // Hash of the wire details of the account. - // Note that this hash is unsalted and potentially - // private (as it could be inverted), hence access - // to this endpoint must be authorized using the - // private key of the reserve. - h_wire: HashCode; + interface KycAttributes { - // Signature created with the reserve's private key. - // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over - // a ``TALER_AccountSetupRequestSignaturePS``. - reserve_sig: EddsaSignature; + // Matching KYC attribute history of the account. + details: KycAttributeCollectionEvent[]; } - .. ts:def:: AccountMergeTransaction - - interface AccountMergeTransaction { - type: "MERGE"; - - // Actual amount merged (what was left after fees). - amount: Amount; + .. ts:def:: KycAttributeCollectionEvent - // Minimum amount merged (amount signed by the - // reserve and purse signatures). - minimum_amount: Amount; + interface KycAttributeCollectionEvent { - // Purse that was merged. - purse_pub: EddsaPublicKey; + // Row ID of the record. Used to filter by offset. + rowid: Integer; - // Time of the merge. - merge_timestamp: Timestamp; + // Name of the configuration section that specifies the provider + // which was used to collect the attributes. NULL if they were + // just uploaded via a form by the account owner. + provider_section?: string; - // Expiration time of the purse. - purse_expiration: Timestamp; + // The collected KYC data. NULL if the attribute data could not + // be decrypted (internal error of the exchange, likely the + // attribute key was changed). + attributes?: Object; - // Hash of the contract. - h_contract: HashCode; + // Time when the KYC data was collected + collection_time: Timestamp; - // Hash of the wire details of the reserve. - h_wire: HashCode; + } - // Signature created with the reserve's private key. - // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` over - // a `TALER_AccountMergeSignaturePS`. - reserve_sig: EddsaSignature; - // Signature created with the purse's private key. - // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE`` - // over a `TALER_PurseMergeSignaturePS`. - purse_sig: EddsaSignature; + .. http:post:: /aml/$OFFICER_PUB/decision - // Deposit fees that were charged to the purse. - deposit_fees: Amount; - } + Make an AML decision. Triggers the respective action and + records the justification. - .. ts:def:: ReserveWithdrawTransaction + **Request:** - interface ReserveWithdrawTransaction { - type: "WITHDRAW"; + The request must be an `AmlDecision` message. - // Amount withdrawn. - amount: Amount; + **Response** - // Hash of the denomination public key of the coin. - h_denom_pub: HashCode; + :http:statuscode:`204 No content`: + The AML decision has been executed and recorded successfully. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`404 Not found`: + The address the decision was made upon is unknown to the exchange or + the designated AML account is not known. + :http:statuscode:`409 Conflict`: + The designated AML account is not enabled or a more recent + decision was already submitted. - // Hash of the blinded coin to be signed. - h_coin_envelope: HashCode; + **Details:** - // Signature over a `TALER_WithdrawRequestPS` - // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW`` - // created with the reserve's private key. - reserve_sig: EddsaSignature; + .. ts:def:: AmlDecision - // Fee that is charged for withdraw. - withdraw_fee: Amount; - } + interface AmlDecision { + // Human-readable justification for the decision. + justification: string; - .. ts:def:: ReserveCreditTransaction + // Which payto-address is the decision about? + // Identifies a GNU Taler wallet or an affected bank account. + h_payto: PaytoHash; - interface ReserveCreditTransaction { - type: "CREDIT"; + // What are the new rules? + // New since protocol **v20**. + new_rules: LegitimizationRuleSet; - // Amount deposited. - amount: Amount; + // True if the account should remain under investigation by AML staff. + // New since protocol **v20**. + keep_investigating: boolean; - // Sender account ``payto://`` URL. - sender_account_url: string; + // Signature by the AML officer over a `TALER_AmlDecisionPS`. + // Must have purpose ``TALER_SIGNATURE_MASTER_AML_KEY``. + officer_sig: EddsaSignature; - // Opaque identifier internal to the exchange that - // uniquely identifies the wire transfer that credited the reserve. - wire_reference: Integer; + // When was the decision made? + decision_time: Timestamp; - // Timestamp of the incoming wire transfer. - timestamp: Timestamp; } - .. ts:def:: ReserveClosingTransaction +--------------- +Auditor actions +--------------- - interface ReserveClosingTransaction { - type: "CLOSING"; +.. _auditor_action: - // Closing balance. - amount: Amount; +This part of the API is for the use by auditors interacting with the exchange. - // Closing fee charged by the exchange. - closing_fee: Amount; - // Wire transfer subject. - wtid: Base32; +.. http:post:: /auditors/$AUDITOR_PUB/$H_DENOM_PUB - // ``payto://`` URI of the wire account into which the funds were returned to. - receiver_account_details: string; + This is used to add an auditor signature to the ``/keys`` response. It + affirms to wallets and merchants that this auditor is indeed auditing + the coins issued by the respective denomination. There is no "delete" + operation for this, as auditors can only stop auditing a denomination + when it expires. - // This is a signature over a - // struct `TALER_ReserveCloseConfirmationPS` with purpose - // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. - exchange_sig: EddsaSignature; + **Request:** - // Public key used to create 'exchange_sig'. - exchange_pub: EddsaPublicKey; + The request must be a `AuditorSignatureAddMessage`. - // Time when the reserve was closed. - timestamp: Timestamp; - } + **Response:** + :http:statuscode:`204 No content`: + The backend has successfully stored the auditor signature. + :http:statuscode:`403 Forbidden`: + The auditor signature is invalid. + :http:statuscode:`404 Not found`: + The denomination key for which the auditor is providing a signature is unknown. + The response will be a `DenominationUnknownMessage`. + :http:statuscode:`410 Gone`: + This auditor is no longer supported by the exchange. + :http:statuscode:`412 Precondition failed`: + This auditor is not yet known to the exchange. - .. ts:def:: ReserveOpenRequestTransaction + **Details:** - interface ReserveOpenRequestTransaction { - type: "OPEN"; + .. ts:def:: DenominationUnknownMessage - // Open fee paid from the reserve. - open_fee: Amount; + interface DenominationUnknownMessage { - // This is a signature over - // a struct `TALER_ReserveOpenPS` with purpose - // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN``. - reserve_sig: EddsaSignature; + // Taler error code. + code: number; - // Timestamp of the open request. - request_timestamp: Timestamp; + // Signature by the exchange over a + // `TALER_DenominationUnknownAffirmationPS`. + // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN``. + exchange_sig: EddsaSignature; - // Requested expiration. - requested_expiration: Timestamp; + // Public key of the exchange used to create + // the 'exchange_sig. + exchange_pub: EddsaPublicKey; - // Requested number of free open purses. - requested_min_purses: Integer; + // Hash of the denomination public key that is unknown. + h_denom_pub: HashCode; - } + // When was the signature created. + timestamp: Timestamp; - .. ts:def:: ReserveCloseRequestTransaction + } - interface ReserveCloseRequestTransaction { - type: "CLOSE"; + .. ts:def:: AuditorSignatureAddMessage - // This is a signature over - // a struct `TALER_ReserveClosePS` with purpose - // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE``. - reserve_sig: EddsaSignature; + interface AuditorSignatureAddMessage { - // Target account ``payto://``, optional. - h_payto?: string; + // Signature by the auditor over a + // `TALER_ExchangeKeyValidityPS`. + // Must have purpose ``TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS``. + auditor_sig: EddsaSignature; - // Timestamp of the close request. - request_timestamp: Timestamp; } - .. ts:def:: ReserveCreditTransaction +.. _exchange-withdrawal: - interface ReserveCreditTransaction { - type: "CREDIT"; +---------- +Withdrawal +---------- - // Amount deposited. - amount: Amount; +This API is used by the wallet to obtain digital coins. - // Sender account ``payto://`` URL. - sender_account_url: string; +When transferring money to the exchange such as via SEPA transfers, the exchange creates +a *reserve*, which keeps the money from the customer. The customer must +specify an EdDSA reserve public key as part of the transfer, and can then +withdraw digital coins using the corresponding private key. All incoming and +outgoing transactions are recorded under the corresponding public key by the +exchange. - // Opaque identifier internal to the exchange that - // uniquely identifies the wire transfer that credited the reserve. - wire_reference: Integer; +.. note:: - // Timestamp of the incoming wire transfer. - timestamp: Timestamp; - } + Eventually the exchange will need to advertise a policy for how long it will + keep transaction histories for inactive or even fully drained reserves. We + will therefore need some additional handler similar to ``/keys`` to + advertise those terms of service. -.. http:post:: /reserves/$RESERVE_PUB/history +.. http:get:: /reserves/$RESERVE_PUB - Request information about the full history of - a reserve or an account. + Request summary information about a reserve. **Request:** - The request body must be a `ReserveHistoryRequest` object. + :query timeout_ms=MILLISECONDS: *Optional.* If specified, the exchange will wait up to MILLISECONDS for incoming funds before returning a 404 if the reserve does not yet exist. **Response:** :http:statuscode:`200 OK`: - The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. - :http:statuscode:`403 Forbidden`: - The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid. - This response comes with a standard `ErrorDetail` response. Alternatively, the provided timestamp is not close to the current time. + The exchange responds with a `ReserveSummary` object; the reserve was known to the exchange. :http:statuscode:`404 Not found`: The reserve key does not belong to a reserve known to the exchange. - :http:statuscode:`412 Precondition failed`: - The balance in the reserve is insufficient to pay for the history request. - This response comes with a standard `ErrorDetail` response. **Details:** - .. ts:def:: ReserveHistoryRequest + .. ts:def:: ReserveSummary - interface ReserveHistoryRequest { - // Signature of type - // ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` - // over a `TALER_ReserveHistoryRequestSignaturePS`. - reserve_sig: EddsaSignature; + interface ReserveSummary { + // Balance left in the reserve. + balance: Amount; - // Time when the client made the request. - // Timestamp must be reasonably close to the time of - // the exchange, otherwise the exchange may reject - // the request. - request_timestamp: Timestamp; + // If set, age restriction is required to be set for each coin to this + // value during the withdrawal from this reserve. The client then MUST + // use a denomination with support for age restriction enabled for the + // withdrawal. + // The value represents a valid age group from the list of permissible + // age groups as defined by the exchange's output to /keys. + maximum_age_group?: number; } +Withdraw +~~~~~~~~ + .. http:post:: /csr-withdraw Obtain exchange-side input values in preparation for a @@ -1648,7 +1962,7 @@ exchange. .. ts:def:: WithdrawPrepareResponse - type WithdrawPrepareResponse + type WithdrawPrepareResponse = | ExchangeWithdrawValue; .. ts:def:: ExchangeWithdrawValue @@ -1675,28 +1989,32 @@ exchange. r_pub_1: CsRPublic; } -.. http:post:: /reserves/$RESERVE_PUB/withdraw - Withdraw a coin of the specified denomination. Note that the client should - commit all of the request details, including the private key of the coin and - the blinding factor, to disk *before* issuing this request, so that it can +Batch Withdraw +~~~~~~~~~~~~~~ + +.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw + + Withdraw multiple coins from the same reserve. Note that the client should + commit all of the request details, including the private key of the coins and + the blinding factors, to disk *before* issuing this request, so that it can recover the information if necessary in case of transient failures, like power outage, network outage, etc. - **Request:** The request body must be a `WithdrawRequest` object. + **Request:** The request body must be a `BatchWithdrawRequest` object. **Response:** :http:statuscode:`200 OK`: - The request was successful, and the response is a `WithdrawResponse`. Note that repeating exactly the same request - will again yield the same response, so if the network goes down during the - transaction or before the client can commit the coin signature to disk, the - coin is not lost. + The request was successful, and the response is a `BatchWithdrawResponse`. + Note that repeating exactly the same request will again yield the same + response, so if the network goes down during the transaction or before the + client can commit the coin signature to disk, the coin is not lost. :http:statuscode:`403 Forbidden`: - The signature is invalid. + A signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: - The denomination key or the reserve are not known to the exchange. If the + A denomination key or the reserve are not known to the exchange. If the denomination key is unknown, this suggests a bug in the wallet as the wallet should have used current denomination keys from ``/keys``. In this case, the response will be a `DenominationUnknownMessage`. @@ -1706,14 +2024,19 @@ exchange. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coin. :http:statuscode:`409 Conflict`: - The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination. - The response is `WithdrawError` object. + One of the following reasons occured: + + 1. The balance of the reserve is not sufficient to withdraw the coins of the + indicated denominations. The response is `WithdrawError` object. + + 2. The reserve has a birthday set and requires a request to ``/age-withdraw`` instead. + The response comes with a standard `ErrorDetail` response with error-code ``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED`` and an additional field ``maximum_allowed_age`` for the maximum age (in years) that the client can commit to in the call to ``/age-withdraw`` :http:statuscode:`410 Gone`: - The requested denomination key is not yet or no longer valid. - It either before the validity start, past the expiration or was revoked. The response is a - `DenominationExpiredMessage`. Clients must evaluate - the error code provided to understand which of the - cases this is and handle it accordingly. + A requested denomination key is not yet or no longer valid. + It either before the validity start, past the expiration or was revoked. + The response is a `DenominationExpiredMessage`. Clients must evaluate the + error code provided to understand which of the cases this is and handle it + accordingly. :http:statuscode:`451 Unavailable for Legal Reasons`: This reserve has received funds from a purse or the amount withdrawn exceeds another legal threshold and thus the reserve must @@ -1723,7 +2046,7 @@ exchange. The user should be redirected to the provided location to perform the required KYC checks to open the account before withdrawing. Afterwards, the request should be repeated. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. Implementation note: internally, we need to distinguish between upgrading the reserve to an @@ -1736,41 +2059,18 @@ exchange. **Details:** - .. ts:def:: DenominationExpiredMessage - - interface DenominationExpiredMessage { - - // Taler error code. Note that beyond - // expiration this message format is also - // used if the key is not yet valid, or - // has been revoked. - code: number; - - // Signature by the exchange over a - // `TALER_DenominationExpiredAffirmationPS`. - // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``. - exchange_sig: EddsaSignature; - - // Public key of the exchange used to create - // the 'exchange_sig. - exchange_pub: EddsaPublicKey; - - // Hash of the denomination public key that is unknown. - h_denom_pub: HashCode; + .. ts:def:: BatchWithdrawRequest - // When was the signature created. - timestamp: Timestamp; + interface BatchWithdrawRequest { + // Array of requests for the individual coins to withdraw. + planchets: WithdrawRequest[]; - // What kind of operation was requested that now - // failed? - oper: string; } - .. ts:def:: WithdrawRequest interface WithdrawRequest { - // Hash of a denomination public key (RSA), specifying the type of coin the client + // Hash of a denomination public key, specifying the type of coin the client // would like the exchange to create. denom_pub_hash: HashCode; @@ -1785,6 +2085,16 @@ exchange. } + + .. ts:def:: BatchWithdrawResponse + + interface BatchWithdrawResponse { + // Array of blinded signatures, in the same order as was + // given in the request. + ev_sigs: WithdrawResponse[]; + + } + .. ts:def:: WithdrawResponse interface WithdrawResponse { @@ -1824,21 +2134,6 @@ exchange. } - .. ts:def:: KycNeededRedirect - - interface KycNeededRedirect { - - // Hash of the payto:// account URI that identifies - // the account which is being KYCed. - h_payto: PaytoHash; - - // Legitimization target that the merchant should - // use to check for its KYC status using - // the ``/kyc-check/$REQUIREMENT_ROW/...`` endpoint. - requirement_row: Integer; - - } - .. ts:def:: WithdrawError interface WithdrawError { @@ -1856,49 +2151,86 @@ exchange. history: TransactionHistoryItem[] } + .. ts:def:: DenominationExpiredMessage + interface DenominationExpiredMessage { + // Taler error code. Note that beyond + // expiration this message format is also + // used if the key is not yet valid, or + // has been revoked. + code: number; -.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw + // Signature by the exchange over a + // `TALER_DenominationExpiredAffirmationPS`. + // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``. + exchange_sig: EddsaSignature; - Withdraw multiple coins from the same reserve. Note that the client should - commit all of the request details, including the private key of the coins and - the blinding factors, to disk *before* issuing this request, so that it can - recover the information if necessary in case of transient failures, like - power outage, network outage, etc. + // Public key of the exchange used to create + // the 'exchange_sig. + exchange_pub: EddsaPublicKey; - **Request:** The request body must be a `BatchWithdrawRequest` object. + // Hash of the denomination public key that is unknown. + h_denom_pub: HashCode; + + // When was the signature created. + timestamp: Timestamp; + + // What kind of operation was requested that now + // failed? + oper: string; + } + + + + + +Withdraw with Age Restriction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the reserve was marked with a maximum age group, the client has to perform a +cut&choose protocol with the exchange. It first calls +``/reserves/$RESERVE_PUB/age-withdraw`` and commits to ``n*kappa`` coins. On +success, the exchange answers this request with an noreveal-index. The client +then has to call ``/age-withdraw/$ACH/reveal`` to reveal all ``n*(kappa - 1)`` +coins along with their age commitments to proof that they were appropriate. +If so, the exchange will blindly sign ``n`` undisclosed coins from the request. + + +.. http:post:: /reserves/$RESERVE_PUB/age-withdraw + + Withdraw multiple coins *with age restriction* from the same reserve. + Note that the client should commit all of the request details, including the + private key of the coins and the blinding factors, to disk *before* issuing + this request, so that it can recover the information if necessary in case of + transient failures, like power outage, network outage, etc. + + **Request:** The request body must be a `AgeWithdrawRequest` object. **Response:** :http:statuscode:`200 OK`: - The request was successful, and the response is a `BatchWithdrawResponse`. - Note that repeating exactly the same request - will again yield the same response, so if the network goes down during the - transaction or before the client can commit the coin signature to disk, the - coin is not lost. + The request was successful, and the response is a `AgeWithdrawResponse`. + Note that repeating exactly the same request will again yield the same + response, so if the network goes down during the transaction or before the + client can commit the coin signature to disk, the coin is not lost. :http:statuscode:`403 Forbidden`: A signature is invalid. This response comes with a standard `ErrorDetail` response. - :http:statuscode:`404 Not found`: - A denomination key or the reserve are not known to the exchange. If the - denomination key is unknown, this suggests a bug in the wallet as the - wallet should have used current denomination keys from ``/keys``. - In this case, the response will be a `DenominationUnknownMessage`. - If the reserve is unknown, the wallet should not report a hard error yet, but - instead simply wait for up to a day, as the wire transaction might simply - not yet have completed and might be known to the exchange in the near future. - In this case, the wallet should repeat the exact same request later again - using exactly the same blinded coin. :http:statuscode:`409 Conflict`: - The balance of the reserve is not sufficient to withdraw the coins of the indicated denominations. - The response is `WithdrawError` object. + One of two reasons occured: + + 1. The balance of the reserve is not sufficient to withdraw the coins of the + given amount. The response is a `WithdrawError` object. + + 2. The provided value for ``max_age`` is higher than the allowed value according to the reserve's birthday. + The response comes with a standard `ErrorDetail` response with error-code ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE`` and an additional field ``maximum_allowed_age`` for the maximum age (in years) that the client can commit to in a call to ``/age-withdraw`` :http:statuscode:`410 Gone`: A requested denomination key is not yet or no longer valid. - It either before the validity start, past the expiration or was revoked. The response is a - `DenominationExpiredMessage`. Clients must evaluate - the error code provided to understand which of the - cases this is and handle it accordingly. + It either before the validity start, past the expiration or was revoked. + The response is a `DenominationExpiredMessage`. Clients must evaluate the + error code provided to understand which of the cases this is and handle it + accordingly. :http:statuscode:`451 Unavailable for Legal Reasons`: This reserve has received funds from a purse or the amount withdrawn exceeds another legal threshold and thus the reserve must @@ -1908,434 +2240,553 @@ exchange. The user should be redirected to the provided location to perform the required KYC checks to open the account before withdrawing. Afterwards, the request should be repeated. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. + + .. ts:def:: AgeWithdrawRequest + + interface AgeWithdrawRequest { + // Array of ``n`` hash codes of denomination public keys to order. + // These denominations MUST support age restriction as defined in the + // output to /keys. + // The sum of all denomination's values and fees MUST be at most the + // balance of the reserve. The balance of the reserve will be + // immediatley reduced by that amount. + denoms_h: HashCode[]; + + // ``n`` arrays of ``kappa`` entries with blinded coin envelopes. Each + // (toplevel) entry represents ``kappa`` canditates for a particular + // coin. The exchange will respond with an index ``gamma``, which is + // the index that shall remain undisclosed during the reveal phase. + // The SHA512 hash $ACH over the blinded coin envelopes is the commitment + // that is later used as the key to the reveal-URL. + blinded_coins_evs: CoinEnvelope[][]; + + // The maximum age to commit to. MUST be the same as the maximum + // age in the reserve. + max_age: number; + + // Signature of `TALER_AgeWithdrawRequestPS` created with + // the `reserves's private key <reserve-priv>` + // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW``. + reserve_sig: EddsaSignature; + } - Implementation note: internally, we need to - distinguish between upgrading the reserve to an - account (due to P2P payment) and identifying the - owner of the origin bank account (due to exceeding - the withdraw amount threshold), as we need to create - a different payto://-URI for the KYC check depending - on the case. + .. ts:def:: AgeWithdrawResponse + interface AgeWithdrawResponse { + // index of the commitments that the client doesn't + // have to disclose + noreveal_index: Integer; - **Details:** + // Signature of `TALER_AgeWithdrawConfirmationPS` whereby + // the exchange confirms the ``noreveal_index``. + exchange_sig: EddsaSignature; - .. ts:def:: BatchWithdrawRequest + // `Public EdDSA key <sign-key-pub>` of the exchange that was used to + // generate the signature. Should match one of the exchange's signing + // keys from ``/keys``. Again given explicitly as the client might + // otherwise be confused by clock skew as to which signing key was used. + exchange_pub: EddsaPublicKey; + } - interface BatchWithdrawRequest { - // Array of requests for the individual coins to withdraw. - planchets: WithdrawRequest[]; + +.. http:post:: /age-withdraw/$ACH/reveal + + The client has previously committed to multiple coins with age restriction + in a call to ``/reserve/$RESERVE_PUB/age-withdraw`` and got a + `AgeWithdrawResponse` from the exchange. By calling this + endpoint, the client has to reveal each coin and their ``kappa - 1`` + age commitments, except for the age commitments with index + ``noreveal_index``. The hash of all commitments from the former withdraw + request is given as the ``$ACH`` value in the URL to this endpoint. + + + **Request:** The request body must be a `AgeWithdrawRevealRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `AgeWithdrawRevealResponse`. + Note that repeating exactly the same request will again yield the same + response, so if the network goes down during the transaction or before the + client can commit the coin signature to disk, the coin is not lost. + :http:statuscode:`404 Not found`: + The provided commitment $ACH is unknown. + :http:statuscode:`409 Conflict`: + The reveal operation failed and the response is an `WithdrawError` object. + The error codes indicate one of two cases: + + 1. An age commitment for at least one of the coins did not fulfill the + required maximum age requirement of the corresponding reserve. + Error code: + ``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``. + 2. The computation of the hash of the commitment with provided input does + result in the value $ACH. + Error code: + ``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH`` + + + .. ts:def:: AgeWithdrawRevealRequest + + interface AgeWithdrawRevealRequest { + // Array of ``n`` of ``(kappa - 1)`` disclosed coin master secrets, from + // which the coins' private key, blinding, nonce (for Clause-Schnorr) and + // age-restriction is calculated. + // + // Given each coin's private key and age commitment, the exchange will + // calculate each coin's blinded hash value und use all those (disclosed) + // blinded hashes together with the non-disclosed envelopes ``coin_evs`` + // during the verification of the original age-withdraw-commitment. + disclosed_coin_secrets: AgeRestrictedCoinSecret[][]; } - .. ts:def:: BatchWithdrawResponse + .. ts:def:: AgeRestrictedCoinSecret - interface BatchWithdrawResponse { - // Array of blinded signatures, in the same order as was - // given in the request. - ev_sigs: WithdrawResponse[]; + // The Master key material from which the coins' private key ``coin_priv``, + // blinding ``beta`` and nonce ``nonce`` (for Clause-Schnorr) itself are + // derived as usually in wallet-core. Given a coin's master key material, + // the age commitment for the coin MUST be derived from this private key as + // follows: + // + // Let m ∈ {1,...,M} be the maximum age group as defined in the reserve + // that the wallet can commit to. + // + // For age group $AG ∈ {1,...m}, set + // seed = HDKF(coin_secret, "age-commitment", $AG) + // p[$AG] = Edx25519_generate_private(seed) + // and calculate the corresponding Edx25519PublicKey as + // q[$AG] = Edx25519_public_from_private(p[$AG]) + // + // For age groups $AG ∈ {m,...,M}, set + // f[$AG] = HDKF(coin_secret, "age-factor", $AG) + // and calculate the corresponding Edx25519PublicKey as + // q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG]) + // + type AgeRestrictedCoinSecret = string; + .. ts:def:: PublishedAgeRestrictionBaseKey + + // The value for ``PublishedAgeRestrictionBaseKey`` is a randomly chosen + // `Edx25519PublicKey` for which the private key is not known to the clients. It is + // used during the age-withdraw protocol so that clients can proof that they + // derived all public keys to age groups higher than their allowed maximum + // from this particular value. + const PublishedAgeRestrictionBaseKey = + new Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG"); + + .. ts:def:: AgeWithdrawRevealResponse + + interface AgeWithdrawRevealResponse { + // List of the exchange's blinded RSA signatures on the new coins. + ev_sigs : BlindedDenominationSignature[]; } -.. _delete-reserve: +.. _reserve-history: -.. http:DELETE:: /reserves/$RESERVE_PUB +--------------- +Reserve History +--------------- - Forcefully closes a reserve. - The request header must contain an *Account-Request-Signature*. - Note: this endpoint is not currently implemented! +.. http:get:: /reserves/$RESERVE_PUB/history + + Request information about the full history of + a reserve or an account. **Request:** - *Account-Request-Signature*: The client must provide Base-32 encoded EdDSA signature made with ``$ACCOUNT_PRIV``, affirming its authorization to delete the account. The purpose used MUST be ``TALER_SIGNATURE_RESERVE_CLOSE``. + The GET request should come with the following HTTP headers: - :query force=BOOLEAN: *Optional.* If set to 'true' specified, the exchange - will delete the account even if there is a balance remaining. + *If-None-Match*: The client MAY provide an ``If-None-Match`` header with an + Etag. In that case, the server MUST additionally respond with an ``304`` + status code in case the reserve history matches the provided Etag. + + *Taler-Reserve-History-Signature*: The client MUST provide Base-32 encoded + EdDSA signature over a TALER_SIGNATURE_RESERVE_HISTORY_REQUEST made with + the respective ``$RESERVE_PRIV``, affirming desire to download the current + reserve transaction history. + + :query start=OFFSET: *Optional.* Only return reserve history entries with + offsets above the given OFFSET. Allows clients to not + retrieve history entries they already have. **Response:** :http:statuscode:`200 OK`: - The operation succeeded, the exchange provides details - about the account deletion. - The response will include a `ReserveClosedResponse` object. + The exchange responds with a `ReserveHistory` object; the reserve was known to the exchange. + :http:statuscode:`204 No content`: + The reserve history is known, but at this point from the given starting point it is empty. Can only happen if OFFSET was positive. + :http:statuscode:`304 Not modified`: + The reserve history matches the one identified by the "If-none-match" HTTP header of the request. :http:statuscode:`403 Forbidden`: - The *Account-Request-Signature* is invalid. + The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: - The account is unknown to the exchange. - :http:statuscode:`409 Conflict`: - The account is still has digital cash in it, the associated - wire method is ``void`` and the *force* option was not provided. - This response comes with a standard `ErrorDetail` response. + The reserve key does not belong to a reserve known to the exchange. **Details:** - .. ts:def:: ReserveClosedResponse + .. ts:def:: ReserveHistory - interface ReserveClosedResponse { + interface ReserveHistory { + // Balance left in the reserve. + balance: Amount; - // Final balance of the account. - closing_amount: Amount; + // If set, gives the maximum age group that the client is required to set + // during withdrawal. + maximum_age_group: number; - // Current time of the exchange, used as part of - // what the exchange signs over. - close_time: Timestamp; + // Transaction history for this reserve. + // May be partial (!). + history: TransactionHistoryItem[]; + } - // Hash of the wire account into which the remaining - // balance will be transferred. Note: may be the - // hash over ``payto://void/`, in which case the - // balance is forfeit to the profit of the exchange. + Objects in the transaction history have the following format: + + .. ts:def:: TransactionHistoryItem + + // Union discriminated by the "type" field. + type TransactionHistoryItem = + | AccountSetupTransaction + | ReserveWithdrawTransaction + | ReserveAgeWithdrawTransaction + | ReserveCreditTransaction + | ReserveClosingTransaction + | ReserveOpenRequestTransaction + | ReserveCloseRequestTransaction + | PurseMergeTransaction; + + .. ts:def:: AccountSetupTransaction + + interface AccountSetupTransaction { + type: "SETUP"; + + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + + // KYC fee agreed to by the reserve owner. + kyc_fee: Amount; + + // Time when the KYC was triggered. + kyc_timestamp: Timestamp; + + // Hash of the wire details of the account. + // Note that this hash is unsalted and potentially + // private (as it could be inverted), hence access + // to this endpoint must be authorized using the + // private key of the reserve. h_wire: HashCode; - // This is a signature over a - // struct ``TALER_AccountDeleteConfirmationPS`` with purpose - // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. - exchange_sig: EddsaSignature; + // Signature created with the reserve's private key. + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST`` over + // a ``TALER_AccountSetupRequestSignaturePS``. + reserve_sig: EddsaSignature; } + .. ts:def:: ReserveWithdrawTransaction + interface ReserveWithdrawTransaction { + type: "WITHDRAW"; -.. _deposit-par: + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; -------- -Deposit -------- + // Amount withdrawn. + amount: Amount; -Deposit operations are requested f.e. by a merchant during a transaction or a -bidder during an auction. + // Hash of the denomination public key of the coin. + h_denom_pub: HashCode; -For the deposit operation during purchase, the merchant has to obtain the -deposit permission for a coin from their customer who owns the coin. When -depositing a coin, the merchant is credited an amount specified in the deposit -permission, possibly a fraction of the total coin's value, minus the deposit -fee as specified by the coin's denomination. + // Hash of the blinded coin to be signed. + h_coin_envelope: HashCode; -For auctions, a bidder performs an deposit operation and provides all relevant -information for the auction policy (such as timeout and public key as bidder) -and can use the ``exchange_sig`` field from the `DepositSuccess` message as a -proof to the seller for the escrow of sufficient fund. + // Signature over a `TALER_WithdrawRequestPS` + // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW`` + // created with the reserve's private key. + reserve_sig: EddsaSignature; + // Fee that is charged for withdraw. + withdraw_fee: Amount; + } -.. _deposit: + .. ts:def:: ReserveAgeWithdrawTransaction -.. http:POST:: /coins/$COIN_PUB/deposit + interface ReserveAgeWithdrawTransaction { + type: "AGEWITHDRAW"; - Deposit the given coin and ask the exchange to transfer the given :ref:`amount` - to the merchant's bank account. This API is used by the merchant to redeem - the digital coins. + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - The base URL for ``/coins/``-requests may differ from the main base URL of the - exchange. The exchange MUST return a 307 or 308 redirection to the correct - base URL if this is the case. + // Total Amount withdrawn. + amount: Amount; - **Request:** + // Commitment of all ``n*kappa`` blinded coins. + h_commitment: HashCode; - The request body must be a `DepositRequest` object. + // Signature over a `TALER_AgeWithdrawRequestPS` + // with purpose ``TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW`` + // created with the reserve's private key. + reserve_sig: EddsaSignature; - **Response:** + // Fee that is charged for withdraw. + withdraw_fee: Amount; + } - :http:statuscode:`200 OK`: - The operation succeeded, the exchange confirms that no double-spending took - place. The response will include a `DepositSuccess` object. - :http:statuscode:`403 Forbidden`: - One of the signatures is invalid. - This response comes with a standard `ErrorDetail` response. - :http:statuscode:`404 Not found`: - Either the denomination key is not recognized (expired or invalid), - or the wire type is not recognized. - If the denomination key is unknown, the response will be - a `DenominationUnknownMessage`. - :http:statuscode:`409 Conflict`: - The deposit operation has either failed because the coin has insufficient - residual value, or because the same public key of the coin has been - previously used with a different denomination. Which case it is - can be decided by looking at the error code - (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). - The fields of the response are the same in both cases. - The request should not be repeated again with this coin. - In this case, the response is a `DepositDoubleSpendError`. - :http:statuscode:`410 Gone`: - The requested denomination key is not yet or no longer valid. - It either before the validity start, past the expiration or was revoked. The response is a - `DenominationExpiredMessage`. Clients must evaluate - the error code provided to understand which of the - cases this is and handle it accordingly. - **Details:** + .. ts:def:: ReserveCreditTransaction - .. ts:def:: DepositRequest + interface ReserveCreditTransaction { + type: "CREDIT"; - interface DepositRequest { - // Amount to be deposited, can be a fraction of the - // coin's total value. - contribution: Amount; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // The merchant's account details. - // In case of an auction policy, it refers to the seller. - merchant_payto_uri: string; + // Amount deposited. + amount: Amount; - // The salt is used to hide the ``payto_uri`` from customers - // when computing the ``h_wire`` of the merchant. - wire_salt: WireSalt; + // Sender account ``payto://`` URL. + sender_account_url: string; - // SHA-512 hash of the contract of the merchant with the customer. Further - // details are never disclosed to the exchange. - h_contract_terms: HashCode; + // Opaque identifier internal to the exchange that + // uniquely identifies the wire transfer that credited the reserve. + wire_reference: Integer; - // Hash of denomination RSA key with which the coin is signed. - denom_pub_hash: HashCode; + // Timestamp of the incoming wire transfer. + timestamp: Timestamp; + } - // Exchange's unblinded RSA signature of the coin. - ub_sig: DenominationSignature; - // Timestamp when the contract was finalized. - timestamp: Timestamp; + .. ts:def:: ReserveClosingTransaction - // Indicative time by which the exchange undertakes to transfer the funds to - // the merchant, in case of successful payment. A wire transfer deadline of 'never' - // is not allowed. - wire_transfer_deadline: Timestamp; + interface ReserveClosingTransaction { + type: "CLOSING"; - // EdDSA `public key of the merchant <merchant-pub>`, so that the client can identify the - // merchant for refund requests. - // - // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a - // policy via extension. - merchant_pub: EddsaPublicKey; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // Date until which the merchant can issue a refund to the customer via the - // exchange, to be omitted if refunds are not allowed. - // - // THIS FIELD WILL BE DEPRICATED, once the refund mechanism becomes a - // policy via extension. - refund_deadline?: Timestamp; + // Closing balance. + amount: Amount; - // CAVEAT: THIS IS WORK IN PROGRESS - // (Optional) policy for the deposit. - // This might be a refund, auction or escrow policy. - // - // Note that support for policies is an optional feature of the exchange. - // Optional features are so called "extensions" in Taler. The exchange - // provides the list of supported extensions, including policies, in the - // `ExtensionsManifestsResponse` response to the ``/keys`` endpoint. - policy?: DepositPolicy; + // Closing fee charged by the exchange. + closing_fee: Amount; - // Signature over `TALER_DepositRequestPS`, made by the customer with the - // `coin's private key <coin-priv>`. - coin_sig: EddsaSignature; + // Wire transfer subject. + wtid: Base32; + + // ``payto://`` URI of the wire account into which the funds were returned to. + receiver_account_details: string; + + // This is a signature over a + // struct `TALER_ReserveCloseConfirmationPS` with purpose + // ``TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED``. + exchange_sig: EddsaSignature; + + // Public key used to create 'exchange_sig'. + exchange_pub: EddsaPublicKey; + + // Time when the reserve was closed. + timestamp: Timestamp; } - .. ts:def:: DenominationSignature - type DenominationSignature = - | RsaDenominationSignature - | CSDenominationSignature; + .. ts:def:: ReserveOpenRequestTransaction - .. ts:def:: RsaDenominationSignature + interface ReserveOpenRequestTransaction { + type: "OPEN"; - interface RsaDenominationSignature { - cipher: "RSA"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // RSA signature - rsa_signature: RsaSignature; - } + // Open fee paid from the reserve. + open_fee: Amount; - .. ts:def:: CSDenominationSignature + // This is a signature over + // a struct `TALER_ReserveOpenPS` with purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN``. + reserve_sig: EddsaSignature; - interface CSDenominationSignature { - type: "CS"; + // Timestamp of the open request. + request_timestamp: Timestamp; - // R value component of the signature. - cs_signature_r: Cs25519Point; + // Requested expiration. + requested_expiration: Timestamp; - // s value component of the signature. - cs_signature_s: Cs25519Scalar: + // Requested number of free open purses. + requested_min_purses: Integer; } - .. ts:def:: DepositPolicy + .. ts:def:: ReserveCloseRequestTransaction - type DepositPolicy = - | PolicyMerchantRefund - | PolicyBrandtVickreyAuction - | PolicyEscrowedPayment; + interface ReserveCloseRequestTransaction { + type: "CLOSE"; - .. ts:def:: PolicyMerchantRefund + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyMerchantRefund { - type: "merchant_refund"; + // This is a signature over + // a struct `TALER_ReserveClosePS` with purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE``. + reserve_sig: EddsaSignature; - // EdDSA `public key of the merchant <merchant-pub>`, so that the client - // can identify the merchant for refund requests. - merchant_pub: EddsaPublicKey; + // Target account ``payto://``, optional. + h_payto?: PaytoHash; - // Date until which the merchant can issue a refund to the customer via - // the ``/extensions/policy_refund``-endpoint of the exchange. - deadline: Timestamp; + // Timestamp of the close request. + request_timestamp: Timestamp; } - .. ts:def:: PolicyBrandtVickreyAuction + .. ts:def:: ReserveCreditTransaction - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyBrandtVickreyAuction { - type: "brandt_vickrey_auction"; + interface ReserveCreditTransaction { + type: "CREDIT"; - // Public key of this bidder. - // - // The bidder uses this key to sign the auction information and - // the messages it sends to the seller during the auction. - bidder_pub: EddsaPublicKey; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // Hash of the auction terms - // - // The hash should be taken over a normalized JSON object of type - // `BrandtVickreyAuction`. - h_auction: HashCode; + // Amount deposited. + amount: Amount; - // The amount that this bidder commits to for this auction - // - // This amount can be larger than the contribution of a single coin. - // The bidder can increase funding of this auction policy by using - // sufficiently many coins during the deposit operation (single or batch) - // with the same policy. - commitment: Amount; + // Sender account ``payto://`` URL. + sender_account_url: string; - // Date until the auction must have been successfully executed and - // a valid transcript provided to the - // ``/extensions/policy_brandt_vickrey_auction``-endpoint of the - // exchange. - // - // [If the auction has not been executed by then] OR [has been executed - // before then, but this bidder did not win], the coin's value doesn't - // change and the owner can refresh the coin. - // - // If this bidder won the auction, the winning price/amount from the - // outcome will be substracted from the coin and transfered to the - // merchant's ``payout_uri`` from the deposit request (minus a potential - // auction fee). For any remaining value, the bidder can refresh the - // coin to retrieve change. - deadline: Timestamp; + // Opaque identifier internal to the exchange that + // uniquely identifies the wire transfer that credited the reserve. + wire_reference: Integer; + + // Timestamp of the incoming wire transfer. + timestamp: Timestamp; } - .. ts:def:: BrandtVickreyAuction + .. ts:def:: PurseMergeTransaction - // CAVEAT: THIS IS STILL WORK IN PROGRESS. - // This structure defines an auction of Brandt-Vickory kind. - // It is used for the `PolicyBrandtVickreyAuction`. - interface BrandtVickreyAuction { - // Start date of the auction - time_start: Timestamp; + interface PurseMergeTransaction { + type: "MERGE"; - // Maximum duration per round. There are four rounds in an auction of - // Brandt-Vickrey kind. - time_round: RelativeTime; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; - // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. - // - Type 0 refers to an auction with one highest-price winner, - // - Type 1 refers to an auction with one winner, paying the second - // highest price, - // - Type 2 refers to an auction with two winners, paying - // the third-highest price, - // - etc. - auction_type: number; + // SHA-512 hash of the contact of the purse. + h_contract_terms: HashCode; - // The vector of prices for the Brandt-Vickrey auction. The values MUST - // be in strictly increasing order. - prices: Amount[]; + // EdDSA public key used to approve merges of this purse. + merge_pub: EddsaPublicKey; - // The type of outcome of the auction. - // In case the auction is declared public, each bidder can calculate the - // winning price. This field is not relevant for the replay of a - // transcript, as the transcript must be provided by the seller who sees - // the winner(s) and winning price of the auction. - outcome_public: boolean; + // Minimum age required for all coins deposited into the purse. + min_age: Integer; - // The public key of the seller. - pubkey: EddsaPublicKey; + // Number that identifies who created the purse + // and how it was paid for. + flags: Integer; - // The seller's account details. - payto_uri: string; - } + // Purse public key. + purse_pub: EddsaPublicKey; + // EdDSA signature of the account/reserve affirming the merge + // over a `TALER_AccountMergeSignaturePS`. + // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` + reserve_sig: EddsaSignature; - .. ts:def:: PolicyEscrowedPayment + // Client-side timestamp of when the merge request was made. + merge_timestamp: Timestamp; - // CAVEAT: THIS IS STILL WORK IN PROGRESS - // This policy is optional and might not be supported by the exchange. - // If it does, the exchange MUST show support for this policy in the - // ``extensions`` field in the response to ``/keys``. - interface PolicyEscrowedPayment { - type: "escrowed_payment"; + // Indicative time by which the purse should expire + // if it has not been merged into an account. At this + // point, all of the deposits made should be + // auto-refunded. + purse_expiration: Timestamp; - // Public key of this trustor, the owner of the coins. - // - // To claim the deposit, the merchant must provide the valid signature - // of the ``h_contract_terms`` field from the deposit, signed by _this_ - // key, to the ``/extensions/policy_escrow``-endpoint of the exchange, - // after the date specified in ``not_before`` and before the date - // specified in ``not_after``. - trustor_pub: EddsaPublicKey; + // Purse fee the reserve owner paid for the purse creation. + purse_fee: Amount; - // Latest date by which the deposit must be claimed. If the deposit - // has not been claimed by that date, the deposited coins can be - // refreshed by the (still) owner. - deadline: Timestamp; + // Total amount merged into the reserve. + // (excludes fees). + amount: Amount; + + // True if the purse was actually merged. + // If false, only the purse_fee has an impact + // on the reserve balance! + merged: boolean; } - The deposit operation succeeds if the coin is valid for making a deposit and - has enough residual value that has not already been deposited or melted. +.. _coin-history: - .. ts:def:: DepositSuccess +------------ +Coin History +------------ - interface DepositSuccess { - // Optional base URL of the exchange for looking up wire transfers - // associated with this transaction. If not given, - // the base URL is the same as the one used for this request. - // Can be used if the base URL for ``/transactions/`` differs from that - // for ``/coins/``, i.e. for load balancing. Clients SHOULD - // respect the ``transaction_base_url`` if provided. Any HTTP server - // belonging to an exchange MUST generate a 307 or 308 redirection - // to the correct base URL should a client uses the wrong base - // URL, or if the base URL has changed since the deposit. - transaction_base_url?: string; +.. http:get:: /coins/$COIN_PUB/history - // Timestamp when the deposit was received by the exchange. - exchange_timestamp: Timestamp; + Obtain the transaction history of a coin. Used only in special cases, like + when the exchange claims a double-spending error and the wallet does not + believe it. Usually, the wallet knows the transaction history of each coin + and thus has no need to inquire. - // The EdDSA signature of `TALER_DepositConfirmationPS` using a current - // `signing key of the exchange <sign-key-priv>` affirming the successful - // deposit and that the exchange will transfer the funds after the refund - // deadline, or as soon as possible if the refund deadline is zero. - exchange_sig: EddsaSignature; + **Request:** - // `Public EdDSA key of the exchange <sign-key-pub>` that was used to - // generate the signature. - // Should match one of the exchange's signing keys from ``/keys``. It is given - // explicitly as the client might otherwise be confused by clock skew as to - // which signing key was used. - exchange_pub: EddsaPublicKey; - } + The GET request should come with the following HTTP headers: - .. ts:def:: DepositDoubleSpendError + *If-None-Match*: The client MAY provide an ``If-None-Match`` header with an + Etag. In that case, the server MUST additionally respond with an ``304`` + status code in case the coin history matches the provided Etag. - interface DepositDoubleSpendError { - // The string constant "insufficient funds". - hint: string; + *Taler-Coin-History-Signature*: The client MUST provide Base-32 encoded + EdDSA signature over a TALER_SIGNATURE_COIN_HISTORY_REQUEST made with + the respective ``$RESERVE_PRIV``, affirming desire to download the current + coin transaction history. - // Transaction history for the coin that is - // being double-spended. + :query start=OFFSET: *Optional.* Only return coin history entries with + offsets above the given OFFSET. Allows clients to not + retrieve history entries they already have. + + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange confirms that no double-spending took + place. The response will include a `CoinHistoryResponse` object. + :http:statuscode:`204 No content`: + The reserve history is known, but at this point from the given starting point it is empty. Can only happen if OFFSET was positive. + :http:statuscode:`304 Not modified`: + The coin history has not changed since the previous query (detected via Etag + in "If-none-match" header). + :http:statuscode:`403 Forbidden`: + The *TALER_SIGNATURE_COIN_HISTORY_REQUEST* is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The coin public key is not (yet) known to the exchange. + + .. ts:def:: CoinHistoryResponse + + interface CoinHistoryResponse { + // Current balance of the coin. + balance: Amount; + + // Hash of the coin's denomination. + h_denom_pub: HashCode; + + // Transaction history for the coin. history: CoinSpendHistoryItem[]; } @@ -2353,12 +2804,16 @@ proof to the seller for the escrow of sufficient fund. | CoinPurseRefundTransaction | CoinReserveOpenDepositTransaction; - .. ts:def:: CoinDepositTransaction interface CoinDepositTransaction { type: "DEPOSIT"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed (or restored in the // case of a refund) by this transaction. // The amount given includes @@ -2402,6 +2857,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinMeltTransaction { type: "MELT"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed by this transaction. // Note that for melt this means the amount given includes // the melt fee. The current coin value can thus be computed by @@ -2431,6 +2891,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinRefundTransaction { type: "REFUND"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value restored // by this transaction. // The amount given excludes the transaction fee. @@ -2461,6 +2926,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinRecoupTransaction { type: "RECOUP"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed // by this transaction. // The current coin value can thus be computed by @@ -2502,6 +2972,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinOldCoinRecoupTransaction { type: "OLD-COIN-RECOUP"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value restored // by this transaction. // The current coin value can thus be computed by @@ -2526,6 +3001,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinRecoupRefreshTransaction { type: "RECOUP-REFRESH"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed // by this transaction. // The current coin value can thus be computed by @@ -2568,6 +3048,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinPurseDepositTransaction { type: "PURSE-DEPOSIT"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed // by this transaction. // Note that this means the amount given includes @@ -2602,6 +3087,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinPurseRefundTransaction { type: "PURSE-REFUND"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value restored // by this transaction. // The amount given excludes the refund fee. @@ -2631,6 +3121,11 @@ proof to the seller for the escrow of sufficient fund. interface CoinReserveOpenDepositTransaction { type: "RESERVE-OPEN-DEPOSIT"; + // Offset of this entry in the reserve history. + // Useful to request incremental histories via + // the "start" query parameter. + history_offset: Integer; + // The total amount of the coin's value absorbed // by this transaction. // Note that this means the amount given includes @@ -2648,7 +3143,30 @@ proof to the seller for the escrow of sufficient fund. } -.. http:POST:: /batch-deposit +.. _deposit-par: + +------- +Deposit +------- + +Deposit operations are requested f.e. by a merchant during a transaction or a +bidder during an auction. + +For the deposit operation during purchase, the merchant has to obtain the +deposit permission for a coin from their customer who owns the coin. When +depositing a coin, the merchant is credited an amount specified in the deposit +permission, possibly a fraction of the total coin's value, minus the deposit +fee as specified by the coin's denomination. + +For auctions, a bidder performs an deposit operation and provides all relevant +information for the auction policy (such as timeout and public key as bidder) +and can use the ``exchange_sig`` field from the `DepositSuccess` message as a +proof to the seller for the escrow of sufficient fund. + + +.. _deposit: + +.. http:post:: /batch-deposit Deposit multiple coins and ask the exchange to transfer the given :ref:`amount` into the merchant's bank account. This API is used by the merchant to redeem @@ -2662,7 +3180,7 @@ proof to the seller for the escrow of sufficient fund. :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that no double-spending took - place. The response will include a `BatchDepositSuccess` object. + place. The response will include a `DepositSuccess` object. :http:statuscode:`403 Forbidden`: One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. @@ -2674,15 +3192,17 @@ proof to the seller for the escrow of sufficient fund. :http:statuscode:`409 Conflict`: The deposit operation has either failed because a coin has insufficient residual value, or because the same public key of a coin has been - previously used with a different denomination. Which case it is - can be decided by looking at the error code - (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or - ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). - The fields of the response are the same in both cases. - The request should not be repeated again with this coin. - In this case, the response is a `DepositDoubleSpendError` with - an additional ``coin_pub`` field specifying the public key of the - coin that was double-spent. + previously used with a different denomination. + Which case it is can be decided by looking at the error code: + + 1. ``TALER_EC_EXCHANGE_DEPOSIT_CONFLICTING_CONTRACT`` (same coin used in different ways), + 2. ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient), + 3. ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` (same coin public key, but different denomination). + 4. ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH`` (same coin public key, but different age commitment). + + The request should not be repeated again with this coin. Instead, the client + can get from the exchange via the ``/coin/$COIN_PUB/history`` endpoint the record + of the transactions known for this coin's public key. :http:statuscode:`410 Gone`: The requested denomination key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a @@ -2756,12 +3276,176 @@ proof to the seller for the escrow of sufficient fund. coin_sig: EddsaSignature; } + .. ts:def:: DenominationSignature + + type DenominationSignature = + | RsaDenominationSignature + | CSDenominationSignature; + + .. ts:def:: RsaDenominationSignature + + interface RsaDenominationSignature { + cipher: "RSA"; + + // RSA signature + rsa_signature: RsaSignature; + } + + .. ts:def:: CSDenominationSignature + + interface CSDenominationSignature { + type: "CS"; + + // R value component of the signature. + cs_signature_r: Cs25519Point; + + // s value component of the signature. + cs_signature_s: Cs25519Scalar: + + } + + .. ts:def:: DepositPolicy + + type DepositPolicy = + | PolicyMerchantRefund + | PolicyBrandtVickreyAuction + | PolicyEscrowedPayment; + + .. ts:def:: PolicyMerchantRefund + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyMerchantRefund { + type: "merchant_refund"; + + // EdDSA `public key of the merchant <merchant-pub>`, so that the client + // can identify the merchant for refund requests. + merchant_pub: EddsaPublicKey; + + // Date until which the merchant can issue a refund to the customer via + // the ``/extensions/policy_refund``-endpoint of the exchange. + deadline: Timestamp; + } + + .. ts:def:: PolicyBrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyBrandtVickreyAuction { + type: "brandt_vickrey_auction"; + + // Public key of this bidder. + // + // The bidder uses this key to sign the auction information and + // the messages it sends to the seller during the auction. + bidder_pub: EddsaPublicKey; + + // Hash of the auction terms + // + // The hash should be taken over a normalized JSON object of type + // `BrandtVickreyAuction`. + h_auction: HashCode; + + // The amount that this bidder commits to for this auction + // + // This amount can be larger than the contribution of a single coin. + // The bidder can increase funding of this auction policy by using + // sufficiently many coins during the deposit operation (single or batch) + // with the same policy. + commitment: Amount; + + // Date until the auction must have been successfully executed and + // a valid transcript provided to the + // ``/extensions/policy_brandt_vickrey_auction``-endpoint of the + // exchange. + // + // [If the auction has not been executed by then] OR [has been executed + // before then, but this bidder did not win], the coin's value doesn't + // change and the owner can refresh the coin. + // + // If this bidder won the auction, the winning price/amount from the + // outcome will be substracted from the coin and transfered to the + // merchant's ``payout_uri`` from the deposit request (minus a potential + // auction fee). For any remaining value, the bidder can refresh the + // coin to retrieve change. + deadline: Timestamp; + } + + .. ts:def:: BrandtVickreyAuction + + // CAVEAT: THIS IS STILL WORK IN PROGRESS. + // This structure defines an auction of Brandt-Vickory kind. + // It is used for the `PolicyBrandtVickreyAuction`. + interface BrandtVickreyAuction { + // Start date of the auction + time_start: Timestamp; + + // Maximum duration per round. There are four rounds in an auction of + // Brandt-Vickrey kind. + time_round: RelativeTime; + + // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. + // - Type 0 refers to an auction with one highest-price winner, + // - Type 1 refers to an auction with one winner, paying the second + // highest price, + // - Type 2 refers to an auction with two winners, paying + // the third-highest price, + // - etc. + auction_type: number; + + // The vector of prices for the Brandt-Vickrey auction. The values MUST + // be in strictly increasing order. + prices: Amount[]; + + // The type of outcome of the auction. + // In case the auction is declared public, each bidder can calculate the + // winning price. This field is not relevant for the replay of a + // transcript, as the transcript must be provided by the seller who sees + // the winner(s) and winning price of the auction. + outcome_public: boolean; + + // The public key of the seller. + pubkey: EddsaPublicKey; + + // The seller's account details. + payto_uri: string; + } + + + .. ts:def:: PolicyEscrowedPayment + + // CAVEAT: THIS IS STILL WORK IN PROGRESS + // This policy is optional and might not be supported by the exchange. + // If it does, the exchange MUST show support for this policy in the + // ``extensions`` field in the response to ``/keys``. + interface PolicyEscrowedPayment { + type: "escrowed_payment"; + + // Public key of this trustor, the owner of the coins. + // + // To claim the deposit, the merchant must provide the valid signature + // of the ``h_contract_terms`` field from the deposit, signed by _this_ + // key, to the ``/extensions/policy_escrow``-endpoint of the exchange, + // after the date specified in ``not_before`` and before the date + // specified in ``not_after``. + trustor_pub: EddsaPublicKey; + + // Latest date by which the deposit must be claimed. If the deposit + // has not been claimed by that date, the deposited coins can be + // refreshed by the (still) owner. + deadline: Timestamp; + } + The deposit operation succeeds if the coin is valid for making a deposit and has enough residual value that has not already been deposited or melted. - .. ts:def:: BatchDepositSuccess + .. ts:def:: DepositSuccess - interface BatchDepositSuccess { + interface DepositSuccess { // Optional base URL of the exchange for looking up wire transfers // associated with this transaction. If not given, // the base URL is the same as the one used for this request. @@ -2783,15 +3467,7 @@ proof to the seller for the escrow of sufficient fund. // which signing key was used. exchange_pub: EddsaPublicKey; - // Array of deposit confirmation signatures from the exchange - // Entries must be in the same order the coins were given - // in the batch deposit request. - exchange_sigs: DepositConfirmationSignature[]; - } - - .. ts:def:: DepositConfirmationSignature - - interface DepositConfirmationSignature { + // Deposit confirmation signature from the exchange. // The EdDSA signature of `TALER_DepositConfirmationPS` using a current // `signing key of the exchange <sign-key-priv>` affirming the successful // deposit and that the exchange will transfer the funds after the refund @@ -2799,6 +3475,27 @@ proof to the seller for the escrow of sufficient fund. exchange_sig: EddsaSignature; } + .. ts:def:: DepositDoubleSpendError + + interface DepositDoubleSpendError { + + // Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS + code: Integer; + + // A string explaining that the user tried to + // double-spend. + hint: string; + + // EdDSA public key of a coin being double-spent. + coin_pub: EddsaPublicKey; + + // Transaction history for the coin that is + // being double-spended. + // DEPRECATED! Will be removed soon. Use + // GET /coins/$COIN_PUB to get the history! + history: CoinSpendHistoryItem[]; + } + ---------- Refreshing @@ -2942,7 +3639,7 @@ the API during normal operation. // Melt commitment. Hash over the various coins to be withdrawn. // See also ``TALER_refresh_get_commitment()``. - rc: TALER_RefreshCommitmentP; + rc: HashCode; // Master seed for the Clause-schnorr R-value // creation. Must match the /csr-melt request. @@ -2951,6 +3648,10 @@ the API during normal operation. // denominations is of type Clause-Schnorr. rms?: RefreshMasterSeed; + // IFF the denomination has age restriction support, the client MUST + // provide the SHA256 hash of the age commitment of the coin. + // MUST be omitted otherwise. + age_commitment_hash?: AgeCommitmentHash; } For details about the HKDF used to derive the new coin private keys and @@ -3073,15 +3774,19 @@ the API during normal operation. // Signs over a `TALER_CoinLinkSignaturePS`. link_sigs: EddsaSignature[]; + // IFF the corresponding denomination has support for age restriction, + // the client MUST provide the original age commitment, i. e. the + // vector of public keys. + // The size of the vector MUST be the number of age groups as defined by the + // Exchange in the field ``.age_groups`` of the extension ``age_restriction``. + old_age_commitment?: Edx25519PublicKey[]; + } .. ts:def:: RevealResponse - interface RevealResponse { - // List of the exchange's blinded RSA signatures on the new coins. - ev_sigs : Array<{ ev_sig: BlindedDenominationSignature }>; - } + type RevealResponse = BatchWithdrawResponse; .. ts:def:: RevealConflictResponse @@ -3427,12 +4132,21 @@ typically also view the balance.) // Coin's public key, both ECDHE and EdDSA. coin_pub: CoinPublicKey; - // The total amount the original deposit was worth. + // The total amount the original deposit was worth, + // including fees and after applicable refunds. deposit_value: Amount; - // Applicable fees for the deposit. + // Applicable fees for the deposit, possibly + // reduced or waived due to refunds. deposit_fee: Amount; + // Refunds that were applied to the value of + // this coin. Optional. + // Since protocol **v19**. Before, refunds were + // incorrectly still included in the + // ``deposit_value`` (!). + refund_total?: Amount; + } .. http:get:: /deposits/$H_WIRE/$MERCHANT_PUB/$H_CONTRACT_TERMS/$COIN_PUB @@ -3444,7 +4158,13 @@ typically also view the balance.) **Request:** - :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a ``TALER_DepositTrackPS``, affirming that it is really the merchant who requires obtaining the wire transfer identifier. + :query merchant_sig: EdDSA signature of the merchant made with purpose + ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION`` over a + ``TALER_DepositTrackPS``, affirming that it is really the merchant who + requires obtaining the wire transfer identifier. + :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait + up to ``NUMBER`` milliseconds for completion of a deposit operation before + sending the HTTP response. **Response:** @@ -3477,9 +4197,6 @@ typically also view the balance.) // The contribution of this coin to the total (without fees) coin_contribution: Amount; - // Total amount transferred. - total_amount: Amount; - // Binary-only Signature_ with purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE`` // over a `TALER_ConfirmWirePS` // whereby the exchange affirms the successful wire transfer. @@ -3504,6 +4221,12 @@ typically also view the balance.) // need has been evaluated. requirement_row?: Integer; + // Current AML state for the target account. Non-zero + // values indicate that the transfer is blocked due to + // AML enforcement. + // Removed in protocol **v20**. + aml_decision: Integer; + // True if the KYC check for the merchant has been // satisfied. False does not mean that KYC // is strictly needed, unless also a @@ -3522,7 +4245,7 @@ typically also view the balance.) Refunds ------- -.. http:POST:: /coins/$COIN_PUB/refund +.. http:post:: /coins/$COIN_PUB/refund Undo deposit of the given coin, restoring its value. @@ -3621,8 +4344,8 @@ Refunds Wallet-to-wallet transfers -------------------------- -.. http:GET:: /purses/$PURSE_PUB/merge -.. http:GET:: /purses/$PURSE_PUB/deposit +.. http:get:: /purses/$PURSE_PUB/merge +.. http:get:: /purses/$PURSE_PUB/deposit Obtain information about a purse. Depending on the suffix, the long-polling (if any) will wait for either a merge or @@ -3663,6 +4386,9 @@ Wallet-to-wallet transfers // purse will (have been) merged with the account. balance: Amount; + // When does the purge expire. + purse_expiration: Timestamp; + // Time of the merge, missing if "never". merge_timestamp?: Timestamp; @@ -3674,6 +4400,13 @@ Wallet-to-wallet transfers // property is that it is either "never" or in the past. deposit_timestamp?: Timestamp; + // Time when the purse expires and + // funds that were not merged are refunded + // on the deposited coins. + // FIXME: Document the exchange protocol version + // in which this field became available. + purse_expiration: Timestamp; + // EdDSA signature of the exchange over a // `TALER_PurseStatusResponseSignaturePS` // with purpose ``TALER_SIGNATURE_PURSE_STATUS_RESPONSE`` @@ -3687,7 +4420,7 @@ Wallet-to-wallet transfers -.. http:POST:: /purses/$PURSE_PUB/create +.. http:post:: /purses/$PURSE_PUB/create Create a purse by depositing money into it. First step of a PUSH payment. @@ -3925,7 +4658,35 @@ Wallet-to-wallet transfers } -.. http:POST:: /purses/$PURSE_PUB/merge + +.. http:delete:: /purses/$PURSE_PUB + + Delete a purse that is unmerged and not yet expired. Refunds any money that + is already in the purse. + + **Request:** + + The request body must be empty, as recommended for HTTP delete in general. + To authorize the request, the header must contain a + ``Taler-Purse-Signature: $PURSE_SIG`` where ``$PURSE_SIG`` is the Crockford base32-encoded + EdDSA signature of purpose TALER_SIGNATURE_WALLET_PURSE_DELETE. + + **Response:** + + :http:statuscode:`204 No Content`: + The operation succeeded, the exchange confirms that the purse + was deleted. + :http:statuscode:`403 Forbidden`: + The signature is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not Found`: + The purse is not known. Might have already been deleted previously. + :http:statuscode:`409 Conflict`: + It is too late to delete the purse, its fate (merge or expiration) + was already decided. + + +.. http:post:: /purses/$PURSE_PUB/merge Merge purse with account, adding the value of the purse into the account. Endpoint to be used by the receiver of a PUSH payment. @@ -3959,7 +4720,7 @@ Wallet-to-wallet transfers :http:statuscode:`451 Unavailable For Legal Reasons`: This account has not yet passed the KYC checks. The client must pass KYC checks before proceeding with the merge. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. **Details:** @@ -3976,7 +4737,7 @@ Wallet-to-wallet transfers // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE`` reserve_sig: EddsaSignature; - // EdDSA signature of the purse private key affirming the merge + // EdDSA signature of the merge private key affirming the merge // over a `TALER_PurseMergeSignaturePS`. // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``. merge_sig: EddsaSignature; @@ -4031,7 +4792,7 @@ Wallet-to-wallet transfers -.. http:POST:: /reserves/$RESERVE_PUB/purse +.. http:post:: /reserves/$RESERVE_PUB/purse Create purse for an account. First step of a PULL payment. @@ -4070,7 +4831,7 @@ Wallet-to-wallet transfers :http:statuscode:`451 Unavailable For Legal Reasons`: This account has not yet passed the KYC checks. The client must pass KYC checks before proceeding with the merge. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. **Details:** @@ -4133,7 +4894,7 @@ Wallet-to-wallet transfers } -.. http:POST:: /purses/$PURSE_PUB/deposit +.. http:post:: /purses/$PURSE_PUB/deposit Deposit money into a purse. Used by the buyer for a PULL payment. @@ -4256,8 +5017,9 @@ Wallet-to-wallet transfers .. _exchange_wads: +---- Wads -^^^^ +---- .. note:: @@ -4268,7 +5030,7 @@ These endpoints are used to manage exchange-to-exchange payments in support of wallet-to-wallet payments. Only another exchange should access this endpoint. -.. http:GET:: /wads/$WAD_ID +.. http:get:: /wads/$WAD_ID Obtain information about a wad. @@ -4356,9 +5118,29 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. KYC status updates ------------------ -.. http:POST:: /kyc-wallet +This section describes endpoints used to set up, complete and +inquire about KYC operations performed by an exchange for +regulatory compliance. + +.. http:post:: /kyc-wallet + + The ``/wallet-kyc`` 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:** @@ -4376,7 +5158,7 @@ KYC status updates This response comes with a standard `ErrorDetail` response. :http:statuscode:`451 Unavailable for Legal Reasons`: The wallet must undergo a KYC check. A KYC ID was created. - The response will be a `WalletKycUuid` object. + The response will be a `LegitimizationNeededResponse` object (changed in protocol **v20**). **Details:** @@ -4399,62 +5181,74 @@ KYC status updates reserve_pub: EddsaPublicKey; } - .. ts:def:: WalletKycUuid +.. http:get:: /kyc-check/$REQUIREMENT_ROW - interface WalletKycUuid { + Checks the KYC status of a particular payment target and possibly begins a + KYC process by allowing the customer to choose the next KYC measure to + satisfy. This endpoint is typically used by wallets or merchants that + have been told that a transaction is not happening because it triggered + some KYC/AML measure and now want to check how the KYC/AML + requirement could be fulfilled (or whether it already has been + statisfied and the operation can now proceed). Long-polling may be used + to instantly observe a change in the KYC requirement status. - // UUID that the wallet should use when initiating - // the KYC check. - requirement_row: number; + The requirement row of the ``/kyc-check/`` endpoint encodes the + legitimization measure's serial number. It is returned in + `LegitimizationNeededResponse` responses via the ``requirement_row`` field. - // Hash of the payto:// account URI for the wallet. - h_payto: PaytoHash; + Given a valid pair of requirement row and account owner signature, the + ``/kyc-check/`` endpoint returns either just the KYC status or redirects the + client (202) to the next required stage of the KYC process. The redirection + must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. It + must always be the same endpoint for the same client, as the wallet/merchant + backend are not required to check for changes to this endpoint. Clients + that received a 202 status code may repeat the request and use long-polling + to detect a change of the HTTP status. - } + This endpoint exists in this specific form only since protocol **v20**. + **Request:** -.. http:GET:: /kyc-check/$REQUIREMENT_ROW/$H_PAYTO/$USERTYPE + *Account-Owner-Signature*: - Check or update KYC status of a particular payment target. - Returns the current KYC status of the account and, if - negative, returns the URL where the KYC process can be - initiated. The ``$REQUIREMENT_ROW`` must have been - returned previously from an exchange API endpoint that - determined that KYC was needed. The ``$H_PATYO`` must be - the hash of the payto:// URI of the payment target. - The ``$USERTYPE`` states whether the entity to perform - the KYC is an "individual" or "business". - - **Request:** + The client must provide Base-32 encoded EdDSA signature with + ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data. Note that + this is merely a simple authentication mechanism, the details of the + request are not protected by the signature. The ``$ACCOUNT_PRIV`` is + either the (wallet long-term) reserve private key or the merchant instance + private key. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will - wait up to ``timeout_ms`` milliseconds if the payment target - is currently not legitimized. Ignored if the payment target - is already legitimized. Note that the legitimization would be - triggered by another request to the same endpoint with a valid - ``token``. + wait up to ``timeout_ms`` milliseconds if the requirement continues + to be mandatory provisioning of KYC data by the client. + Ignored if the HTTP status code is already ``200 Ok``. Note that + clients cannot long-poll for AML staff actions, so status information + about an account being under AML review needs to be requested + periodically. **Response:** :http:statuscode:`200 Ok`: - The KYC operation succeeded, the exchange confirms that the - payment target already authorized to transact. - The response will be an `AccountKycStatus` object. + No mandatory KYC actions are required by the client at this time. + The client *may* still visit the KYC URL to initiate voluntary checks. + The response will be an `AccountKycStatus` object which specifies + restrictions that currently apply to the account. If the + client attempts to exceed *soft* limits, the status may change + to a ``202 Accepted``. Hard limits cannot be lifted by passing KYC checks. :http:statuscode:`202 Accepted`: - The user should be redirected to the provided location to perform - the required KYC checks to open the account. Afterwards, the - ``/kyc/`` request should be repeated. - The response will be an `AccountKycRedirect` object. + The account holder performed an operation that would have crossed + *soft* limits and must be redirected to the provided location to perform + the required KYC checks to satisfy the legal requirements. Afterwards, the + ``/kyc-check/`` request should be repeated to check whether the + user has completed the process. + The response will be an `AccountKycStatus` object. :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus - generally all accounts are simply considered legitimate. - :http:statuscode:`402 Payment Required`: - The client must pay the KYC fee for the KYC process. - **This is currently not implemented, see #7365.** + the legal requirements are already satisfied. :http:statuscode:`403 Forbidden`: - The provided hash does not match the payment target. + The provided signature is not acceptable for the requirement row. :http:statuscode:`404 Not found`: - The payment target is unknown. + The requirement row is unknown. **Details:** @@ -4462,68 +5256,303 @@ KYC status updates interface AccountKycStatus { - // Details about the KYC check that the user - // passed. - kyc_details: KycDetails; + // Current AML state for the target account. True if + // operations are not happening due to staff processing + // paperwork *or* due to legal requirements (so the + // client cannot do anything but wait). + // + // Note that not every AML staff action may be legally + // exposed to the client, so this is merely a hint that + // a client should be told that AML staff is currently + // reviewing the account. AML staff *may* review + // accounts without this flag being set! + aml_review: boolean; + + // Access token needed to construct the ``/kyc-spa/`` + // URL that the user should open in a browser to + // proceed with the KYC process (optional if the status + // type is ``200 Ok``, mandatory if the HTTP status + // is ``202 Accepted``). + access_token: AccountAccessToken; + + // Array with limitations that currently apply to this + // account and that may be increased or lifted if the + // KYC check is passed. + // Note that additional limits *may* exist and not be + // communicated to the client. If such limits are + // reached, this *may* be indicated by the account + // going into ``aml_review`` state. However, it is + // also possible that the exchange may legally have + // to deny operations without being allowed to provide + // any justification. + // The limits should be used by the client to + // possibly structure their operations (e.g. withdraw + // what is possible below the limit, ask the user to + // pass KYC checks or withdraw the rest after the time + // limit is passed, warn the user to not withdraw too + // much or even prevent the user from generating a + // request that would cause it to exceed hard limits). + limits?: AccountLimit[]; + + } + + .. ts:def:: AccountLimit + + interface AccountLimit { + + // Operation that is limited. + // Must be one of "WITHDRAW", "DEPOSIT", "P2P-RECEIVE" + // or "WALLET-BALANCE". + operation_type: string; + + // Timeframe during which the limit applies. + timeframe: RelativeTime; + + // Maximum amount allowed during the given timeframe. + // Zero if the operation is simply forbidden. + threshold: Amount; + + // True if this is a soft limit that could be raised + // by passing KYC checks. Clients *may* deliberately + // try to cross limits and trigger measures resulting + // in 451 responses to begin KYC processes. + // Clients that are aware of hard limits *should* + // inform users about the hard limit and prevent flows + // in the UI that would cause violations of hard limits. + soft_limit: boolean; + } + +.. http:get:: /kyc-spa/$ACCESS_TOKEN +.. http:get:: /kyc-spa/$FILENAME + + A set of ``/kyc-spa/$ACCESS_TOKEN`` GET endpoints is created per account + hash that serves the KYC SPA. This is where the ``/kyc-check/`` endpoint + will in principle redirect clients. The KYC SPA will use the + ``$ACCESS_TOKEN`` of its URL to initialize itself via the + ``/kyc-info/$ACCESS_TOKEN`` endpoint family. The KYC SPA may download + additional resources via ``/kyc-spa/$FILENAME``. The filenames must not + match base32-encoded 256-bit values. + + This endpoint was introduced in protocol **v20**. + + +.. http:get:: /kyc-info/$ACCESS_TOKEN + + The ``/kyc-info/$ACCESS_TOKEN`` endpoints are created per client + account hash (but access controlled via a unique target token) + to return information about the state of the KYC or AML process + to the KYC SPA. The SPA uses this information to show the user an + appropriate dialog. The SPA should also long-poll this endpoint for changes + to the AML/KYC state. Note that this is a client-facing endpoint, so it will + only provide a restricted amount of information to the customer (as some + laws may forbid us to inform particular customers about their true status). + The endpoint will typically inform the SPA about possible choices to + proceed, such as directly uploading files, contacting AML staff, or + proceeding with a particular KYC process at an external provider (such as + Challenger). If the user chooses to initate a KYC process at an external + provider, the SPA must request the respective process to be set-up by the + exchange via the ``/kyc-start/`` endpoint. + + This endpoint was introduced in protocol **v20**. - // Current time of the exchange, used as part of - // what the exchange signs over. - now: Timestamp; + **Request:** - // EdDSA signature of the exchange affirming the account - // is KYC'ed, must be of purpose - // ``TALER_SIGNATURE_EXCHANGE_ACCOUNT_SETUP_SUCCESS`` - // and over ``TALER_AccountSetupStatusSignaturePS``. - exchange_sig: EddsaSignature; + *If-None-Match*: + The client MAY provide an ``If-None-Match`` header with an ETag. - // public key used to create the signature. - exchange_pub: EddsaPublicKey; + :query timeout_ms=MILLISECONDS: + *Optional.* If specified, the exchange will wait up to MILLISECONDS for + a change to a more recent legitimization measure before returning a 304 + Not Modified status. + + **Response:** + + *Etag*: Will be set to the serial ID of the measure. Used for long-polling (only for 200 OK responses). + + :http:statuscode:`200 OK`: + The body is a `KycProcessClientInformation`. + :http:statuscode:`204 No Content`: + There are no open KYC requirements or possible voluntary checks + the client might perform. + :http:statuscode:`304 Not Modified`: + The KYC requirements did not change. + + + **Details:** + + .. ts:def:: KycProcessClientInformation + + interface KycProcessClientInformation { + + // List of requirements. + requirements?: { name : KycRequirementInformation}; + + // True if the client is expected to eventually satisfy all requirements. + // Default (if missing) is false. + is_and_combinator?: boolean + + // List of available voluntary checks the client could pay for. + // Since **vATTEST**. + voluntary_checks?: { name : KycCheckInformation}; } - .. ts:def:: AccountKycRedirect + .. ts:def:: KycRequirementInformation - interface AccountKycRedirect { + interface KycRequirementInformation { - // URL that the user should open in a browser to - // proceed with the KYC process. - kyc_url: string; + // Which form should be used? Common values include "INFO" + // (to just show the descriptions but allow no action), + // "LINK" (to enable the user to obtain a link via + // ``/kyc-start/``) or any build-in form name supported + // by the SPA. + form: string; + + // English description of the requirement. + description: string; + + // Map from IETF BCP 47 language tags to localized + // description texts. + description_i18n ?: { [lang_tag: string]: string }; + + // ID of the requirement, useful to construct the + // ``/kyc-upload/$ID`` or ``/kyc-start/$ID`` endpoint URLs. + // Present if and only if "form" is not "INFO". The + // ``$ID`` value may itself contain ``/`` or ``?`` and + // basically encode any URL path (and optional arguments). + id?: string; } - .. ts:def:: KycDetails + .. ts:def:: KycCheckInformation + + // Since **vATTEST**. + interface KycCheckInformation { - // Object that specifies which KYC checks are satisfied. - interface KycDetails { + // English description of the check. + description: string; - // Keys are the names of the check(s). - // The values are for now always empty objects. + // Map from IETF BCP 47 language tags to localized + // description texts. + description_i18n ?: { [lang_tag: string]: string }; + // FIXME: is the above in any way sufficient + // to begin the check? Do we not need at least + // something more??!? } -.. http:GET:: /kyc-proof/$H_PAYTO/$PROVIDER_SECTION - Update KYC status of a particular payment target. Provides +.. http:post:: /kyc-upload/$ID + + The ``/kyc-upload/$ID`` POST endpoint allows the SPA to upload + client-provided evidence. The ``$ID`` will be provided as part of the + ``/kyc-info`` body. This is for checks of type ``FORM``. In practice, + ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of the selected + measure (but this should be irrelevant for the client). + + This endpoint was introduced in protocol **v20**. + + **Request:** + + Basically oriented along the possible formats of a HTTP form being + POSTed. Details will depend on the form. The server will try to decode the + uploaded body from whatever format it is provided in. + + **Response:** + + :http:statuscode:`204 No Content`: + The information was successfully uploaded. The SPA should fetch + an updated ``/kyc-info/``. + :http:statuscode:`404 Not Found`: + The ``$ID`` is unknown to the exchange. + :http:statuscode:`409 Conflict`: + The upload conflicts with a previous upload. + :http:statuscode:`413 Request Entity Too Large`: + The body is too large. + +.. http:post:: /kyc-start/$ID + + The ``/kyc-start/$ID`` POST endpoint allows the SPA to set up a new external + KYC process. It will return the URL that the client must GET to begin the + KYC process. The SPA should probably open this URL in a new window or tab. + The ``$ID`` will be provided as part of the ``/kyc-info`` body. In + practice, ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of + the selected measure (but this should be irrelevant for the client). + + **Request:** + + Use empty JSON body for now. + + **Response:** + + :http:statuscode:`200 Ok`: + The KYC process was successfully initiated. The URL is in a + `KycProcessStartInformation` object. + :http:statuscode:`404 Not Found`: + The ``$ID`` is unknown to the exchange. + + **Details:** + + .. ts:def:: KycProcessStartInformation + + interface KycProcessStartInformation { + + // URL to open. + redirect_url: string; + } + + .. note:: + + As this endpoint is involved in every KYC check at the beginning, this + is also the place where we could integrate the payment process for the KYC fee + in the future (since **vATTEST**). + +.. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO + + Upon completion of the process at the external KYC provider, the provider + must redirect the client (browser) to trigger a GET request to a new + ``/kyc-proof/$H_PAYTO/$PROVIDER_SECTION`` endpoint. Once this endpoint is + triggered, the exchange will pass the received arguments to the respective + logic plugin. The logic plugin will then (asynchronously) update the KYC + status of the user. The logic plugin should redirect the user to the KYC + SPA. This endpoint deliberately does not use the ``$ACCESS_TOKEN`` as the + external KYC provider should not learn that token. + + This endpoint is thus accessed from the user's browser at the *end* of a + KYC process, possibly providing the exchange with additional + credentials to obtain the results of the KYC process. + Specifically, the URL arguments should provide information to the exchange that allows it to verify that the user has completed the KYC process. The details depend on - the logic, which is selected by the $PROVIDER_SECTION. + the logic, which is selected by the "$PROVIDER_SECTION". + + While this is a GET (and thus safe, and idempotent), the operation + may actually trigger significant changes in the exchange's state. + In particular, it may update the KYC status of a particular + payment target. **Request:** Details on the request depend on the specific KYC logic that was used. - If $LOGIC is "oauth2.0", the query parameters are: + If the KYC plugin logic is OAuth 2.0, the query parameters are: - :query code=CODE: OAuth 2.0 code argument. - :query state=CODE: OAuth 2.0 state argument. + :query code=CODE: + OAuth 2.0 code argument. + :query state=STATE: + OAuth 2.0 state argument with the H_PAYTO. - .. note:: + .. note:: - Depending on the OAuth variant used, additional - query parameters may need to be passed here. + Depending on the OAuth variant used, additional + query parameters may need to be passed here. **Response:** + Given that the response is returned to a user using a browser and **not** to + a Taler wallet, the response format is in human-readable HTML and not in + machine-readable JSON. + :http:statuscode:`302 Found`: The KYC operation succeeded and the payment target is now authorized to transact. @@ -4541,16 +5570,16 @@ KYC status updates service within a reasonable time period. -.. http:GET:: /kyc-webhook/$PROVIDER_SECTION/* -.. http:POST:: /kyc-webhook/$PROVIDER_SECTION/* -.. http:GET:: /kyc-webhook/$LOGIC/* -.. http:POST:: /kyc-webhook/$LOGIC/* +.. http:get:: /kyc-webhook/$PROVIDER_SECTION/* +.. http:post:: /kyc-webhook/$PROVIDER_SECTION/* +.. http:get:: /kyc-webhook/$LOGIC/* +.. http:post:: /kyc-webhook/$LOGIC/* - Update KYC status of a particular payment target. Provides - information to the KYC logic of the exchange that allows - it to verify that the user has completed the KYC process. - May be a GET or a POST request, depending on $LOGIC or - $PROVIDER_SECTION. + All of the above endpoints can be used to update KYC status of a particular + payment target. They provide information to the KYC logic of the exchange + that allows it to verify that the user has completed the KYC process. May + be a GET or a POST request, depending on the specific "$LOGIC" and/or the + "$PROVIDER_SECTION". **Request:** @@ -4560,7 +5589,7 @@ KYC status updates **Response:** :http:statuscode:`204 No content`: - The webhook succeeded. + The operation succeeded. :http:statuscode:`404 Not found`: The specified logic is unknown. @@ -4570,12 +5599,12 @@ Reserve control --------------- This section describes the reserve control API which can be used to (1) -prevent a reserve from expiring (which is useful if the reserve is used for -tipping), to (2) pay an annual fee to allow a number of purses to be created -for the respective reserve without paying a purse fee each time, to (3) obtain -KYC information associated with a reserve to prove the identity of the person -sending an invoice to the payer, and to (4) close a reserve before it would -naturally expire and possibly (5) wire the funds to a designated account. +prevent a reserve from expiring, to (2) pay an annual fee to allow a number of +purses to be created for the respective reserve without paying a purse fee +each time, to (3) obtain KYC information associated with a reserve to prove +the identity of the person sending an invoice to the payer, and to (4) close a +reserve before it would naturally expire and possibly (5) wire the funds to a +designated account. .. note:: @@ -4583,7 +5612,7 @@ naturally expire and possibly (5) wire the funds to a designated account. .. http:post:: /reserves/$RESERVE_PUB/open - Request keeping a reserve open for tipping or invoicing. + Request keeping a reserve open for invoicing. **Request:** @@ -4615,7 +5644,7 @@ naturally expire and possibly (5) wire the funds to a designated account. :http:statuscode:`451 Unavailable For Legal Reasons`: This account has not yet passed the KYC checks. The client must pass KYC checks before the reserve can be opened. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. **Details:** @@ -4624,7 +5653,7 @@ naturally expire and possibly (5) wire the funds to a designated account. interface ReserveOpenRequest { // Signature of purpose // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over - // a `TALER_ReserveOpenRequestSignaturePS`. + // a `TALER_ReserveOpenPS`. reserve_sig: EddsaSignature; // Array of payments made towards the cost of the @@ -4782,7 +5811,7 @@ naturally expire and possibly (5) wire the funds to a designated account. interface ReserveAttestResponse { // Signature of purpose // ``TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS`` over - // a `TALER_ExchangeReserveAttestDetailsSignaturePS`. + // a `TALER_ExchangeAttestPS`. exchange_sig: EddsaSignature; // Exchange public key used to create the @@ -4831,7 +5860,7 @@ naturally expire and possibly (5) wire the funds to a designated account. This account has not yet passed the KYC checks, hence wiring funds to a non-origin account is not allowed. The client must pass KYC checks before the reserve can be opened. - The response will be an `KycNeededRedirect` object. + The response will be an `LegitimizationNeededResponse` object. **Details:** @@ -4868,3 +5897,61 @@ naturally expire and possibly (5) wire the funds to a designated account. wire_amount: Amount; } + + +.. _delete-reserve: + +.. http:DELETE:: /reserves/$RESERVE_PUB + + Forcefully closes a reserve. + The request header must contain an *Account-Request-Signature*. + Note: this endpoint is not currently implemented! + + **Request:** + + *Account-Request-Signature*: The client must provide Base-32 encoded EdDSA signature made with ``$ACCOUNT_PRIV``, affirming its authorization to delete the account. The purpose used MUST be ``TALER_SIGNATURE_RESERVE_CLOSE``. + + :query force=BOOLEAN: *Optional.* If set to 'true' specified, the exchange + will delete the account even if there is a balance remaining. + + **Response:** + + :http:statuscode:`200 OK`: + The operation succeeded, the exchange provides details + about the account deletion. + The response will include a `ReserveDeletedResponse` object. + :http:statuscode:`403 Forbidden`: + The *Account-Request-Signature* is invalid. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + The account is unknown to the exchange. + :http:statuscode:`409 Conflict`: + The account is still has digital cash in it, the associated + wire method is ``void`` and the *force* option was not provided. + This response comes with a standard `ErrorDetail` response. + + **Details:** + + .. ts:def:: ReserveDeletedResponse + + interface ReserveDeletedResponse { + + // Final balance of the account. + closing_amount: Amount; + + // Current time of the exchange, used as part of + // what the exchange signs over. + close_time: Timestamp; + + // Hash of the wire account into which the remaining + // balance will be transferred. Note: may be the + // hash over ``payto://void/`, in which case the + // balance is forfeit to the profit of the exchange. + h_wire: HashCode; + + // This is a signature over a + // struct ``TALER_AccountDeleteConfirmationPS`` with purpose + // ``TALER_SIGNATURE_EXCHANGE_RESERVE_DELETED``. + exchange_sig: EddsaSignature; + + } |