.. This file is part of GNU TALER. Copyright (C) 2014-2020 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2.1, or (at your option) any later version. TALER is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with TALER; see the file COPYING. If not, see @author Christian Grothoff ============================= The Exchange RESTful JSON API ============================= The API specified here follows the :ref:`general conventions ` for all details not specified in the individual requests. The `glossary `_ defines all specific terms used in this section. .. _keys: -------------------- Terms of service API -------------------- These APIs allow merchants and wallets to obtain the terms of service and the privacy policy of an exchange. .. http:get:: /terms Get the terms of service of the exchange. The exchange will consider the "Accept" and "Accept-Language" and "Accept-Encoding" headers when generating a response. Specifically, it will try to find a response with an acceptable mime-type, then pick the version in the most preferred language of the user, and finally apply compression if that is allowed by the client and deemed beneficial. The exchange will set an "Etag", and subsequent requests of the same client should provide the tag in an "If-None-Match" header to detect if the terms of service have changed. If not, a "204 Not Modified" response will be returned. If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the terms of service were not configured correctly. .. http:get:: /privacy Get the privacy policy of the exchange. The exchange will consider the "Accept" and "Accept-Language" and "Accept-Encoding" headers when generating a response. Specifically, it will try to find a response with an acceptable mime-type, then pick the version in the most preferred language of the user, and finally apply compression if that is allowed by the client and deemed beneficial. The exchange will set an "Etag", and subsequent requests of the same client should provide the tag in an "If-None-Match" header to detect if the privacy policy has changed. If not, a "204 Not Modified" response will be returned. If the "Etag" is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the privacy policy was not configured correctly. --------------------------- Exchange status information --------------------------- This API is used by wallets and merchants to obtain global information about the exchange, such as online signing keys, available denominations and the fee structure. This is typically the first call any exchange client makes, as it returns information required to process all of the other interactions with the exchange. The returned information is secured by (1) signature(s) from the exchange, especially the long-term offline signing key of the exchange, which clients should cache; (2) signature(s) from auditors, and the auditor keys should be hard-coded into the wallet as they are the trust anchors for Taler; (3) possibly by using HTTPS. .. http:get:: /seed Return an entropy seed. The exchange will return a high-entropy value that will differ for every call. The response is NOT in JSON, but simply high-entropy binary data in the HTTP body. This API should be used by wallets to guard themselves against running on low-entropy (bad PRNG) hardware. Naturally, the entropy returned MUST be mixed with locally generated entropy. .. http:get:: /keys Get a list of all denomination keys offered by the exchange, as well as the exchange's current online signing key. **Request:** :query last_issue_date: Optional argument specifying the maximum value of any of the ``stamp_start`` members of the denomination keys of a ``/keys`` response that is already known to the client. Allows the exchange to only return keys that have changed since that timestamp. The given value must be an unsigned 64-bit integer representing seconds after 1970. If the timestamp does not exactly match the ``stamp_start`` of one of the denomination keys, all keys are returned. **Response:** :http:statuscode:`200 OK`: The exchange responds with a `ExchangeKeysResponse` object. This request should virtually always be successful. It only fails if the exchange is misconfigured or has not yet been provisioned with key signatures via ``taler-exchange-offline``. **Details:** .. ts:def:: ExchangeKeysResponse interface ExchangeKeysResponse { // 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; // The exchange's currency. currency: string; // EdDSA master public key of the exchange, used to sign entries // in ``denoms`` and ``signkeys``. master_public_key: EddsaPublicKey; // Relative duration until inactive reserves are closed; // not signed (!), can change without notice. reserve_closing_delay: RelativeTime; // Denominations offered by this exchange. denoms: Denom[]; // Denominations for which the exchange currently offers/requests recoup. recoup: Recoup[]; // Fees relevant for wallet-to-wallet (or peer-to-peer) payments. // If no fees are provided for a given time range, then the // exchange simply does not support purses/p2p-payments at that time. p2p_fees: P2Pfees[]; // The date when the denomination keys were last updated. list_issue_date: Timestamp; // Auditors of the exchange. auditors: AuditorKeys[]; // 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 `. 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. eddsa_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 ``/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:: P2PFees interface P2PFees { // What date (inclusive) does these fees go into effect? start_date: Timestamp; // What date (exclusive) does this fees stop going into effect? end_date: Timestamp; // KYC fee, charged when a user wants to create an account. // The first year of the account_annual_fee after the KYC is // always included. kyc_fee: Amount; // Account history fee, charged when a user wants to // obtain the full account history, and not just the // recent transactions in an account. account_history_fee: Amount; // Annual fee charged for having an open account at the // exchange. Charged to the account. If the account // balance is insufficient to cover this fee, the account // is automatically deleted/closed. (Note that the exchange // will keep the account history around for longer for // regulatory reasons.) account_annual_fee: Amount; // How long will the exchange preserve the account // history? After an account was deleted/closed, the // exchange will retain the account history for // legal reasons until this time. legal_history_retention: RelativeTime; // How long does the exchange promise to keep funds // an account for which the KYC has never happened // after a purse was merged into an account? Basically, // after this time funds in an account without KYC are // forfeit. account_kyc_timeout: RelativeTime; // Purse fee, charged only if a purse is abandoned // and was not covered by the account limit. purse_fee: Amount; // Non-negative number of concurrent purses that any // account holder is allowed to create without having // to pay the purse_fee. purse_account_limit: integer; // How long does an exchange keep a purse around // after a purse has expired (or been successfully // merged)? A 'GET' request for a purse will // succeed until the purse expiration time plus this // value. purse_timeout: RelativeTime; // Signature of `TALER_P2PFeesPS`. master_sig: EddsaSignature; } .. 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; // 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 (RSA) key for the denomination. denom_pub: RsaPublicKey; // 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; } Fees for any of the operations can be zero, but the fields must still be present. The currency of the ``fee_deposit``, ``fee_refresh`` and ``fee_refund`` must match the currency of the ``value``. Theoretically, the ``fee_withdraw`` could be in a different currency, but this is not currently supported by the implementation. .. ts:def:: Recoup interface Recoup { // Hash of the public key of the denomination that is being revoked under // emergency protocol (see ``/recoup``). h_denom_pub: HashCode; // We do not include any signature here, as the primary use-case for // this emergency involves the exchange having lost its signing keys, // so such a signature here would be pretty worthless. However, the // exchange will not honor ``/recoup`` requests unless they are for // denomination keys listed here. } A signing key in the ``signkeys`` list is a JSON object with the following fields: .. ts:def:: SignKey interface SignKey { // The actual exchange's EdDSA signing public key. key: EddsaPublicKey; // Initial validity date for the signing key. stamp_start: Timestamp; // Date when the exchange will stop using the signing key, allowed to overlap // slightly with the next signing key's validity to allow for clock skew. stamp_expire: Timestamp; // Date when all signatures made by the signing key expire and should // henceforth no longer be considered valid in legal disputes. stamp_end: Timestamp; // Signature over ``key`` and ``stamp_expire`` by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``. master_sig: EddsaSignature; } An entry in the ``auditors`` list is a JSON object with the following fields: .. ts:def:: AuditorKeys interface AuditorKeys { // The auditor's EdDSA signing public key. auditor_pub: EddsaPublicKey; // The auditor's URL. auditor_url: string; // The auditor's name (for humans). auditor_name: string; // An array of denomination keys the auditor affirms with its signature. // Note that the message only includes the hash of the public key, while the // signature is actually over the expanded information including expiration // times and fees. The exact format is described below. denomination_keys: AuditorDenominationKey[]; } .. ts:def:: AuditorDenominationKey interface AuditorDenominationKey { // Hash of the public RSA key used to sign coins of the respective // denomination. Note that the auditor's signature covers more than just // the hash, but this other information is already provided in ``denoms`` and // thus not repeated here. denom_pub_h: HashCode; // Signature of `TALER_ExchangeKeyValidityPS`. auditor_sig: EddsaSignature; } The same auditor may appear multiple times in the array for different subsets of denomination keys, and the same denomination key hash may be listed multiple times for the same or different auditors. The wallet or merchant just should check that the denomination keys they use are in the set for at least one of the auditors that they accept. .. note:: 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. "sepa" 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 // 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 respective array contains objects with the following members: .. ts:def:: AggregateTransferFee interface AggregateTransferFee { // Per transfer wire transfer fee. wire_fee: Amount; // Per transfer closing fee. closing_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. start_date: Timestamp; // What date (exclusive) does this fee stop going into effect? // The different fees must cover the full time period in which // any of the denomination keys are valid without overlap. end_date: Timestamp; // Signature of `TALER_MasterWireFeePS` with // purpose ``TALER_SIGNATURE_MASTER_WIRE_FEES``. sig: EddsaSignature; } .. ts:def:: ExchangePartner interface ExchangePartner { // Base URL of the partner exchange. partner_base_url: string; // Public master key of the partner exchange. partner_master_pub: EddsaPublicKey; // Wallet-to-wallet transfer wad fee charged. wad_fee: Amount; // Exchange-to-exchange wad (wire) transfer frequency. wad_frequency: RelativeTime; // When did this partnership begin (under these conditions)? start_date: Timestamp; // How long is this partnership expected to last? end_date: Timestamp; // Signature using the exchange's offline key // with purpose ``TALER_SIGNATURE_MASTER_PARTNER_DETAILS``. master_sig: EddsaSignature; } ---------------------------------------------- Management operations authorized by master key ---------------------------------------------- .. http:get:: /management/keys Get a list of future public keys to be used by the exchange. Only to be used by the exchange's offline key management team. Not useful for anyone else (but also not secret, so access is public). **Response:** :http:statuscode:`200 OK`: The exchange responds with a `FutureKeysResponse` object. This request should virtually always be successful. **Details:** .. ts:def:: FutureKeysResponse interface FutureKeysResponse { // Future denominations to be offered by this exchange // (only those lacking a master signature). future_denoms: FutureDenom[]; // The exchange's future signing keys (only those lacking a master signature). future_signkeys: FutureSignKey[]; // Master public key expected by this exchange (provided so that the // offline signing tool can check that it has the right key). master_pub: EddsaPublicKey; // Public key of the denomination security module. denom_secmod_public_key: EddsaPublicKey; // Public key of the signkey security module. signkey_secmod_public_key: EddsaPublicKey; } .. ts:def:: FutureDenom interface FutureDenom { // Name in the configuration file that defines this denomination. section_name: string; // 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 withdraw coins // of this denomination? stamp_expire_withdraw: Timestamp; // When is it no longer possible to deposit coins // of this denomination? 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 (RSA) key for the denomination. denom_pub: RsaPublicKey; // 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 over this denomination by the denomination security module. denom_secmod_sig: EddsaSignature; } .. ts:def:: FutureSignKey interface SignKey { // The actual exchange's EdDSA signing public key. key: EddsaPublicKey; // Initial validity date for the signing key. stamp_start: Timestamp; // Date when the exchange will stop using the signing key, allowed to overlap // slightly with the next signing key's validity to allow for clock skew. stamp_expire: Timestamp; // Date when all signatures made by the signing key expire and should // henceforth no longer be considered valid in legal disputes. stamp_end: Timestamp; // Signature over this signing key by the signkey security module. signkey_secmod_sig: EddsaSignature; } .. http:post:: /management/keys Provide master signatures for future public keys to be used by the exchange. Only to be used by the exchange's offline key management team. Not useful for anyone else. **Request:** The request body must be a `MasterSignatures` object. **Response:** :http:statuscode:`204 No content`: The request was successfully processed. :http:statuscode:`403 Forbidden`: A provided signature is invalid. :http:statuscode:`404 Not found`: One of the keys for which a signature was provided is unknown to the exchange. **Details:** .. ts:def:: MasterSignatures interface MasterSignatures { // Provided master signatures for future denomination keys. denom_sigs: DenomSignature[]; // Provided master signatures for future online signing keys. signkey_sigs: SignKeySignature[]; } .. ts:def:: DenomSignature interface DenomSignature { // Hash of the public (RSA) key of the denomination. h_denom_pub: HashCode; // Signature of `TALER_DenominationKeyValidityPS`. master_sig: EddsaSignature; } .. ts:def:: SignKeySignature interface SignKeySignature { // The actual exchange's EdDSA signing public key. key: EddsaPublicKey; // Signature by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``. master_sig: EddsaSignature; } .. http:post:: /management/denominations/$H_DENOM_PUB/revoke Revoke denomination key, preventing further use by the exchange. Only to be used by the exchange's offline key management team. Not useful for anyone else. **Request:** The request body must be a `DenomRevocationSignature` object. **Response:** :http:statuscode:`204 No content`: The request was successfully processed. :http:statuscode:`403 Forbidden`: The provided signature is invalid. **Details:** .. ts:def:: DenomRevocationSignature interface DenomRevocationSignature { // Signature by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``. master_sig: EddsaSignature; } .. http:post:: /management/signkeys/$EXCHANGE_PUB/revoke Revoke exchange online signing key, preventing further use by the exchange. Only to be used by the exchange's offline key management team. Not useful for anyone else. **Request:** The request body must be a `SignkeyRevocationSignature` object. **Response:** :http:statuscode:`204 No content`: The request was successfully processed. :http:statuscode:`403 Forbidden`: The provided signature is invalid. **Details:** .. ts:def:: SignkeyRevocationSignature interface SignkeyRevocationSignature { // Signature by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_SIGN_KEY_REVOKED``. master_sig: EddsaSignature; } .. http:post:: /management/auditors This request will be used to enable an auditor. **Request:** The request must be a `AuditorSetupMessage`. **Response:** :http:statuscode:`204 No content`: The auditor was successfully enabled. :http:statuscode:`403 Forbidden`: The master signature is invalid. :http:statuscode:`409 Conflict`: The exchange has a more recent request related to this auditor key (replay detected). **Details:** .. ts:def:: AuditorSetupMessage interface AuditorSetupMessage { // Base URL of the auditor. auditor_url: string; // Human-readable name of the auditor. auditor_name: string; // The auditor's EdDSA signing public key. auditor_pub: EddsaPublicKey; // Signature by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_ADD``. master_sig: EddsaSignature; // When does the auditor become active? // Should be the time when the signature was created, // using the (monotonic!) local time of the system // with the offline master public key. Note that // even if the time is in the future, the auditor will // become active immediately! Used ONLY to detect replay attacks. validity_start: Timestamp; } .. http:post:: /management/auditors/$AUDITOR_PUB/disable This request will be used to disable the use of the given auditor. We use POST instead of DELETE because the exchange will retain state about the auditor (specifically the end date) to prevent replay attacks abusing the `AuditorSetupMessage`. Also, DELETE would not support a body, which is needed to provide the signature authorizing the operation. **Request:** The request must be a `AuditorTeardownMessage`. **Response** :http:statuscode:`204 No content`: The auditor has successfully disabled the auditor. The body is empty. :http:statuscode:`403 Forbidden`: The signature is invalid. :http:statuscode:`404 Not found`: The auditor is unknown to the exchange. :http:statuscode:`409 Conflict`: The exchange has a more recent request related to this auditor key (replay detected). **Details:** .. ts:def:: AuditorTeardownMessage interface AuditorTeardownMessage { // Signature by the exchange master key. // Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_DEL``. master_sig: EddsaSignature; // When does the auditor become inactive? // Should be the time when the signature was created, // using the (monotonic!) local time of the system // with the offline master public key. Note that // even if the time is in the future, the auditor will // become inactive immediately! Used ONLY to detect replay attacks. validity_end: Timestamp; } .. http:post:: /management/wire-fee This request will be used to configure wire fees. **Request:** The request must be a `WireFeeSetupMessage`. **Response:** :http:statuscode:`204 No content`: The wire fee was successfully configured. :http:statuscode:`403 Forbidden`: The master signature is invalid. :http:statuscode:`409 Conflict`: The exchange has a conflicting wire fee already set up. :http:statuscode:`412 Precondition failed`: The currency used is different from the currency of the exchange. **Details:** .. ts:def:: WireFeeSetupMessage interface WireFeeSetupMessage { // Wire method the fee applies to. wire_method: string; // Signature using the exchange's offline key // with purpose ``TALER_SIGNATURE_MASTER_WIRE_FEES``. master_sig_wire: EddsaSignature; // When does the wire fee validity period start? fee_start: Timestamp; // When does the wire fee validity period end (exclusive). fee_end: Timestamp; // Closing fee to charge during that time period for this wire method. closing_fee: Amount; // Wire fee to charge during that time period for this wire method. wire_fee: Amount; } .. http:post:: /management/wire This request will be used to enable a wire method (exchange bank account). **Request:** The request must be a `WireSetupMessage`. **Response:** :http:statuscode:`204 No content`: The wire method was successfully enabled. :http:statuscode:`403 Forbidden`: The master signature is invalid. :http:statuscode:`409 Conflict`: The exchange has a more recent request related to this wire method (replay detected). **Details:** .. ts:def:: WireSetupMessage interface WireSetupMessage { // ``payto://`` URL identifying the account and wire method payto_uri: string; // Signature using the exchange's offline key // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``. master_sig_wire: EddsaSignature; // Signature using the exchange's offline key // with purpose ``TALER_SIGNATURE_MASTER_WIRE_ADD``. master_sig_add: EddsaSignature; // When does the wire method become active? // Should be the time when the signature was created, // using the (monotonic!) local time of the system // with the offline master public key. Note that // even if the time is in the future, the wire method will // become active immediately! Used ONLY to detect replay attacks. validity_start: Timestamp; } .. http:post:: /management/wire/disable This request will be used to disable the use of the given wire method. We use POST instead of DELETE because the exchange will retain state about the wire method (specifically the end date) to prevent replay attacks abusing the `WireSetupMessage`. Also, DELETE would not support a body, which is needed to provide the signature authorizing the operation. **Request:** The request must be a `WireTeardownMessage`. **Response** :http:statuscode:`204 No content`: The auditor has successfully disabled the wire method. The body is empty. :http:statuscode:`403 Forbidden`: The signature is invalid. :http:statuscode:`404 Not found`: The wire method is unknown to the exchange. :http:statuscode:`409 Conflict`: The exchange has a more recent request related to this wire method (replay detected). **Details:** .. ts:def:: WireTeardownMessage interface WireTeardownMessage { // ``payto://`` URL identifying the account and wire method payto_uri: string; // Signature using the exchange's offline key // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DEL``. master_sig_del: EddsaSignature; // Should be the time when the signature was created, // using the (monotonic!) local time of the system // with the offline master public key. Note that // even if the time is in the future, the wire method will // become inactive immediately! Used ONLY to detect replay attacks. validity_end: Timestamp; } --------------- Auditor actions --------------- .. _auditor_action: This part of the API is for the use by auditors interacting with the exchange. .. http:post:: /auditors/$AUDITOR_PUB/$H_DENOM_PUB 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. **Request:** The request must be a `AuditorSignatureAddMessage`. **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. :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. **Details:** .. ts:def:: AuditorSignatureAddMessage interface AuditorSignatureAddMessage { // Signature by the auditor. // Must have purpose ``TALER_SIGNATURE_AUDITOR_XXX``. auditor_sig: EddsaSignature; } ---------- Withdrawal ---------- This API is used by the wallet to obtain digital coins. 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. .. note:: 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/status Request information about a reserve or an account. **Request:** :query history=BOOLEAN: *Optional.* If specified, the exchange will return the recent account history. This is still free of charge. :query full_history=BOOLEAN: *Optional.* If 'true' is specified, the exchange will return the full account history. This may incur a fee that will be charged to the account. The request body must be a `ReserveStatusRequest` object. **Response:** :http:statuscode:`200 OK`: The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. :http:statuscode:`401 Unauthorized`: The *Account-Request-Signature* is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The reserve key does not belong to a reserve known to the exchange. **Details:** .. ts:def:: ReserveStatusRequest interface ReserveStatusRequest { // Signature of type // TALER_SIGNATURE_RESERVE_STATUS_REQUEST reserve_sig: EddsaSignature; } .. ts:def:: ReserveStatus interface ReserveStatus { // Balance left in the reserve. balance: Amount; // True if the owner of the account currently satisfies // the required KYC checks. kyc_passed: boolean; // True if the reserve history includes a merge of a purse // and thus the owner must pass KYC checks before withdrawing. kyc_required: boolean; // Transaction history for this reserve. // May be partial (!). history: TransactionHistoryItem[]; } Objects in the transaction history have the following format: .. ts:def:: TransactionHistoryItem // Union discriminated by the "type" field. type TransactionHistoryItem = | AccountMergeTransaction | AccountSetupTransaction | ReserveHistoryTransaction | ReserveWithdrawTransaction | ReserveCreditTransaction | ReserveClosingTransaction | ReserveRecoupTransaction; .. ts:def:: AccountHistoryTransaction interface AccountHistoryTransaction { type: "HISTORY"; // Fee agreed to by the reserve owner. history_fee: 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. reserve_sig: EddsaSignature; } .. ts:def:: AccountSetupTransaction interface AccountSetupTransaction { type: "SETUP"; // 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; // Signature created with the reserve's private key. // Must be of purpose TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST. reserve_sig: EddsaSignature; } .. ts:def:: AccountMergeTransaction interface AccountMergeTransaction { type: "MERGE"; // Actual amount merged (what was left after fees). amount: Amount; // Minimum amount merged (amount signed by the // reserve and purse signatures). minimum_amount: Amount; // Purse that was merged. purse_pub: EddsaPublicKey; // Time of the merge. merge_timestamp: Timestamp; // Expiration time of the purse. purse_expiration: Timestamp; // Hash of the contract. h_contract: HashCode; // Signature created with the reserve's private key. // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE. reserve_sig: EddsaSignature; // Signature created with the purse's private key. // Must be of purpose TALER_SIGNATURE_PURSE_MERGE. purse_sig: EddsaSignature; // Deposit fees that were charged to the purse. deposit_fees: Amount; } .. ts:def:: ReserveWithdrawTransaction interface ReserveWithdrawTransaction { type: "WITHDRAW"; // Amount withdrawn. amount: Amount; // Hash of the denomination public key of the coin. h_denom_pub: HashCode; // Hash of the blinded coin to be signed. h_coin_envelope: HashCode; // Signature of ``TALER_WithdrawRequestPS`` created with the reserve's // private key. reserve_sig: EddsaSignature; // Fee that is charged for withdraw. withdraw_fee: Amount; } .. ts:def:: ReserveCreditTransaction interface ReserveCreditTransaction { type: "CREDIT"; // Amount deposited. amount: Amount; // Sender account ``payto://`` URL. sender_account_url: string; // 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:: ReserveClosingTransaction interface ReserveClosingTransaction { type: "CLOSING"; // Closing balance. amount: Amount; // Closing fee charged by the exchange. closing_fee: Amount; // Wire transfer subject. wtid: string; // ``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:: ReserveRecoupTransaction interface ReserveRecoupTransaction { type: "RECOUP"; // Amount paid back. amount: Amount; // This is a signature over // a struct ``TALER_PaybackConfirmationPS`` with purpose // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK``. exchange_sig: EddsaSignature; // Public key used to create ``exchange_sig``. exchange_pub: EddsaPublicKey; // Time when the funds were paid back into the reserve. timestamp: Timestamp; // Public key of the coin that was paid back. coin_pub: CoinPublicKey; } .. http:post:: /reserves/$RESERVE_PUB/history Request information about the full history of a reserve or an account. **Request:** The request body must be a `ReserveHistoryRequest` object. **Response:** :http:statuscode:`200 OK`: The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange. :http:statuscode:`401 Unauthorized`: The *Account-Request-Signature* is invalid. This response comes with a standard `ErrorDetail` response. :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 interface ReserveHistoryRequest { // Signature of type // TALER_SIGNATURE_RESERVE_HISTORY_REQUEST reserve_sig: EddsaSignature; // 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; } .. 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 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. **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. :http:statuscode:`202 Accepted`: This reserve has received funds from a purse and must be upgraded to an account (with KYC) before the withdraw can complete. Note that this response does NOT affirm that the withdraw will ultimately complete with the requested amount. 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 `AccountKycRedirect` object. :http:statuscode:`403 Forbidden`: The signature is invalid. :http:statuscode:`404 Not found`: The 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``. 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 a coin of the indicated denomination. The response is `WithdrawError` object. :http:statuscode:`410 Gone`: The requested denomination key is no longer valid. It either expired or was revoked. :http:statuscode:`412 Precondition failed`: The requested denomination key is not yet valid. It is too early to withdraw. **Details:** .. ts:def:: WithdrawRequest interface WithdrawRequest { // Hash of a denomination public key (RSA), specifying the type of coin the client // would like the exchange to create. denom_pub_hash: HashCode; // Coin's blinded public key, should be (blindly) signed by the exchange's // denomination private key. coin_ev: CoinEnvelope; // Signature of `TALER_WithdrawRequestPS` created with // the `reserves's private key `. reserve_sig: EddsaSignature; } .. ts:def:: WithdrawResponse interface WithdrawResponse { // The blinded RSA signature over the ``coin_ev``, affirms the coin's // validity after unblinding. ev_sig: BlindedRsaSignature; } .. ts:def:: WithdrawError interface WithdrawError { // Text describing the error. hint: string; // Detailed error code. code: Integer; // Amount left in the reserve. balance: Amount; // History of the reserve's activity, in the same format // as returned by ``/reserve/status``. history: TransactionHistoryItem[] } .. http:DELETE:: /reserves/$RESERVE_PUB Forcefully closes a reserve. The request header must contain an *Account-Request-Signature*. **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 `ReserveClosedResponse` object. :http:statuscode:`401 Unauthorized`: 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:: ReserveClosedResponse interface ReserveClosedResponse { // 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_CLOSED``. exchange_sig: EddsaSignature; } .. _deposit-par: ------- Deposit ------- Deposit operations are requested by a merchant during a transaction. For the deposit operation, 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. .. _deposit: .. http:POST:: /coins/$COIN_PUB/deposit 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. 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. The request should contain a JSON object with the following fields: **Request:** The request body must be a `DepositRequest` object. **Response:** :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:`401 Unauthorized`: One of the signatures is invalid. :http:statuscode:`404 Not found`: Either the denomination key is not recognized (expired or invalid) or the wire type is not recognized. :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_DEPOSIT_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`. **Details:** .. ts:def:: DepositRequest interface DepositRequest { // Amount to be deposited, can be a fraction of the // coin's total value. contribution: Amount; // The merchant's account details. // The salt is used to hide the ``payto_uri`` from customers // that learn the ``h_wire`` of the merchant. wire: { payto_uri: string; salt: HashCode; }; // SHA-512 hash of the merchant's payment details from ``wire``. Although // strictly speaking redundant, this helps detect inconsistencies. h_wire: HashCode; // SHA-512 hash of the contract of the merchant with the customer. Further // details are never disclosed to the exchange. h_contract_terms: HashCode; // Hash of denomination RSA key with which the coin is signed. denom_pub_hash: HashCode; // Exchange's unblinded RSA signature of the coin. ub_sig: RsaSignature; // Timestamp when the contract was finalized. timestamp: Timestamp; // Indicative time by which the exchange undertakes to transfer the funds to // the merchant, in case of successful payment. wire_transfer_deadline: Timestamp; // EdDSA `public key of the merchant `, 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 // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; // Signature of `TALER_DepositRequestPS`, made by the customer with the // `coin's private key `. coin_sig: EddsaSignature; } 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:: DepositSuccess 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; // Timestamp when the deposit was received by the exchange. exchange_timestamp: Timestamp; // The EdDSA signature of `TALER_DepositConfirmationPS` using a current // `signing key of the exchange ` 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; // `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. exchange_pub: EddsaPublicKey; } .. ts:def:: DepositDoubleSpendError interface DepositDoubleSpendError { // The string constant "insufficient funds". hint: string; // Transaction history for the coin that is // being double-spended. history: CoinSpendHistoryItem[]; } .. ts:def:: CoinSpendHistoryItem // Union discriminated by the "type" field. type CoinSpendHistoryItem = | CoinDepositTransaction | CoinMeltTransaction | CoinRefundTransaction | CoinRecoupTransaction | CoinOldCoinRecoupTransaction | CoinRecoupRefreshTransaction | CoinPursePaymentTransaction; .. ts:def:: CoinDepositTransaction interface CoinDepositTransaction { type: "DEPOSIT"; // The total amount of the coin's value absorbed (or restored in the // case of a refund) by this transaction. // The amount given includes // the deposit fee. The current coin value can thus be computed by // subtracting this amount. amount: Amount; // Deposit fee. deposit_fee: Amount; // Public key of the merchant. merchant_pub: EddsaPublicKey; // Date when the operation was made. timestamp: Timestamp; // Date until which the merchant can issue a refund to the customer via the // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; // Signature by the coin. coin_sig: EddsaSignature; // Hash of the bank account from where we received the funds. h_wire: HashCode; // Hash of the public denomination key used to sign the coin. // FIXME: why do we care to have this? h_denom_pub: HashCode; // Hash over the proposal data of the contract that // is being paid. h_contract_terms: HashCode; } .. ts:def:: CoinMeltTransaction interface CoinMeltTransaction { type: "MELT"; // 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 // subtracting the amounts. amount: Amount; // Signature by the coin. coin_sig: EddsaSignature; // Melt fee. melt_fee: Amount; // Commitment from the melt operation. rc: TALER_RefreshCommitmentP; // Hash of the public denomination key used to sign the coin. // FIXME: why do we care to have this? h_denom_pub: HashCode; } .. ts:def:: CoinRefundTransaction interface CoinRefundTransaction { type: "REFUND"; // The total amount of the coin's value restored // by this transaction. // The amount given excludes the transaction fee. // The current coin value can thus be computed by // adding the amounts to the coin's denomination value. amount: Amount; // Refund fee in case of type "REFUND". refund_fee: Amount; // Hash over the proposal data of the contract that // is being refunded. h_contract_terms: HashCode; // Refund transaction ID. rtransaction_id: Integer; // `EdDSA Signature ` authorizing the REFUND. Made with // the `public key of the merchant `. merchant_sig: EddsaSignature; } .. ts:def:: CoinRecoupTransaction interface CoinRecoupTransaction { type: "RECOUP"; // The total amount of the coin's value absorbed // by this transaction. // The current coin value can thus be computed by // subtracting the amount from // the coin's denomination value. amount: Amount; // Date when the operation was made. timestamp: Timestamp; // Signature by the coin. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. // FIXME: why do we care to have this? h_denom_pub: HashCode; // Coin blinding key. coin_blind: DenominationBlindingKeyP; // Reserve receiving the recoup. reserve_pub: EddsaPublicKey; // Signature by the exchange, must be // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP. exchange_sig: EddsaSignature; // Public key used to sign ``exchange_sig`` exchange_pub: EddsaPublicKey; } .. ts:def:: CoinOldCoinRecoupTransaction interface CoinOldCoinRecoupTransaction { type: "OLD-COIN-RECOUP"; // The total amount of the coin's value restored // by this transaction. // The current coin value can thus be computed by // adding the amount to the coin's denomination value. amount: Amount; // Date when the operation was made. timestamp: Timestamp; // Signature by the exchange // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH. exchange_sig: EddsaSignature; // Public key used to sign ``exchange_sig``, exchange_pub: EddsaPublicKey; } .. ts:def:: CoinRecoupRefreshTransaction interface CoinRecoupRefreshTransaction { type: "RECOUP-REFRESH"; // The total amount of the coin's value absorbed // by this transaction. // The current coin value can thus be computed by // subtracting this amounts from // the coin's denomination value. amount: Amount; // Date when the operation was made. timestamp: Timestamp; // Signature by the coin. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. // FIXME: why do we care to have this? h_denom_pub: HashCode; // Coin blinding key. coin_blind: DenominationBlindingKeyP; // Signature by the exchange // of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH. exchange_sig: EddsaSignature; // Public key used to sign ``exchange_sig``, exchange_pub: EddsaPublicKey; // Blinding factor of the revoked new coin. new_coin_blinding_secret: RsaBlindingKeySecret; // Blinded public key of the revoked new coin. new_coin_ev: RsaBlindingKeySecret; } .. ts:def:: CoinPursePaymentTransaction interface CoinPursePaymentTransaction { type: "PURSE_PAYMENT"; // The total amount of the coin's value absorbed // by this transaction. // Note that this means the amount given includes // the deposit fee. The current coin value can thus be computed by // subtracting the amount from // the coin's denomination value. amount: Amount; // Deposit fee. deposit_fee: Amount; // Public key of the purse. purse_pub: EddsaPublicKey; // Date when the purse was set to expire. purse_expiration: Timestamp; // Signature by the coin. coin_sig: EddsaSignature; // Hash of the public denomination key used to sign the coin. // FIXME: why do we care to have this? h_denom_pub: HashCode; } ---------- Refreshing ---------- Refreshing creates ``n`` new coins from ``m`` old coins, where the sum of denominations of the new coins must be smaller than the sum of the old coins' denominations plus melting (refresh) and withdrawal fees charged by the exchange. The refreshing API can be used by wallets to melt partially spent coins, making transactions with the freshly exchangeed coins unlinkabe to previous transactions by anyone except the wallet itself. However, the new coins are linkable from the private keys of all old coins using the ``/refresh/link`` request. While ``/refresh/link`` must be implemented by the exchange to achieve taxability, wallets do not really ever need that part of the API during normal operation. .. _refresh: .. http:post:: /coins/$COIN_PUB/melt "Melts" a coin. Invalidates the coins and prepares for exchanging of fresh coins. Taler uses a global parameter ``kappa`` for the cut-and-choose component of the protocol, for which this request is the commitment. Thus, various arguments are given ``kappa``-times in this step. At present ``kappa`` is always 3. 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. :http:statuscode:`200 OK`: The request was successful. The response body is `MeltResponse` in this case. :http:statuscode:`403 Forbidden`: One of the signatures is invalid. :http:statuscode:`404 Not found`: The exchange does not recognize the denomination key as belonging to the exchange, or it has expired. :http:statuscode:`409 Conflict`: The operation is not allowed as 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_MELT_INSUFFICIENT_FUNDS`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). The response is `MeltForbiddenResponse` in both cases. **Details:** .. ts:def:: MeltRequest interface MeltRequest { // Hash of the denomination public key, to determine total coin value. denom_pub_hash: HashCode; // Signature over the `coin public key ` by the denomination. denom_sig: RsaSignature; // Signature by the `coin ` over the melt commitment. confirm_sig: EddsaSignature; // Amount of the value of the coin that should be melted as part of // this refresh operation, including melting fee. value_with_fee: Amount; // Melt commitment. Hash over the various coins to be withdrawn. // See also ``TALER_refresh_get_commitment()``. rc: TALER_RefreshCommitmentP; } For details about the HKDF used to derive the new coin private keys and the blinding factors from ECDHE between the transfer public keys and the private key of the melted coin, please refer to the implementation in ``libtalerutil``. .. ts:def:: MeltResponse interface MeltResponse { // Which of the ``kappa`` indices does the client not have to reveal. noreveal_index: Integer; // Signature of `TALER_RefreshMeltConfirmationPS` whereby the exchange // affirms the successful melt and confirming the ``noreveal_index``. 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 ``/keys``. Again given // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. exchange_pub: EddsaPublicKey; // Base URL to use for operations on the refresh context // (so the reveal operation). If not given, // the base URL is the same as the one used for this request. // Can be used if the base URL for ``/refreshes/`` differs from that // for ``/coins/``, i.e. for load balancing. Clients SHOULD // respect the refresh_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 melt. // // When melting the same coin twice (technically allowed // as the response might have been lost on the network), // the exchange may return different values for the ``refresh_base_url``. refresh_base_url?: string; } .. ts:def:: MeltForbiddenResponse interface MeltForbiddenResponse { // Text describing the error. hint: string; // Detailed error code. code: Integer; // Public key of a melted coin that had insufficient funds. coin_pub: EddsaPublicKey; // Original total value of the coin. original_value: Amount; // Remaining value of the coin. residual_value: Amount; // Amount of the coin's value that was to be melted. requested_value: Amount; // The transaction list of the respective coin that failed to have sufficient funds left. // Note that only the transaction history for one bogus coin is given, // even if multiple coins would have failed the check. history: CoinSpendHistoryItem[]; } .. http:post:: /refreshes/$RCH/reveal Reveal previously committed values to the exchange, except for the values corresponding to the ``noreveal_index`` returned by the ``/coins/``-melt step. The $RCH is the hash over the refresh commitment from the ``/coins/``-melt step (note that the value is calculated independently by both sides and has never appeared *explicitly* in the protocol before). The base URL for ``/refreshes/``-requests may differ from the main base URL of the exchange. Clients SHOULD respect the ``refresh_base_url`` returned for the coin during melt operations. The exchange MUST return a 307 or 308 redirection to the correct base URL if the client failed to respect the ``refresh_base_url`` or if the allocation has changed. Errors such as failing to do proper arithmetic when it comes to calculating the total of the coin values and fees are simply reported as bad requests. This includes issues such as melting the same coin twice in the same session, which is simply not allowed. However, theoretically it is possible to melt a coin twice, as long as the ``value_with_fee`` of the two melting operations is not larger than the total remaining value of the coin before the melting operations. Nevertheless, this is not really useful. :http:statuscode:`200 OK`: The transfer private keys matched the commitment and the original request was well-formed. The response body is a `RevealResponse`. :http:statuscode:`409 Conflict`: There is a problem between the original commitment and the revealed private keys. The returned information is proof of the mismatch, and therefore rather verbose, as it includes most of the original /refresh/melt request, but of course expected to be primarily used for diagnostics. The response body is a `RevealConflictResponse`. **Details:** Request body contains a JSON object with the following fields: .. ts:def:: RevealRequest interface RevealRequest { // Array of ``n`` new hash codes of denomination public keys to order. new_denoms_h: HashCode[]; // Array of ``n`` entries with blinded coins, // matching the respective entries in ``new_denoms``. coin_evs: CoinEnvelope[]; // ``kappa - 1`` transfer private keys (ephemeral ECDHE keys). transfer_privs: EddsaPrivateKey[]; // Transfer public key at the ``noreveal_index``. transfer_pub: EddsaPublicKey; // Array of ``n`` signatures made by the wallet using the old coin's private key, // used later to verify the /refresh/link response from the exchange. // Signs over a `TALER_CoinLinkSignaturePS`. link_sigs: EddsaSignature[]; } .. ts:def:: RevealResponse interface RevealResponse { // List of the exchange's blinded RSA signatures on the new coins. ev_sigs : Array<{ ev_sig: BlindedRsaSignature }>; } .. ts:def:: RevealConflictResponse interface RevealConflictResponse { // Text describing the error. hint: string; // Detailed error code. code: Integer; // Commitment as calculated by the exchange from the revealed data. rc_expected: HashCode; } .. http:get:: /coins/$COIN_PUB/link Link the old public key of a melted coin to the coin(s) that were exchanged during the refresh operation. **Request:** **Response:** :http:statuscode:`200 OK`: All commitments were revealed successfully. The exchange returns an array, typically consisting of only one element, in which each each element contains information about a melting session that the coin was used in. :http:statuscode:`404 Not found`: The exchange has no linkage data for the given public key, as the coin has not yet been involved in a refresh operation. **Details:** .. ts:def:: LinkResponse interface LinkResponse { // Transfer ECDHE public key corresponding to the ``coin_pub``, used to // compute the blinding factor and private key of the fresh coins. transfer_pub: EcdhePublicKey; // Array with (encrypted/blinded) information for each of the coins // exchangeed in the refresh operation. new_coins: NewCoinInfo[]; } .. ts:def:: NewCoinInfo interface NewCoinInfo { // RSA public key of the exchangeed coin. denom_pub: RsaPublicKey; // Exchange's blinded signature over the fresh coin. ev_sig: BlindedRsaSignature; // Blinded coin. coin_ev : CoinEnvelope; // Signature made by the old coin over the refresh request. // Signs over a `TALER_CoinLinkSignaturePS`. link_sig: EddsaSignature; } ------ Recoup ------ This API is only used if the exchange is either about to go out of business or has had its private signing keys compromised (so in either case, the protocol is only used in **abnormal** situations). In the above cases, the exchange signals to the wallets that the emergency cash back protocol has been activated by putting the affected denomination keys into the cash-back part of the ``/keys`` response. If and only if this has happened, coins that were signed with those denomination keys can be cashed in using this API. .. http:post:: /coins/$COIN_PUB/recoup Demand that a coin be refunded via wire transfer to the original owner. 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. Depending whether ``$COIN_PUB`` is a withdrawn coin or a refreshed coin, the remaining amount on the coin will be credited either on the reserve or the old coin that ``$COIN_PUB`` was withdrawn/refreshed from. Note that the original withdrawal/refresh fees will **not** be recouped. **Request:** The request body must be a `RecoupRequest` object. **Response:** :http:statuscode:`200 OK`: The request was successful, and the response is a `RecoupConfirmation`. 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:`401 Unauthorized`: The coin's signature is invalid. :http:statuscode:`404 Not found`: The denomination key is not in the set of denomination keys where emergency pay back is enabled, or the blinded coin is not known to have been withdrawn. :http:statuscode:`409 Conflict`: The operation is not allowed as 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_RECOUP_COIN_BALANCE_ZERO`` or ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``). The response is a `DepositDoubleSpendError`. **Details:** .. ts:def:: RecoupRequest interface RecoupRequest { // Hash of denomination public key (RSA), specifying the type of coin the client // would like the exchange to pay back. denom_pub_hash: HashCode; // Signature over the `coin public key ` by the denomination. denom_sig: RsaSignature; // Coin's blinding factor. coin_blind_key_secret: RsaBlindingKeySecret; // Signature of `TALER_RecoupRequestPS` created with // the `coin's private key `. coin_sig: EddsaSignature; // Was the coin refreshed (and thus the recoup should go to the old coin)? // While this information is technically redundant, it helps the exchange // to respond faster. // *Optional* (for backwards compatibility); if absent, ``false`` is assumed. refreshed?: boolean; } .. ts:def:: RecoupConfirmation type RecoupConfirmation = | RecoupRefreshConfirmation | RecoupWithdrawalConfirmation; .. ts:def:: RecoupWithdrawalConfirmation interface RecoupWithdrawalConfirmation { // Tag to distinguish the `RecoupConfirmation` response type. refreshed: false; // Public key of the reserve that will receive the recoup. reserve_pub: EddsaPublicKey; } .. ts:def:: RecoupRefreshConfirmation interface RecoupRefreshConfirmation { // Tag to distinguish the `RecoupConfirmation` response type. refreshed: true; // Public key of the old coin that will receive the recoup. old_coin_pub: EddsaPublicKey; } ----------------------- Tracking wire transfers ----------------------- This API is used by merchants that need to find out which wire transfers (from the exchange to the merchant) correspond to which deposit operations. Typically, a merchant will receive a wire transfer with a **wire transfer identifier** and want to know the set of deposit operations that correspond to this wire transfer. This is the preferred query that merchants should make for each wire transfer they receive. If a merchant needs to investigate a specific deposit operation (i.e. because it seems that it was not paid), then the merchant can also request the wire transfer identifier for a deposit operation. Sufficient information is returned to verify that the coin signatures are correct. This also allows governments to use this API when doing a tax audit on merchants. Naturally, the returned information may be sensitive for the merchant. We do not require the merchant to sign the request, as the same requests may also be performed by the government auditing a merchant. However, wire transfer identifiers should have sufficient entropy to ensure that obtaining a successful reply by brute-force is not practical. Nevertheless, the merchant should protect the wire transfer identifiers from his bank statements against unauthorized access, lest his income situation is revealed to an adversary. (This is not a major issue, as an adversary that has access to the line-items of bank statements can typically also view the balance.) .. http:get:: /transfers/$WTID Provides deposits associated with a given wire transfer. The wire transfer identifier (WTID) and the base URL for tracking the wire transfer are both given in the wire transfer subject. **Request:** **Response:** :http:statuscode:`200 OK`: The wire transfer is known to the exchange, details about it follow in the body. The body of the response is a `TrackTransferResponse`. :http:statuscode:`404 Not found`: The wire transfer identifier is unknown to the exchange. .. ts:def:: TrackTransferResponse interface TrackTransferResponse { // Actual amount of the wire transfer, excluding the wire fee. total: Amount; // Applicable wire fee that was charged. wire_fee: Amount; // Public key of the merchant (identical for all deposits). merchant_pub: EddsaPublicKey; // Hash of the wire details (identical for all deposits). h_wire: HashCode; // Time of the execution of the wire transfer by the exchange. execution_time: Timestamp; // Details about the deposits. deposits: TrackTransferDetail[]; // Signature from the exchange made with purpose // `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT`. 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 ``/keys``. Again given // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. exchange_pub: EddsaSignature; } .. ts:def:: TrackTransferDetail interface TrackTransferDetail { // SHA-512 hash of the contact of the merchant with the customer. h_contract_terms: HashCode; // Coin's public key, both ECDHE and EdDSA. coin_pub: CoinPublicKey; // The total amount the original deposit was worth. deposit_value: Amount; // Applicable fees for the deposit. deposit_fee: Amount; } .. http:get:: /deposits/$H_WIRE/$MERCHANT_PUB/$H_CONTRACT_TERMS/$COIN_PUB Provide the wire transfer identifier associated with an (existing) deposit operation. The arguments are the hash of the merchant's payment details (H_WIRE), the merchant's public key (EdDSA), the hash of the contract terms that were paid (H_CONTRACT_TERMS) and the public key of the coin used for the payment (COIN_PUB). **Request:** :query merchant_sig: EdDSA signature of the merchant made with purpose ``TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION``, affirming that it is really the merchant who requires obtaining the wire transfer identifier. **Response:** :http:statuscode:`200 OK`: The deposit has been executed by the exchange and we have a wire transfer identifier. The response body is a `TrackTransactionResponse` object. :http:statuscode:`202 Accepted`: The deposit request has been accepted for processing, but was not yet executed. Hence the exchange does not yet have a wire transfer identifier. The merchant should come back later and ask again. The response body is a `TrackTransactionAcceptedResponse`. :http:statuscode:`401 Unauthorized`: The signature is invalid. :http:statuscode:`404 Not found`: The deposit operation is unknown to the exchange. **Details:** .. ts:def:: TrackTransactionResponse interface TrackTransactionResponse { // Raw wire transfer identifier of the deposit. wtid: Base32; // When was the wire transfer given to the bank. execution_time: Timestamp; // The contribution of this coin to the total (without fees) coin_contribution: Amount; // Total amount transferred. total_amount: Amount; // Binary-only Signature_ for purpose `TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE` // whereby the exchange affirms the successful wire transfer. 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 /keys. Again given // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. exchange_pub: EddsaPublicKey; } .. ts:def:: TrackTransactionAcceptedResponse interface TrackTransactionAcceptedResponse { // Time by which the exchange currently thinks the deposit will be executed. execution_time: Timestamp; } .. _exchange_refund: ------- Refunds ------- .. http:POST:: /coins/$COIN_PUB/refund Undo deposit of the given coin, restoring its value. **Request:** The request body must be a `RefundRequest` object. **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object. :http:statuscode:`401 Unauthorized`: Merchant signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match). This response comes with a standard `ErrorDetail` response. :http:statuscode:`409 Conflict`: The exchange has previously received a refund request for the same coin, merchant and contract, but specifying a different amount for the same refund transaction ID. The response will be a `RefundFailure` object. :http:statuscode:`410 Gone`: It is too late for a refund by the exchange, the money was already sent to the merchant. This response comes with a standard `ErrorDetail` response. :http:statuscode:`412 Precondition failed`: The request transaction ID is identical to a previous refund request by the same merchant for the same coin and contract, but the refund amount differs. (The failed precondition is that the ``rtransaction_id`` is not unique.) The response will be a `RefundFailure` object with the conflicting refund request. **Details:** .. ts:def:: RefundRequest interface RefundRequest { // Amount to be refunded, can be a fraction of the // coin's total deposit value (including deposit fee); // must be larger than the refund fee. refund_amount: Amount; // SHA-512 hash of the contact of the merchant with the customer. h_contract_terms: HashCode; // 64-bit transaction id of the refund transaction between merchant and customer. rtransaction_id: Integer; // EdDSA public key of the merchant. merchant_pub: EddsaPublicKey; // EdDSA signature of the merchant affirming the refund. merchant_sig: EddsaPublicKey; } .. ts:def:: RefundSuccess interface RefundSuccess { // The EdDSA :ref:`signature` (binary-only) with purpose // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the // exchange affirming the successful refund. 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 ``/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; } .. ts:def:: RefundFailure interface RefundFailure { // Numeric error code unique to the condition, which can be either // related to the deposit value being insufficient for the requested // refund(s), or the requested refund conflicting due to refund // transaction number re-use (with different amounts). code: Integer; // Human-readable description of the error message. hint: string; // Information about the conflicting refund request(s). // This will not be the full history of the coin, but only // the relevant subset of the transactions. history: CoinSpendHistoryItem[]; } .. _exchange_w2w: -------------------------- Wallet-to-wallet transfers -------------------------- TODO for the spec: * add reserve history requests (with fee!) to reserve history (changes balance!) * specify new database schema at exchange (add SQL to DD13!) - something for in-progress kyc vs. completed kyc? => add kyc_date to reserves? => or have separate KYC table instead of NULLs in reserves! * update wire transfer API to enable WAD IDs (and while we are at it, should probably also write extended version to allow _merchants_ to query for their inbound transfers, so spec for both WADs and regular WTID!); also add flag to tell exchange for inbound wire transfers that they are from a partner bank where KYC fees would be waived! Discussion: * when the user POSTs to /kyc for a reserve with a payto URI that differs from the URI that was used to establish the reserve, do we 409 conflict or accept? That seems like an attack vector: Say I learn your account pub and wire you money from my bank account, thus blocking you from /kyc'ing your account!) * when the user POSTs to /kyc for an account with a payto URI that differs from the URI that was previously used for a /kyc for the same account, do we allow the KYC to proceed and update the bank account? Is there an attack vector? .. http:GET:: /purses/$PURSE_PUB Obtain information about a purse. The request header must contain a *Purse-Request-Signature*. Endpoint used by the party that did not create the purse. **Request:** *Purse-Request-Signature*: The client must provide Base-32 encoded EdDSA signature made with ``$PURSE_PRIV``, affirming its authorization to download the purse status. The purpose used MUST be ``TALER_SIGNATURE_PURSE_STATUS_REQUEST``. :query merge_timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds for completion of a merge operation before sending the HTTP response. :query deposit_timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds for completion of a deposit operation before sending the HTTP response. :query contract=BOOLEAN: *Optional.* If 'false' is specified, the exchange will not return the encrypted contract, saving bandwidth for clients that already know it. **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange provides details about the purse. The response will include a `PurseStatus` object. :http:statuscode:`401 Unauthorized`: The *Purse-Request-Signature* is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The purse is unknown to the exchange. **Details:** .. ts:def:: PurseStatus interface PurseStatus { // Total amount that must be paid into the purse. total_purse_amount: Amount; // Total amount deposited into the purse so far. total_deposit_amount: Amount; // Indicative time by which the purse expires // if it has not been merged into an account. At this // point, all of the deposits made will be auto-refunded. purse_expiration: Timestamp; // Indicative time at which the exchange is answering the // status request. Used as part of `exchange_sig`. status_timestamp: Timestamp; // Maximum deposit fees that can be charged under the contract. max_deposit_fees: Amount; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; // EdDSA signature of the exchange affirming the purse status. exchange_sig: EddsaSignature; // EdDSA public key exchange used for exchange_sig. exchange_pub: EddsaPublicKey; // AES-GCM Encrypted contract terms using encryption // key derived from DH of 'contract_pub' and the 'purse_pub'. // Optional, may be omitted if not desired by the client. e_contract_terms?: byte[]; // If a merge request was received, information about the // merge request. Omitted if the purse has not yet received // a merge request. merge_request?: MergeRequest; } .. http:POST:: /purses/$PURSE_PUB/deposit Deposit money into a purse. Endpoint used by the buyer. **Request:** The request body must be a `PurseRequest` object. **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that all coins were deposited into the purse. The response will include a `PursePaymentSuccess` object. :http:statuscode:`202 Accepted`: The payment was accepted, but insufficient to reach the specified purse balance. The client should make further purse deposits before the expiration deadline. The response will include a `PursePaymentAccepted` object. :http:statuscode:`401 Unauthorized`: A coin signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`403 Forbidden`: The server is denying the operation as a purse with a different contract or total amount already exists. This response comes with a standard `PurseConflict` response. :http:statuscode:`404 Not found`: Either the denomination key is not recognized (expired or invalid) or the wire type is not recognized. :http:statuscode:`409 Conflict`: The deposit operation has either failed because a 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_DEPOSIT_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 `PurseDepositDoubleSpendError`. If the value of all successful coins is below the purse fee, the exchange may not setup the purse at all. **Details:** .. ts:def:: PurseRequest interface PurseRequest { // EdDSA signature of the purse confirming the key // invariants associated with the purse. // (amount, h_contract_terms, expiration). purse_sig: EddsaSignature; // Total amount to be paid into the purse. // Clients may make several requests, i.e. if a // first request failed with a double-spending error. // The exchange will confirm the creation of the // purse once the amount given here is reached. total_purse_amount: Amount; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; // Client-side timestamp of when the payment was made. payment_timestamp: Timestamp; // 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 will be auto-refunded. purse_expiration: Timestamp; // Optional encrypted contract, in case the buyer is // proposing the contract and thus establishing the // purse with the payment. contract?: EncryptedContract; // Array of coins being deposited into the purse. deposits: PurseDeposit[]; } .. ts:def:: EncryptedContract { // ECDH contract_public key used to encrypt the contract. // Optional as the contract terms may already be known // to the exchange or the other wallet from a different // interaction. contract_pub: EcdhPublicKey; // AES-GCM Encrypted contract terms using encryption // key derived from DH of 'contract_pub' and the 'purse_pub'. // Optional as the contract terms may already be known // to the exchange or the other wallet from a different // interaction. e_contract_terms: byte[]; } .. ts:def:: PurseDeposit { // Public key of the coin being deposited into the purse. coin_pub: EddsaPublicKey; // Amount to be deposited, can be a fraction of the // coin's total value. contribution: Amount; // Hash of denomination RSA key with which the coin is signed. denom_pub_hash: HashCode; // Exchange's unblinded RSA signature of the coin. ub_sig: RsaSignature; // Signature of `TALER_PurseDepositRequestPS`, // made by the customer with the // `coin's private key `. coin_sig: EddsaSignature; } .. ts:def:: PursePaymentSuccess interface PursePaymentSuccess { // Total amount paid into the purse. total_purse_amount: Amount; // Total deposit fees charged. total_deposit_fees: Amount; // EdDSA signature of the exchange affirming the payment, // of purpose TALER_SIGNATURE_PURSE_PAYMENT_CONFIRMED // Signs over the above and the purse public key and // the hash of the contract terms. exchange_sig: EddsaSignature; // public key used to create the signature. exchange_pub: EddsaPublicKey; } .. ts:def:: PursePaymentAccepted interface PursePaymentAccepted { // Total amount paid so far into the purse, in this // and previous requests. total_amount_deposited: Amount; // Total amount contributed by the current request. total_amount_contributed: Amount; } .. ts:def:: PurseConflict interface PurseConflict { // Total amount to be paid into the purse as per // the previous request. total_purse_amount: Amount; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; // 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; // EdDSA signature of the purse confirming that the // above details hold for this purse. purse_sig: EddsaSignature; } .. ts:def:: PurseDepositDoubleSpendError interface DepositDoubleSpendError { // Taler error code. code: number; // Human-readable description of the error, i.e. "insufficient funds". hint?: string; // Total amount contributed by the current request. // Note that some coins may have been successfully // deposited into the purse, so the total amount // from these coins is listed here. total_amount_contributed: Amount; // Public keys of coins that could not be deposited // into the purse, mapped to the coin's histories. coin_map: EddsaPublicKey -> CoinSpendHistoryItem[]; } .. 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 seller. **Request:** The request body must be a `MergeRequest` object. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds to receive payment before reporting on the completion of merge operation. Basically forstalls returning a 202 response for up to timeout milliseconds to possibly return a 200 response instead. **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that the funds were merged into the account. The response will include a `MergeSuccess` object. :http:statuscode:`202 Accepted`: The operation succeeded, the exchange confirms that the merge request is valid. Alas, the purse was still not funded and thus the actual merge is delayed. The response will include a `MergeAccepted` object. :http:statuscode:`401 Unauthorized`: Account signature is invalid. This response comes with a standard `ErrorDetail` response. :http:statuscode:`404 Not found`: The refund operation failed as we could not find the purse. This response comes with a standard `ErrorDetail` response. :http:statuscode:`410 Gone`: The purse has already expired and thus can no longer be merged. This response comes with a standard `ErrorDetail` response. :http:statuscode:`429 Too Many Requests`: This account is not at this exchange, has not yet passed the KYC checks, or it has exceeded the number of open purses. The client must include payment to create another purse or wait until existing purses have expired. **Details:** .. ts:def:: MergeRequest interface MergeRequest { // payto://-URI of the account the purse is to be merged into. // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB". payto_uri: string; // EdDSA signature of the account/reserve affirming the merge. // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE reserve_sig: EddsaSignature; // EdDSA signature of the purse private key affirming the merge. // Must be of purpose TALER_SIGNATURE_PURSE_MERGE. purse_sig: EddsaSignature; // Minimum amount that must be credited to the reserve, that is // the total value of the purse minus the deposit fees. // If the deposit fees are lower, the contribution to the // reserve can be higher! minimum_amount_contributed: Amount; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; // Client-side timestamp of when the merge request was made. merge_timestamp: Timestamp; // Indicative time by which the purse should expire // if it has not been paid. purse_expiration: Timestamp; // Optional encrypted contract, in case the seller is // proposing the contract and thus establishing the // purse with the payment. contract?: EncryptedContract; // Array of payments made to pay for the creation of the // purse. Can be empty, say if no payment is needed. payments: CreatePurseDeposit[]; } .. ts:def:: CreatePurseDeposit { // Public key of the coin being used to pay for creating a purse. coin_pub: EddsaPublicKey; // Amount to be deposited, can be a fraction of the // coin's total value. contribution: Amount; // Hash of denomination RSA key with which the coin is signed. denom_pub_hash: HashCode; // Exchange's unblinded RSA signature of the coin. ub_sig: RsaSignature; // Signature of purpose TALER_SIGNATURE_PURSE_PAYMENT. // made by the customer with the // `coin's private key `. coin_sig: EddsaSignature; } .. ts:def:: MergeSuccess interface MergeSuccess { // Amount merged (excluding deposit fees). merge_amount: Amount; // SHA-512 hash of the contact of the purse. h_contract_terms: HashCode; // Time at which the merge came into effect. // Maximum of the "payment_timestamp" and the // "merge_timestamp". contract_time: Timestamp; // EdDSA signature of the exchange affirming the merge of // purpose TALER_SIGNATURE_PURSE_MERGE_SUCCESS. // Signs over the above and the account public key. exchange_sig: EddsaSignature; // public key used to create the signature. exchange_pub: EddsaPublicKey; } .. ts:def:: MergeAccepted interface MergeAccepted { // The number of remaining purses that can still be opened // under the given account. remaining_purses: integer; } .. http:POST:: /reserves/$RESERVE_PUB/kyc Upgrade a reserve to an *account*. The reserve must (from wire transfers or merges of purses) already have a sufficient balance to cover the KYC fee. The signature affirms that the KYC fee can and should be charged to the reserve. **Request:** The request body must be a `AccountSetupRequest` object. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds for the KYC gateway to confirm completion of the KYC process. **Response:** :http:statuscode:`200 Ok`: The operation succeeded, the exchange confirms that the account can now be used. The response will be an `AccountStatus` 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 request should be repeated. The response will be an `AccountKycRedirect` object. :http:statuscode:`409 Conflict`: The reserve or account was previously associated with a different payto URI, and changing the associated bank account is not permitted. FIXME: should we allow it? Should we use PATCH for this? Or only conflict if this was an account and not a reserve!?? :http:statuscode:`504 Gateway Timeout`: The exchange did not receive a confirmation from the KYC service within the specified time period. Used when long-polling for the result. **Details:** .. ts:def:: AccountSetupRequest interface AccountSetupRequest { // Time of the request to perform the KYC. Determines // the KYC fee charged by the exchange. Must be // reasonably close to the current time of the exchange. kyc_timestamp: Timestamp; // Bank account to be associated with the account. // Can be ``payto://void/`` to not associate the // account with any bank account. In this case, // closing the account will result in the balance // being forfeit. If the provided wire method is // not supported by the exchange *and* not ``void``, // this is a ``Bad Request`` (HTTP status 400). payto_uri: string; // EdDSA signature of the reserve affirming the request // to create the account, must be of purpose // TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST reserve_sig: EddsaPublicKey; } .. ts:def:: AccountKycStatus interface AccountKycStatus { // Current time of the exchange, used as part of // what the exchange signs over. now: Timestamp; // EdDSA signature of the exchange affirming the account // is KYC'ed, must be of purpose // TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS. exchange_sig: EddsaSignature; // public key used to create the signature. exchange_pub: EddsaPublicKey; } .. ts:def:: AccountKycRedirect interface AccountKycRedirect { // URL that the user should open in a browser to // proceed with the KYC process. kyc_url: string; } .. _exchange_wads: Wads ^^^^ 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 Obtain information about a wad. **Request:** **Response:** :http:statuscode:`200 OK`: The operation succeeded, the exchange provides details about the wad. The response will include a `WadDetails` object. :http:statuscode:`404 Not found`: The wad is unknown to the exchange. **Details:** .. ts:def:: WadDetails interface WadDetails { // Total transfer amount claimed by the exchange. total: Amount; // Transfers aggregated in the wad. items: WadItem[]; // EdDSA signature of the exchange affirming the wad // data is correct, must be of purpose // TALER_SIGNATURE_WAD_DATA. exchange_sig: EddsaSignature; // public key used to create the signature. exchange_pub: EddsaPublicKey; } Objects in the wad item list have the following format: .. ts:def:: WadItem interface WadItem { // Amount in the purse. amount: Amount; // payto://-URI of the account the purse is to be merged into. // Must be of the form: "payto://taler/EXCHANGE_URL/RESERVE_PUB". payto_uri: string; // Purse public key. purse_pub: EddsaPublicKey; // Hash of the contract. h_contract: HashCode; // Indicative time by which the purse should expire // if it has not been paid. purse_expiration: Timestamp; // Client-side timestamp of when the merge request was made. merge_timestamp: Timestamp; // Signature created with the reserve's private key. // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE reserve_sig: EddsaSignature; // Signature created with the purse's private key. // Must be of purpose TALER_SIGNATURE_PURSE_MERGE purse_sig: EddsaSignature; // Deposit fees that were charged to the purse. deposit_fees: Amount; // Wad fees that was charged to the purse. wad_fees: Amount; }