diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 318 |
1 files changed, 168 insertions, 150 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 222d345e..5a734795 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-2023 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 @@ -25,6 +25,7 @@ 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 @@ -61,6 +62,7 @@ possibly by using HTTPS. 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 **v19**. **Response:** @@ -78,6 +80,10 @@ possibly by using HTTPS. // 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; @@ -97,7 +103,7 @@ possibly by using HTTPS. name: string; // Code of the currency. - // Deprecated in protocol v18 for the exchange + // Deprecated in protocol **v18** for the exchange // and in protocol v6 for the merchant. currency: string; @@ -168,10 +174,9 @@ possibly by using HTTPS. // Linear cost factor for the STEFAN curve used // 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 to be multiplied with. - stefan_lin: 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 @@ -192,7 +197,8 @@ possibly by using HTTPS. // Set to true if this exchange allows the use // of reserves for rewards. - rewards_allowed: boolean; + // @deprecated in protocol **v18**. + rewards_allowed: false; // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. @@ -249,6 +255,90 @@ possibly by using HTTPS. } + 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 }; + + } + .. ts:def:: GlobalFees interface GlobalFees { @@ -536,114 +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; - - // 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; - } - - .. 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 }; - - } - 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 @@ -658,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. @@ -685,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; @@ -1131,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 @@ -3391,7 +3383,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. @@ -3538,10 +3530,7 @@ the API during normal operation. .. 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 @@ -4863,9 +4852,18 @@ wallet-to-wallet payments. Only another exchange should access this endpoint. KYC status updates ------------------ +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 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:** @@ -4922,15 +4920,18 @@ KYC status updates .. http:get:: /kyc-check/$REQUIREMENT_ROW/$H_PAYTO/$USERTYPE - 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". + Checks the KYC status of a particular payment target and possibly begins the + KYC process. This endpoint is used by wallets or merchants that have been + told about a KYC requirement and now want to check if the KYC requirement + has been fulfilled. Long-polling may be used to instantly observe a change + in the KYC requirement status. + + Returns the current KYC status of the requirement process 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 a "business". **Request:** @@ -4949,12 +4950,13 @@ KYC status updates The response will be an `AccountKycStatus` object. :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-check/`` request should be repeated. + 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 `AccountKycRedirect` object. :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus - generally all accounts are simply considered legitimate. + the legal requirements are already satisfied. :http:statuscode:`402 Payment Required`: The client must pay the KYC fee for the KYC process. **This is currently not implemented, see #7365.** @@ -4964,6 +4966,10 @@ KYC status updates The payment target is unknown. :http:statuscode:`451 Unavailable for Legal Reasons`: The transaction cannot be completed due to AML rules. + Thus, the operation is currently not stuck on KYC, but + on exchange staff performing their AML review. The user + should be told to wait and/or contact the exchange operator + if the situation persists. The response will be a `AccountAmlBlocked` object. **Details:** @@ -5034,10 +5040,18 @@ KYC status updates .. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO - Update KYC status of a particular payment target. Provides + Endpoint 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:** @@ -5056,6 +5070,10 @@ KYC status updates **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. @@ -5078,11 +5096,11 @@ KYC status updates .. 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:** @@ -5092,7 +5110,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. @@ -5102,12 +5120,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 -rewards), 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:: @@ -5115,7 +5133,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 rewards or invoicing. + Request keeping a reserve open for invoicing. **Request:** |