diff options
| author | Sebastian <sebasjm@gmail.com> | 2022-12-19 12:23:39 -0300 |
|---|---|---|
| committer | Sebastian <sebasjm@gmail.com> | 2022-12-19 12:23:39 -0300 |
| commit | 72b429321553841ac1ff48cf974bfc65da01bb06 (patch) | |
| tree | 7db9a4462f02de6cb86de695a1e64772b00ead5f /packages/merchant-backoffice-ui/src/declaration.d.ts | |
| parent | 770ab6f01dc81a16f384f314982bd761540f8e65 (diff) | |
| download | wallet-core-72b429321553841ac1ff48cf974bfc65da01bb06.tar.xz | |
pretty
Diffstat (limited to 'packages/merchant-backoffice-ui/src/declaration.d.ts')
| -rw-r--r-- | packages/merchant-backoffice-ui/src/declaration.d.ts | 2338 |
1 files changed, 1148 insertions, 1190 deletions
diff --git a/packages/merchant-backoffice-ui/src/declaration.d.ts b/packages/merchant-backoffice-ui/src/declaration.d.ts index 7737c2cbc..75bc66201 100644 --- a/packages/merchant-backoffice-ui/src/declaration.d.ts +++ b/packages/merchant-backoffice-ui/src/declaration.d.ts @@ -15,10 +15,9 @@ */ /** -* -* @author Sebastian Javier Marchano (sebasjm) -*/ - + * + * @author Sebastian Javier Marchano (sebasjm) + */ type HashCode = string; type EddsaPublicKey = string; @@ -28,21 +27,21 @@ type RelativeTime = Duration; type ImageDataUrl = string; export interface WithId { - id: string + id: string; } interface Timestamp { - // Milliseconds since epoch, or the special - // value "forever" to represent an event that will - // never happen. - t_s: number | "never"; + // Milliseconds since epoch, or the special + // value "forever" to represent an event that will + // never happen. + t_s: number | "never"; } interface Duration { - d_us: number | "forever"; + d_us: number | "forever"; } interface WithId { - id: string; + id: string; } type Amount = string; @@ -50,1394 +49,1353 @@ type UUID = string; type Integer = number; export namespace ExchangeBackend { - 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 }; - } - 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; - } - 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; - } - + 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 }; + } + 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; + } + 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; + } } export namespace MerchantBackend { - interface ErrorDetail { - - // Numeric error code unique to the condition. - // The other arguments are specific to the error value reported here. - code: number; + interface ErrorDetail { + // Numeric error code unique to the condition. + // The other arguments are specific to the error value reported here. + code: number; - // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ... - // Should give a human-readable hint about the error's nature. Optional, may change without notice! - hint?: string; + // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ... + // Should give a human-readable hint about the error's nature. Optional, may change without notice! + hint?: string; - // Optional detail about the specific input value that failed. May change without notice! - detail?: string; + // Optional detail about the specific input value that failed. May change without notice! + detail?: string; - // Name of the parameter that was bogus (if applicable). - parameter?: string; + // Name of the parameter that was bogus (if applicable). + parameter?: string; - // Path to the argument that was bogus (if applicable). - path?: string; + // Path to the argument that was bogus (if applicable). + path?: string; - // Offset of the argument that was bogus (if applicable). - offset?: string; + // Offset of the argument that was bogus (if applicable). + offset?: string; - // Index of the argument that was bogus (if applicable). - index?: string; + // Index of the argument that was bogus (if applicable). + index?: string; - // Name of the object that was bogus (if applicable). - object?: string; + // Name of the object that was bogus (if applicable). + object?: string; - // Name of the currency than was problematic (if applicable). - currency?: string; + // Name of the currency than was problematic (if applicable). + currency?: string; - // Expected type (if applicable). - type_expected?: string; - - // Type that was provided instead (if applicable). - type_actual?: string; - } + // Expected type (if applicable). + type_expected?: string; + // Type that was provided instead (if applicable). + type_actual?: string; + } - // Delivery location, loosely modeled as a subset of - // ISO20022's PostalAddress25. - interface Tax { - // the name of the tax - name: string; + // Delivery location, loosely modeled as a subset of + // ISO20022's PostalAddress25. + interface Tax { + // the name of the tax + name: string; - // amount paid in tax - tax: Amount; - } + // amount paid in tax + tax: Amount; + } - interface Auditor { - // official name - name: string; + interface Auditor { + // official name + name: string; - // Auditor's public key - auditor_pub: EddsaPublicKey; + // Auditor's public key + auditor_pub: EddsaPublicKey; - // Base URL of the auditor - url: string; - } - interface Exchange { - // the exchange's base URL - url: string; + // Base URL of the auditor + url: string; + } + interface Exchange { + // the exchange's base URL + url: string; - // master public key of the exchange - master_pub: EddsaPublicKey; - } + // master public key of the exchange + master_pub: EddsaPublicKey; + } - interface Product { - // merchant-internal identifier for the product. - product_id?: string; + interface Product { + // merchant-internal identifier for the product. + product_id?: string; + + // Human-readable product description. + description: string; + + // Map from IETF BCP 47 language tags to localized descriptions + description_i18n?: { [lang_tag: string]: string }; + + // The number of units of the product to deliver to the customer. + quantity: Integer; + + // The unit in which the product is measured (liters, kilograms, packages, etc.) + unit: string; + + // The price of the product; this is the total price for quantity times unit of this product. + price?: Amount; + + // An optional base64-encoded product image + image: ImageDataUrl; + + // a list of taxes paid by the merchant for this product. Can be empty. + taxes: Tax[]; + + // time indicating when this product should be delivered + delivery_date?: TalerProtocolTimestamp; + + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } + interface Merchant { + // label for a location with the business address of the merchant + address: Location; + + // the merchant's legal name of business + name: string; - // Human-readable product description. - description: string; + // label for a location that denotes the jurisdiction for disputes. + // Some of the typical fields for a location (such as a street address) may be absent. + jurisdiction: Location; + } - // Map from IETF BCP 47 language tags to localized descriptions - description_i18n?: { [lang_tag: string]: string }; + interface VersionResponse { + // libtool-style representation of the Merchant protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Name of the protocol. + name: "taler-merchant"; + + // Currency supported by this backend. + currency: string; + } + interface Location { + // Nation with its own government. + country?: string; + + // Identifies a subdivision of a country such as state, region, county. + country_subdivision?: string; + + // Identifies a subdivision within a country sub-division. + district?: string; + + // Name of a built-up area, with defined boundaries, and a local government. + town?: string; + + // Specific location name within the town. + town_location?: string; + + // Identifier consisting of a group of letters and/or numbers that + // is added to a postal address to assist the sorting of mail. + post_code?: string; + + // Name of a street or thoroughfare. + street?: string; + + // Name of the building or house. + building_name?: string; + + // Number that identifies the position of a building on a street. + building_number?: string; + + // Free-form address lines, should not exceed 7 elements. + address_lines?: string[]; + } + namespace Instances { + //POST /private/instances/$INSTANCE/auth + interface InstanceAuthConfigurationMessage { + // Type of authentication. + // "external": The mechant backend does not do + // any authentication checks. Instead an API + // gateway must do the authentication. + // "token": The merchant checks an auth token. + // See "token" for details. + method: "external" | "token"; + + // For method "external", this field is mandatory. + // The token MUST begin with the string "secret-token:". + // After the auth token has been set (with method "token"), + // the value must be provided in a "Authorization: Bearer $token" + // header. + token?: string; + } + //POST /private/instances + interface InstanceConfigurationMessage { + // The URI where the wallet will send coins. A merchant may have + // multiple accounts, thus this is an array. Note that by + // removing URIs from this list the respective account is set to + // inactive and thus unavailable for new contracts, but preserved + // in the database as existing offers and contracts may still refer + // to it. + payto_uris: string[]; + + // Name of the merchant instance to create (will become $INSTANCE). + id: string; + + // Merchant name corresponding to this instance. + name: string; + + email: string; + website: string; + // An optional base64-encoded logo image + logo: ImageDataUrl; + + // "Authentication" header required to authorize management access the instance. + // Optional, if not given authentication will be disabled for + // this instance (hopefully authentication checks are still + // done by some reverse proxy). + auth: InstanceAuthConfigurationMessage; + + // The merchant's physical address (to be put into contracts). + address: Location; + + // The jurisdiction under which the merchant conducts its business + // (to be put into contracts). + jurisdiction: Location; + + // Maximum wire fee this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_wire_fee: Amount; + + // Default factor for wire fee amortization calculations. + // Can be overridden by the frontend on a per-order basis. + default_wire_fee_amortization: Integer; + + // Maximum deposit fee (sum over all coins) this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_deposit_fee: Amount; + + // If the frontend does NOT specify an execution date, how long should + // we tell the exchange to wait to aggregate transactions before + // executing the wire transfer? This delay is added to the current + // time when we generate the advisory execution time for the exchange. + default_wire_transfer_delay: RelativeTime; + + // If the frontend does NOT specify a payment deadline, how long should + // offers we make be valid by default? + default_pay_delay: RelativeTime; + } - // The number of units of the product to deliver to the customer. - quantity: Integer; + // PATCH /private/instances/$INSTANCE + interface InstanceReconfigurationMessage { + // The URI where the wallet will send coins. A merchant may have + // multiple accounts, thus this is an array. Note that by + // removing URIs from this list + payto_uris: string[]; - // The unit in which the product is measured (liters, kilograms, packages, etc.) - unit: string; + // Merchant name corresponding to this instance. + name: string; - // The price of the product; this is the total price for quantity times unit of this product. - price?: Amount; + // The merchant's physical address (to be put into contracts). + address: Location; - // An optional base64-encoded product image - image: ImageDataUrl; + // The jurisdiction under which the merchant conducts its business + // (to be put into contracts). + jurisdiction: Location; - // a list of taxes paid by the merchant for this product. Can be empty. - taxes: Tax[]; + // Maximum wire fee this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_wire_fee: Amount; - // time indicating when this product should be delivered - delivery_date?: TalerProtocolTimestamp; + // Default factor for wire fee amortization calculations. + // Can be overridden by the frontend on a per-order basis. + default_wire_fee_amortization: Integer; - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; - } - interface Merchant { - // label for a location with the business address of the merchant - address: Location; + // Maximum deposit fee (sum over all coins) this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_deposit_fee: Amount; - // the merchant's legal name of business - name: string; + // If the frontend does NOT specify an execution date, how long should + // we tell the exchange to wait to aggregate transactions before + // executing the wire transfer? This delay is added to the current + // time when we generate the advisory execution time for the exchange. + default_wire_transfer_delay: RelativeTime; - // label for a location that denotes the jurisdiction for disputes. - // Some of the typical fields for a location (such as a street address) may be absent. - jurisdiction: Location; + // If the frontend does NOT specify a payment deadline, how long should + // offers we make be valid by default? + default_pay_delay: RelativeTime; } - interface VersionResponse { - // libtool-style representation of the Merchant protocol version, see - // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning - // The format is "current:revision:age". - version: string; - - // Name of the protocol. - name: "taler-merchant"; - - // Currency supported by this backend. - currency: string; - + // GET /private/instances + interface InstancesResponse { + // List of instances that are present in the backend (see Instance) + instances: Instance[]; } - interface Location { - // Nation with its own government. - country?: string; - // Identifies a subdivision of a country such as state, region, county. - country_subdivision?: string; + interface Instance { + // Merchant name corresponding to this instance. + name: string; - // Identifies a subdivision within a country sub-division. - district?: string; + deleted?: boolean; - // Name of a built-up area, with defined boundaries, and a local government. - town?: string; + // Merchant instance this response is about ($INSTANCE) + id: string; - // Specific location name within the town. - town_location?: string; + // Public key of the merchant/instance, in Crockford Base32 encoding. + merchant_pub: EddsaPublicKey; - // Identifier consisting of a group of letters and/or numbers that - // is added to a postal address to assist the sorting of mail. - post_code?: string; + // List of the payment targets supported by this instance. Clients can + // specify the desired payment target in /order requests. Note that + // front-ends do not have to support wallets selecting payment targets. + payment_targets: string[]; + } - // Name of a street or thoroughfare. - street?: string; + //GET /private/instances/$INSTANCE/kyc + interface AccountKycRedirects { + // Array of pending KYCs. + pending_kycs: MerchantAccountKycRedirect[]; - // Name of the building or house. - building_name?: string; + // Array of exchanges with no reply. + timeout_kycs: ExchangeKycTimeout[]; + } + interface MerchantAccountKycRedirect { + // URL that the user should open in a browser to + // proceed with the KYC process (as returned + // by the exchange's /kyc-check/ endpoint). + kyc_url: string; - // Number that identifies the position of a building on a street. - building_number?: string; + // Base URL of the exchange this is about. + exchange_url: string; - // Free-form address lines, should not exceed 7 elements. - address_lines?: string[]; + // Our bank wire account this is about. + payto_uri: string; + } + interface ExchangeKycTimeout { + // Base URL of the exchange this is about. + exchange_url: string; + + // Numeric error code indicating errors the exchange + // returned, or TALER_EC_INVALID for none. + exchange_code: number; + + // HTTP status code returned by the exchange when we asked for + // information about the KYC status. + // 0 if there was no response at all. + exchange_http_status: number; } - namespace Instances { - - //POST /private/instances/$INSTANCE/auth - interface InstanceAuthConfigurationMessage { - // Type of authentication. - // "external": The mechant backend does not do - // any authentication checks. Instead an API - // gateway must do the authentication. - // "token": The merchant checks an auth token. - // See "token" for details. - method: "external" | "token"; - - // For method "external", this field is mandatory. - // The token MUST begin with the string "secret-token:". - // After the auth token has been set (with method "token"), - // the value must be provided in a "Authorization: Bearer $token" - // header. - token?: string; - - } - //POST /private/instances - interface InstanceConfigurationMessage { - // The URI where the wallet will send coins. A merchant may have - // multiple accounts, thus this is an array. Note that by - // removing URIs from this list the respective account is set to - // inactive and thus unavailable for new contracts, but preserved - // in the database as existing offers and contracts may still refer - // to it. - payto_uris: string[]; - - // Name of the merchant instance to create (will become $INSTANCE). - id: string; - - // Merchant name corresponding to this instance. - name: string; - - email: string; - website: string; - // An optional base64-encoded logo image - logo: ImageDataUrl; - - - // "Authentication" header required to authorize management access the instance. - // Optional, if not given authentication will be disabled for - // this instance (hopefully authentication checks are still - // done by some reverse proxy). - auth: InstanceAuthConfigurationMessage; - - // The merchant's physical address (to be put into contracts). - address: Location; - - // The jurisdiction under which the merchant conducts its business - // (to be put into contracts). - jurisdiction: Location; - - // Maximum wire fee this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_wire_fee: Amount; - - // Default factor for wire fee amortization calculations. - // Can be overridden by the frontend on a per-order basis. - default_wire_fee_amortization: Integer; - - // Maximum deposit fee (sum over all coins) this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_deposit_fee: Amount; - - // If the frontend does NOT specify an execution date, how long should - // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. - default_wire_transfer_delay: RelativeTime; - - // If the frontend does NOT specify a payment deadline, how long should - // offers we make be valid by default? - default_pay_delay: RelativeTime; - - } - - // PATCH /private/instances/$INSTANCE - interface InstanceReconfigurationMessage { - // The URI where the wallet will send coins. A merchant may have - // multiple accounts, thus this is an array. Note that by - // removing URIs from this list - payto_uris: string[]; - - // Merchant name corresponding to this instance. - name: string; - - // The merchant's physical address (to be put into contracts). - address: Location; - - // The jurisdiction under which the merchant conducts its business - // (to be put into contracts). - jurisdiction: Location; - - // Maximum wire fee this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_wire_fee: Amount; - - // Default factor for wire fee amortization calculations. - // Can be overridden by the frontend on a per-order basis. - default_wire_fee_amortization: Integer; - - // Maximum deposit fee (sum over all coins) this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_deposit_fee: Amount; - // If the frontend does NOT specify an execution date, how long should - // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. - default_wire_transfer_delay: RelativeTime; + //GET /private/instances/$INSTANCE + interface QueryInstancesResponse { + // The URI where the wallet will send coins. A merchant may have + // multiple accounts, thus this is an array. + accounts: MerchantAccount[]; + + // Merchant name corresponding to this instance. + name: string; + + // Public key of the merchant/instance, in Crockford Base32 encoding. + merchant_pub: EddsaPublicKey; + + // The merchant's physical address (to be put into contracts). + address: Location; + + // The jurisdiction under which the merchant conducts its business + // (to be put into contracts). + jurisdiction: Location; + + // Maximum wire fee this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_wire_fee: Amount; + + // Default factor for wire fee amortization calculations. + // Can be overridden by the frontend on a per-order basis. + default_wire_fee_amortization: Integer; + + // Maximum deposit fee (sum over all coins) this instance is willing to pay. + // Can be overridden by the frontend on a per-order basis. + default_max_deposit_fee: Amount; + + // If the frontend does NOT specify an execution date, how long should + // we tell the exchange to wait to aggregate transactions before + // executing the wire transfer? This delay is added to the current + // time when we generate the advisory execution time for the exchange. + default_wire_transfer_delay: RelativeTime; + + // If the frontend does NOT specify a payment deadline, how long should + // offers we make be valid by default? + default_pay_delay: RelativeTime; + + // Authentication configuration. + // Does not contain the token when token auth is configured. + auth: { + method: "external" | "token"; + token?: string; + }; + } - // If the frontend does NOT specify a payment deadline, how long should - // offers we make be valid by default? - default_pay_delay: RelativeTime; + interface MerchantAccount { + // payto:// URI of the account. + payto_uri: string; - } + // Hash over the wire details (including over the salt) + h_wire: HashCode; - // GET /private/instances - interface InstancesResponse { - // List of instances that are present in the backend (see Instance) - instances: Instance[]; - } + // salt used to compute h_wire + salt: HashCode; - interface Instance { - // Merchant name corresponding to this instance. - name: string; + // true if this account is active, + // false if it is historic. + active: boolean; + } - deleted?: boolean; + // DELETE /private/instances/$INSTANCE + } - // Merchant instance this response is about ($INSTANCE) - id: string; + namespace Products { + // POST /private/products + interface ProductAddDetail { + // product ID to use. + product_id: string; - // Public key of the merchant/instance, in Crockford Base32 encoding. - merchant_pub: EddsaPublicKey; + // Human-readable product description. + description: string; - // List of the payment targets supported by this instance. Clients can - // specify the desired payment target in /order requests. Note that - // front-ends do not have to support wallets selecting payment targets. - payment_targets: string[]; + // Map from IETF BCP 47 language tags to localized descriptions + description_i18n: { [lang_tag: string]: string }; - } + // unit in which the product is measured (liters, kilograms, packages, etc.) + unit: string; - //GET /private/instances/$INSTANCE/kyc - interface AccountKycRedirects { - // Array of pending KYCs. - pending_kycs: MerchantAccountKycRedirect[]; + // The price for one unit of the product. Zero is used + // to imply that this product is not sold separately, or + // that the price is not fixed, and must be supplied by the + // front-end. If non-zero, this price MUST include applicable + // taxes. + price: Amount; - // Array of exchanges with no reply. - timeout_kycs: ExchangeKycTimeout[]; + // An optional base64-encoded product image + image: ImageDataUrl; - } - interface MerchantAccountKycRedirect { + // a list of taxes paid by the merchant for one unit of this product + taxes: Tax[]; - // URL that the user should open in a browser to - // proceed with the KYC process (as returned - // by the exchange's /kyc-check/ endpoint). - kyc_url: string; + // Number of units of the product in stock in sum in total, + // including all existing sales ever. Given in product-specific + // units. + // A value of -1 indicates "infinite" (i.e. for "electronic" books). + total_stock: Integer; - // Base URL of the exchange this is about. - exchange_url: string; + // Identifies where the product is in stock. + address: Location; - // Our bank wire account this is about. - payto_uri: string; + // Identifies when we expect the next restocking to happen. + next_restock?: Timestamp; - } - interface ExchangeKycTimeout { + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } + // PATCH /private/products/$PRODUCT_ID + interface ProductPatchDetail { + // Human-readable product description. + description: string; - // Base URL of the exchange this is about. - exchange_url: string; + // Map from IETF BCP 47 language tags to localized descriptions + description_i18n: { [lang_tag: string]: string }; - // Numeric error code indicating errors the exchange - // returned, or TALER_EC_INVALID for none. - exchange_code: number; + // unit in which the product is measured (liters, kilograms, packages, etc.) + unit: string; - // HTTP status code returned by the exchange when we asked for - // information about the KYC status. - // 0 if there was no response at all. - exchange_http_status: number; + // The price for one unit of the product. Zero is used + // to imply that this product is not sold separately, or + // that the price is not fixed, and must be supplied by the + // front-end. If non-zero, this price MUST include applicable + // taxes. + price: Amount; - } + // An optional base64-encoded product image + image: ImageDataUrl; - //GET /private/instances/$INSTANCE - interface QueryInstancesResponse { - // The URI where the wallet will send coins. A merchant may have - // multiple accounts, thus this is an array. - accounts: MerchantAccount[]; + // a list of taxes paid by the merchant for one unit of this product + taxes: Tax[]; - // Merchant name corresponding to this instance. - name: string; + // Number of units of the product in stock in sum in total, + // including all existing sales ever. Given in product-specific + // units. + // A value of -1 indicates "infinite" (i.e. for "electronic" books). + total_stock: Integer; - // Public key of the merchant/instance, in Crockford Base32 encoding. - merchant_pub: EddsaPublicKey; + // Number of units of the product that were lost (spoiled, stolen, etc.) + total_lost: Integer; - // The merchant's physical address (to be put into contracts). - address: Location; + // Identifies where the product is in stock. + address: Location; - // The jurisdiction under which the merchant conducts its business - // (to be put into contracts). - jurisdiction: Location; + // Identifies when we expect the next restocking to happen. + next_restock?: Timestamp; - // Maximum wire fee this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_wire_fee: Amount; + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } - // Default factor for wire fee amortization calculations. - // Can be overridden by the frontend on a per-order basis. - default_wire_fee_amortization: Integer; + // GET /private/products + interface InventorySummaryResponse { + // List of products that are present in the inventory + products: InventoryEntry[]; + } + interface InventoryEntry { + // Product identifier, as found in the product. + product_id: string; + } - // Maximum deposit fee (sum over all coins) this instance is willing to pay. - // Can be overridden by the frontend on a per-order basis. - default_max_deposit_fee: Amount; + // GET /private/products/$PRODUCT_ID + interface ProductDetail { + // Human-readable product description. + description: string; - // If the frontend does NOT specify an execution date, how long should - // we tell the exchange to wait to aggregate transactions before - // executing the wire transfer? This delay is added to the current - // time when we generate the advisory execution time for the exchange. - default_wire_transfer_delay: RelativeTime; + // Map from IETF BCP 47 language tags to localized descriptions + description_i18n: { [lang_tag: string]: string }; - // If the frontend does NOT specify a payment deadline, how long should - // offers we make be valid by default? - default_pay_delay: RelativeTime; + // unit in which the product is measured (liters, kilograms, packages, etc.) + unit: string; - // Authentication configuration. - // Does not contain the token when token auth is configured. - auth: { - method: "external" | "token"; - token?: string; - }; - } + // The price for one unit of the product. Zero is used + // to imply that this product is not sold separately, or + // that the price is not fixed, and must be supplied by the + // front-end. If non-zero, this price MUST include applicable + // taxes. + price: Amount; - interface MerchantAccount { + // An optional base64-encoded product image + image: ImageDataUrl; - // payto:// URI of the account. - payto_uri: string; + // a list of taxes paid by the merchant for one unit of this product + taxes: Tax[]; - // Hash over the wire details (including over the salt) - h_wire: HashCode; + // Number of units of the product in stock in sum in total, + // including all existing sales ever. Given in product-specific + // units. + // A value of -1 indicates "infinite" (i.e. for "electronic" books). + total_stock: Integer; - // salt used to compute h_wire - salt: HashCode; + // Number of units of the product that have already been sold. + total_sold: Integer; - // true if this account is active, - // false if it is historic. - active: boolean; - } + // Number of units of the product that were lost (spoiled, stolen, etc.) + total_lost: Integer; - // DELETE /private/instances/$INSTANCE + // Identifies where the product is in stock. + address: Location; + // Identifies when we expect the next restocking to happen. + next_restock?: Timestamp; + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; } - namespace Products { - // POST /private/products - interface ProductAddDetail { - - // product ID to use. - product_id: string; + // POST /private/products/$PRODUCT_ID/lock + interface LockRequest { + // UUID that identifies the frontend performing the lock + // It is suggested that clients use a timeflake for this, + // see https://github.com/anthonynsimon/timeflake + lock_uuid: UUID; - // Human-readable product description. - description: string; + // How long does the frontend intend to hold the lock + duration: RelativeTime; - // Map from IETF BCP 47 language tags to localized descriptions - description_i18n: { [lang_tag: string]: string }; + // How many units should be locked? + quantity: Integer; + } - // unit in which the product is measured (liters, kilograms, packages, etc.) - unit: string; + // DELETE /private/products/$PRODUCT_ID + } - // The price for one unit of the product. Zero is used - // to imply that this product is not sold separately, or - // that the price is not fixed, and must be supplied by the - // front-end. If non-zero, this price MUST include applicable - // taxes. - price: Amount; + namespace Orders { + type MerchantOrderStatusResponse = + | CheckPaymentPaidResponse + | CheckPaymentClaimedResponse + | CheckPaymentUnpaidResponse; + interface CheckPaymentPaidResponse { + // The customer paid for this contract. + order_status: "paid"; - // An optional base64-encoded product image - image: ImageDataUrl; + // Was the payment refunded (even partially)? + refunded: boolean; - // a list of taxes paid by the merchant for one unit of this product - taxes: Tax[]; + // True if there are any approved refunds that the wallet has + // not yet obtained. + refund_pending: boolean; - // Number of units of the product in stock in sum in total, - // including all existing sales ever. Given in product-specific - // units. - // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stock: Integer; + // Did the exchange wire us the funds? + wired: boolean; - // Identifies where the product is in stock. - address: Location; + // Total amount the exchange deposited into our bank account + // for this contract, excluding fees. + deposit_total: Amount; - // Identifies when we expect the next restocking to happen. - next_restock?: Timestamp; + // Numeric error code indicating errors the exchange + // encountered tracking the wire transfer for this purchase (before + // we even got to specific coin issues). + // 0 if there were no issues. + exchange_ec: number; - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; - } - // PATCH /private/products/$PRODUCT_ID - interface ProductPatchDetail { + // HTTP status code returned by the exchange when we asked for + // information to track the wire transfer for this purchase. + // 0 if there were no issues. + exchange_hc: number; - // Human-readable product description. - description: string; + // Total amount that was refunded, 0 if refunded is false. + refund_amount: Amount; - // Map from IETF BCP 47 language tags to localized descriptions - description_i18n: { [lang_tag: string]: string }; + // Contract terms. + contract_terms: ContractTerms; - // unit in which the product is measured (liters, kilograms, packages, etc.) - unit: string; + // The wire transfer status from the exchange for this order if + // available, otherwise empty array. + wire_details: TransactionWireTransfer[]; - // The price for one unit of the product. Zero is used - // to imply that this product is not sold separately, or - // that the price is not fixed, and must be supplied by the - // front-end. If non-zero, this price MUST include applicable - // taxes. - price: Amount; + // Reports about trouble obtaining wire transfer details, + // empty array if no trouble were encountered. + wire_reports: TransactionWireReport[]; - // An optional base64-encoded product image - image: ImageDataUrl; + // The refund details for this order. One entry per + // refunded coin; empty array if there are no refunds. + refund_details: RefundDetails[]; - // a list of taxes paid by the merchant for one unit of this product - taxes: Tax[]; + // Status URL, can be used as a redirect target for the browser + // to show the order QR code / trigger the wallet. + order_status_url: string; + } + interface CheckPaymentClaimedResponse { + // A wallet claimed the order, but did not yet pay for the contract. + order_status: "claimed"; - // Number of units of the product in stock in sum in total, - // including all existing sales ever. Given in product-specific - // units. - // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stock: Integer; + // Contract terms. + contract_terms: ContractTerms; + } + interface CheckPaymentUnpaidResponse { + // The order was neither claimed nor paid. + order_status: "unpaid"; - // Number of units of the product that were lost (spoiled, stolen, etc.) - total_lost: Integer; + // when was the order created + creation_time: Timestamp; - // Identifies where the product is in stock. - address: Location; + // Order summary text. + summary: string; - // Identifies when we expect the next restocking to happen. - next_restock?: Timestamp; + // Total amount of the order (to be paid by the customer). + total_amount: Amount; - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; - } + // URI that the wallet must process to complete the payment. + taler_pay_uri: string; - // GET /private/products - interface InventorySummaryResponse { - // List of products that are present in the inventory - products: InventoryEntry[]; - } - interface InventoryEntry { - // Product identifier, as found in the product. - product_id: string; + // Alternative order ID which was paid for already in the same session. + // Only given if the same product was purchased before in the same session. + already_paid_order_id?: string; - } + // Fulfillment URL of an already paid order. Only given if under this + // session an already paid order with a fulfillment URL exists. + already_paid_fulfillment_url?: string; - // GET /private/products/$PRODUCT_ID - interface ProductDetail { + // Status URL, can be used as a redirect target for the browser + // to show the order QR code / trigger the wallet. + order_status_url: string; - // Human-readable product description. - description: string; + // We do we NOT return the contract terms here because they may not + // exist in case the wallet did not yet claim them. + } + interface RefundDetails { + // Reason given for the refund. + reason: string; - // Map from IETF BCP 47 language tags to localized descriptions - description_i18n: { [lang_tag: string]: string }; + // When was the refund approved. + timestamp: Timestamp; - // unit in which the product is measured (liters, kilograms, packages, etc.) - unit: string; + // Set to true if a refund is still available for the wallet for this payment. + pending: boolean; - // The price for one unit of the product. Zero is used - // to imply that this product is not sold separately, or - // that the price is not fixed, and must be supplied by the - // front-end. If non-zero, this price MUST include applicable - // taxes. - price: Amount; + // Total amount that was refunded (minus a refund fee). + amount: Amount; + } + interface TransactionWireTransfer { + // Responsible exchange. + exchange_url: string; - // An optional base64-encoded product image - image: ImageDataUrl; + // 32-byte wire transfer identifier. + wtid: Base32; - // a list of taxes paid by the merchant for one unit of this product - taxes: Tax[]; + // Execution time of the wire transfer. + execution_time: Timestamp; - // Number of units of the product in stock in sum in total, - // including all existing sales ever. Given in product-specific - // units. - // A value of -1 indicates "infinite" (i.e. for "electronic" books). - total_stock: Integer; + // Total amount that has been wire transferred + // to the merchant. + amount: Amount; - // Number of units of the product that have already been sold. - total_sold: Integer; + // Was this transfer confirmed by the merchant via the + // POST /transfers API, or is it merely claimed by the exchange? + confirmed: boolean; + } + interface TransactionWireReport { + // Numerical error code. + code: number; - // Number of units of the product that were lost (spoiled, stolen, etc.) - total_lost: Integer; + // Human-readable error description. + hint: string; - // Identifies where the product is in stock. - address: Location; + // Numerical error code from the exchange. + exchange_ec: number; - // Identifies when we expect the next restocking to happen. - next_restock?: Timestamp; + // HTTP status code received from the exchange. + exchange_hc: number; - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; - } + // Public key of the coin for which we got the exchange error. + coin_pub: CoinPublicKey; + } - // POST /private/products/$PRODUCT_ID/lock - interface LockRequest { + interface OrderHistory { + // timestamp-sorted array of all orders matching the query. + // The order of the sorting depends on the sign of delta. + orders: OrderHistoryEntry[]; + } + interface OrderHistoryEntry { + // order ID of the transaction related to this entry. + order_id: string; - // UUID that identifies the frontend performing the lock - // It is suggested that clients use a timeflake for this, - // see https://github.com/anthonynsimon/timeflake - lock_uuid: UUID; + // row ID of the order in the database + row_id: number; - // How long does the frontend intend to hold the lock - duration: RelativeTime; + // when the order was created + timestamp: Timestamp; - // How many units should be locked? - quantity: Integer; + // the amount of money the order is for + amount: Amount; - } + // the summary of the order + summary: string; - // DELETE /private/products/$PRODUCT_ID + // whether some part of the order is refundable, + // that is the refund deadline has not yet expired + // and the total amount refunded so far is below + // the value of the original transaction. + refundable: boolean; + // whether the order has been paid or not + paid: boolean; } - namespace Orders { - - type MerchantOrderStatusResponse = CheckPaymentPaidResponse | - CheckPaymentClaimedResponse | - CheckPaymentUnpaidResponse; - interface CheckPaymentPaidResponse { - // The customer paid for this contract. - order_status: "paid"; - - // Was the payment refunded (even partially)? - refunded: boolean; - - // True if there are any approved refunds that the wallet has - // not yet obtained. - refund_pending: boolean; + interface PostOrderRequest { + // The order must at least contain the minimal + // order detail, but can override all + order: Order; + + // if set, the backend will then set the refund deadline to the current + // time plus the specified delay. If it's not set, refunds will not be + // possible. + refund_delay?: RelativeTime; + + // specifies the payment target preferred by the client. Can be used + // to select among the various (active) wire methods supported by the instance. + payment_target?: string; + + // specifies that some products are to be included in the + // order from the inventory. For these inventory management + // is performed (so the products must be in stock) and + // details are completed from the product data of the backend. + inventory_products?: MinimalInventoryProduct[]; + + // Specifies a lock identifier that was used to + // lock a product in the inventory. Only useful if + // manage_inventory is set. Used in case a frontend + // reserved quantities of the individual products while + // the shopping card was being built. Multiple UUIDs can + // be used in case different UUIDs were used for different + // products (i.e. in case the user started with multiple + // shopping sessions that were combined during checkout). + lock_uuids?: UUID[]; + + // Should a token for claiming the order be generated? + // False can make sense if the ORDER_ID is sufficiently + // high entropy to prevent adversarial claims (like it is + // if the backend auto-generates one). Default is 'true'. + create_token?: boolean; + } + type Order = MinimalOrderDetail | ContractTerms; + + interface MinimalOrderDetail { + // Amount to be paid by the customer + amount: Amount; + + // Short summary of the order + summary: string; + + // URL that will show that the order was successful after + // it has been paid for. Optional. When POSTing to the + // merchant, the placeholder "${ORDER_ID}" will be + // replaced with the actual order ID (useful if the + // order ID is generated server-side and needs to be + // in the URL). + fulfillment_url?: string; + } - // Did the exchange wire us the funds? - wired: boolean; + interface MinimalInventoryProduct { + // Which product is requested (here mandatory!) + product_id: string; - // Total amount the exchange deposited into our bank account - // for this contract, excluding fees. - deposit_total: Amount; + // How many units of the product are requested + quantity: Integer; + } + interface PostOrderResponse { + // Order ID of the response that was just created + order_id: string; + + // Token that authorizes the wallet to claim the order. + // Provided only if "create_token" was set to 'true' + // in the request. + token?: ClaimToken; + } + interface OutOfStockResponse { + // Product ID of an out-of-stock item + product_id: string; - // Numeric error code indicating errors the exchange - // encountered tracking the wire transfer for this purchase (before - // we even got to specific coin issues). - // 0 if there were no issues. - exchange_ec: number; - - // HTTP status code returned by the exchange when we asked for - // information to track the wire transfer for this purchase. - // 0 if there were no issues. - exchange_hc: number; + // Requested quantity + requested_quantity: Integer; - // Total amount that was refunded, 0 if refunded is false. - refund_amount: Amount; + // Available quantity (must be below requested_quanitity) + available_quantity: Integer; - // Contract terms. - contract_terms: ContractTerms; + // When do we expect the product to be again in stock? + // Optional, not given if unknown. + restock_expected?: Timestamp; + } - // The wire transfer status from the exchange for this order if - // available, otherwise empty array. - wire_details: TransactionWireTransfer[]; + interface ForgetRequest { + // Array of valid JSON paths to forgettable fields in the order's + // contract terms. + fields: string[]; + } + interface RefundRequest { + // Amount to be refunded + refund: Amount; - // Reports about trouble obtaining wire transfer details, - // empty array if no trouble were encountered. - wire_reports: TransactionWireReport[]; - - // The refund details for this order. One entry per - // refunded coin; empty array if there are no refunds. - refund_details: RefundDetails[]; - - // Status URL, can be used as a redirect target for the browser - // to show the order QR code / trigger the wallet. - order_status_url: string; - } - interface CheckPaymentClaimedResponse { - // A wallet claimed the order, but did not yet pay for the contract. - order_status: "claimed"; + // Human-readable refund justification + reason: string; + } + interface MerchantRefundResponse { + // URL (handled by the backend) that the wallet should access to + // trigger refund processing. + // taler://refund/... + taler_refund_uri: string; + + // Contract hash that a client may need to authenticate an + // HTTP request to obtain the above URI in a wallet-friendly way. + h_contract: HashCode; + } + } - // Contract terms. - contract_terms: ContractTerms; + namespace Tips { + // GET /private/reserves + interface TippingReserveStatus { + // Array of all known reserves (possibly empty!) + reserves: ReserveStatusEntry[]; + } + interface ReserveStatusEntry { + // Public key of the reserve + reserve_pub: EddsaPublicKey; - } - interface CheckPaymentUnpaidResponse { - // The order was neither claimed nor paid. - order_status: "unpaid"; + // Timestamp when it was established + creation_time: Timestamp; - // when was the order created - creation_time: Timestamp; + // Timestamp when it expires + expiration_time: Timestamp; - // Order summary text. - summary: string; + // Initial amount as per reserve creation call + merchant_initial_amount: Amount; - // Total amount of the order (to be paid by the customer). - total_amount: Amount; + // Initial amount as per exchange, 0 if exchange did + // not confirm reserve creation yet. + exchange_initial_amount: Amount; - // URI that the wallet must process to complete the payment. - taler_pay_uri: string; + // Amount picked up so far. + pickup_amount: Amount; - // Alternative order ID which was paid for already in the same session. - // Only given if the same product was purchased before in the same session. - already_paid_order_id?: string; - - // Fulfillment URL of an already paid order. Only given if under this - // session an already paid order with a fulfillment URL exists. - already_paid_fulfillment_url?: string; - - // Status URL, can be used as a redirect target for the browser - // to show the order QR code / trigger the wallet. - order_status_url: string; - - // We do we NOT return the contract terms here because they may not - // exist in case the wallet did not yet claim them. - } - interface RefundDetails { - // Reason given for the refund. - reason: string; - - // When was the refund approved. - timestamp: Timestamp; - - // Set to true if a refund is still available for the wallet for this payment. - pending: boolean; - - // Total amount that was refunded (minus a refund fee). - amount: Amount; - } - interface TransactionWireTransfer { - // Responsible exchange. - exchange_url: string; - - // 32-byte wire transfer identifier. - wtid: Base32; - - // Execution time of the wire transfer. - execution_time: Timestamp; - - // Total amount that has been wire transferred - // to the merchant. - amount: Amount; - - // Was this transfer confirmed by the merchant via the - // POST /transfers API, or is it merely claimed by the exchange? - confirmed: boolean; - } - interface TransactionWireReport { - // Numerical error code. - code: number; - - // Human-readable error description. - hint: string; - - // Numerical error code from the exchange. - exchange_ec: number; - - // HTTP status code received from the exchange. - exchange_hc: number; - - // Public key of the coin for which we got the exchange error. - coin_pub: CoinPublicKey; - } - - interface OrderHistory { - // timestamp-sorted array of all orders matching the query. - // The order of the sorting depends on the sign of delta. - orders: OrderHistoryEntry[]; - } - interface OrderHistoryEntry { - - // order ID of the transaction related to this entry. - order_id: string; - - // row ID of the order in the database - row_id: number; - - // when the order was created - timestamp: Timestamp; - - // the amount of money the order is for - amount: Amount; - - // the summary of the order - summary: string; - - // whether some part of the order is refundable, - // that is the refund deadline has not yet expired - // and the total amount refunded so far is below - // the value of the original transaction. - refundable: boolean; - - // whether the order has been paid or not - paid: boolean; - } - - interface PostOrderRequest { - // The order must at least contain the minimal - // order detail, but can override all - order: Order; - - // if set, the backend will then set the refund deadline to the current - // time plus the specified delay. If it's not set, refunds will not be - // possible. - refund_delay?: RelativeTime; - - // specifies the payment target preferred by the client. Can be used - // to select among the various (active) wire methods supported by the instance. - payment_target?: string; - - // specifies that some products are to be included in the - // order from the inventory. For these inventory management - // is performed (so the products must be in stock) and - // details are completed from the product data of the backend. - inventory_products?: MinimalInventoryProduct[]; - - // Specifies a lock identifier that was used to - // lock a product in the inventory. Only useful if - // manage_inventory is set. Used in case a frontend - // reserved quantities of the individual products while - // the shopping card was being built. Multiple UUIDs can - // be used in case different UUIDs were used for different - // products (i.e. in case the user started with multiple - // shopping sessions that were combined during checkout). - lock_uuids?: UUID[]; - - // Should a token for claiming the order be generated? - // False can make sense if the ORDER_ID is sufficiently - // high entropy to prevent adversarial claims (like it is - // if the backend auto-generates one). Default is 'true'. - create_token?: boolean; - - } - type Order = MinimalOrderDetail | ContractTerms; - - interface MinimalOrderDetail { - // Amount to be paid by the customer - amount: Amount; - - // Short summary of the order - summary: string; - - // URL that will show that the order was successful after - // it has been paid for. Optional. When POSTing to the - // merchant, the placeholder "${ORDER_ID}" will be - // replaced with the actual order ID (useful if the - // order ID is generated server-side and needs to be - // in the URL). - fulfillment_url?: string; - } - - interface MinimalInventoryProduct { - // Which product is requested (here mandatory!) - product_id: string; - - // How many units of the product are requested - quantity: Integer; - } - interface PostOrderResponse { - // Order ID of the response that was just created - order_id: string; - - // Token that authorizes the wallet to claim the order. - // Provided only if "create_token" was set to 'true' - // in the request. - token?: ClaimToken; - } - interface OutOfStockResponse { - - // Product ID of an out-of-stock item - product_id: string; - - // Requested quantity - requested_quantity: Integer; - - // Available quantity (must be below requested_quanitity) - available_quantity: Integer; - - // When do we expect the product to be again in stock? - // Optional, not given if unknown. - restock_expected?: Timestamp; - } - - interface ForgetRequest { - - // Array of valid JSON paths to forgettable fields in the order's - // contract terms. - fields: string[]; - } - interface RefundRequest { - // Amount to be refunded - refund: Amount; - - // Human-readable refund justification - reason: string; - } - interface MerchantRefundResponse { - - // URL (handled by the backend) that the wallet should access to - // trigger refund processing. - // taler://refund/... - taler_refund_uri: string; - - // Contract hash that a client may need to authenticate an - // HTTP request to obtain the above URI in a wallet-friendly way. - h_contract: HashCode; - } + // Amount approved for tips that exceeds the pickup_amount. + committed_amount: Amount; + // Is this reserve active (false if it was deleted but not purged) + active: boolean; } - namespace Tips { + interface ReserveCreateRequest { + // Amount that the merchant promises to put into the reserve + initial_balance: Amount; - // GET /private/reserves - interface TippingReserveStatus { - // Array of all known reserves (possibly empty!) - reserves: ReserveStatusEntry[]; - } - interface ReserveStatusEntry { - // Public key of the reserve - reserve_pub: EddsaPublicKey; + // Exchange the merchant intends to use for tipping + exchange_url: string; - // Timestamp when it was established - creation_time: Timestamp; + // Desired wire method, for example "iban" or "x-taler-bank" + wire_method: string; + } + interface ReserveCreateConfirmation { + // Public key identifying the reserve + reserve_pub: EddsaPublicKey; - // Timestamp when it expires - expiration_time: Timestamp; + // Wire account of the exchange where to transfer the funds + payto_uri: string; + } + interface TipCreateRequest { + // Amount that the customer should be tipped + amount: Amount; - // Initial amount as per reserve creation call - merchant_initial_amount: Amount; + // Justification for giving the tip + justification: string; - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; + // URL that the user should be directed to after tipping, + // will be included in the tip_token. + next_url: string; + } + interface TipCreateConfirmation { + // Unique tip identifier for the tip that was created. + tip_id: HashCode; - // Amount picked up so far. - pickup_amount: Amount; + // taler://tip URI for the tip + taler_tip_uri: string; - // Amount approved for tips that exceeds the pickup_amount. - committed_amount: Amount; + // URL that will directly trigger processing + // the tip when the browser is redirected to it + tip_status_url: string; - // Is this reserve active (false if it was deleted but not purged) - active: boolean; - } + // when does the tip expire + tip_expiration: Timestamp; + } - interface ReserveCreateRequest { - // Amount that the merchant promises to put into the reserve - initial_balance: Amount; + interface ReserveDetail { + // Timestamp when it was established. + creation_time: Timestamp; - // Exchange the merchant intends to use for tipping - exchange_url: string; + // Timestamp when it expires. + expiration_time: Timestamp; - // Desired wire method, for example "iban" or "x-taler-bank" - wire_method: string; - } - interface ReserveCreateConfirmation { - // Public key identifying the reserve - reserve_pub: EddsaPublicKey; + // Initial amount as per reserve creation call. + merchant_initial_amount: Amount; - // Wire account of the exchange where to transfer the funds - payto_uri: string; - } - interface TipCreateRequest { - // Amount that the customer should be tipped - amount: Amount; + // Initial amount as per exchange, 0 if exchange did + // not confirm reserve creation yet. + exchange_initial_amount: Amount; - // Justification for giving the tip - justification: string; + // Amount picked up so far. + pickup_amount: Amount; - // URL that the user should be directed to after tipping, - // will be included in the tip_token. - next_url: string; - } - interface TipCreateConfirmation { - // Unique tip identifier for the tip that was created. - tip_id: HashCode; + // Amount approved for tips that exceeds the pickup_amount. + committed_amount: Amount; - // taler://tip URI for the tip - taler_tip_uri: string; + // Array of all tips created by this reserves (possibly empty!). + // Only present if asked for explicitly. + tips?: TipStatusEntry[]; - // URL that will directly trigger processing - // the tip when the browser is redirected to it - tip_status_url: string; + // Is this reserve active (false if it was deleted but not purged)? + active: boolean; - // when does the tip expire - tip_expiration: Timestamp; - } + // URI to use to fill the reserve, can be NULL + // if the reserve is inactive or was already filled + payto_uri: string; - interface ReserveDetail { - // Timestamp when it was established. - creation_time: Timestamp; + // URL of the exchange hosting the reserve, + // NULL if the reserve is inactive + exchange_url: string; + } - // Timestamp when it expires. - expiration_time: Timestamp; + interface TipStatusEntry { + // Unique identifier for the tip. + tip_id: HashCode; - // Initial amount as per reserve creation call. - merchant_initial_amount: Amount; + // Total amount of the tip that can be withdrawn. + total_amount: Amount; - // Initial amount as per exchange, 0 if exchange did - // not confirm reserve creation yet. - exchange_initial_amount: Amount; + // Human-readable reason for why the tip was granted. + reason: string; + } - // Amount picked up so far. - pickup_amount: Amount; + interface TipDetails { + // Amount that we authorized for this tip. + total_authorized: Amount; - // Amount approved for tips that exceeds the pickup_amount. - committed_amount: Amount; + // Amount that was picked up by the user already. + total_picked_up: Amount; - // Array of all tips created by this reserves (possibly empty!). - // Only present if asked for explicitly. - tips?: TipStatusEntry[]; + // Human-readable reason given when authorizing the tip. + reason: string; - // Is this reserve active (false if it was deleted but not purged)? - active: boolean; + // Timestamp indicating when the tip is set to expire (may be in the past). + expiration: Timestamp; - // URI to use to fill the reserve, can be NULL - // if the reserve is inactive or was already filled - payto_uri: string; + // Reserve public key from which the tip is funded. + reserve_pub: EddsaPublicKey; - // URL of the exchange hosting the reserve, - // NULL if the reserve is inactive - exchange_url: string; + // Array showing the pickup operations of the wallet (possibly empty!). + // Only present if asked for explicitly. + pickups?: PickupDetail[]; + } + interface PickupDetail { + // Unique identifier for the pickup operation. + pickup_id: HashCode; - } + // Number of planchets involved. + num_planchets: Integer; - interface TipStatusEntry { + // Total amount requested for this pickup_id. + requested_amount: Amount; + } + } - // Unique identifier for the tip. - tip_id: HashCode; + namespace Transfers { + interface TransferList { + // list of all the transfers that fit the filter that we know + transfers: TransferDetails[]; + } + interface TransferDetails { + // how much was wired to the merchant (minus fees) + credit_amount: Amount; - // Total amount of the tip that can be withdrawn. - total_amount: Amount; + // raw wire transfer identifier identifying the wire transfer (a base32-encoded value) + wtid: string; - // Human-readable reason for why the tip was granted. - reason: string; - } + // target account that received the wire transfer + payto_uri: string; - interface TipDetails { - // Amount that we authorized for this tip. - total_authorized: Amount; + // base URL of the exchange that made the wire transfer + exchange_url: string; - // Amount that was picked up by the user already. - total_picked_up: Amount; + // Serial number identifying the transfer in the merchant backend. + // Used for filgering via offset. + transfer_serial_id: number; - // Human-readable reason given when authorizing the tip. - reason: string; + // Time of the execution of the wire transfer by the exchange, according to the exchange + // Only provided if we did get an answer from the exchange. + execution_time?: Timestamp; - // Timestamp indicating when the tip is set to expire (may be in the past). - expiration: Timestamp; + // True if we checked the exchange's answer and are happy with it. + // False if we have an answer and are unhappy, missing if we + // do not have an answer from the exchange. + verified?: boolean; - // Reserve public key from which the tip is funded. - reserve_pub: EddsaPublicKey; + // True if the merchant uses the POST /transfers API to confirm + // that this wire transfer took place (and it is thus not + // something merely claimed by the exchange). + confirmed?: boolean; + } - // Array showing the pickup operations of the wallet (possibly empty!). - // Only present if asked for explicitly. - pickups?: PickupDetail[]; - } - interface PickupDetail { - // Unique identifier for the pickup operation. - pickup_id: HashCode; + interface TransferInformation { + // how much was wired to the merchant (minus fees) + credit_amount: Amount; - // Number of planchets involved. - num_planchets: Integer; + // raw wire transfer identifier identifying the wire transfer (a base32-encoded value) + wtid: WireTransferIdentifierRawP; - // Total amount requested for this pickup_id. - requested_amount: Amount; - } + // target account that received the wire transfer + payto_uri: string; + // base URL of the exchange that made the wire transfer + exchange_url: string; } + interface MerchantTrackTransferResponse { + // Total amount transferred + total: Amount; - namespace Transfers { - - interface TransferList { - // list of all the transfers that fit the filter that we know - transfers: TransferDetails[]; - } - interface TransferDetails { - // how much was wired to the merchant (minus fees) - credit_amount: Amount; - - // raw wire transfer identifier identifying the wire transfer (a base32-encoded value) - wtid: string; + // Applicable wire fee that was charged + wire_fee: Amount; - // target account that received the wire transfer - payto_uri: string; + // Time of the execution of the wire transfer by the exchange, according to the exchange + execution_time: Timestamp; - // base URL of the exchange that made the wire transfer - exchange_url: string; - - // Serial number identifying the transfer in the merchant backend. - // Used for filgering via offset. - transfer_serial_id: number; - - // Time of the execution of the wire transfer by the exchange, according to the exchange - // Only provided if we did get an answer from the exchange. - execution_time?: Timestamp; - - // True if we checked the exchange's answer and are happy with it. - // False if we have an answer and are unhappy, missing if we - // do not have an answer from the exchange. - verified?: boolean; - - // True if the merchant uses the POST /transfers API to confirm - // that this wire transfer took place (and it is thus not - // something merely claimed by the exchange). - confirmed?: boolean; - } - - interface TransferInformation { - // how much was wired to the merchant (minus fees) - credit_amount: Amount; - - // raw wire transfer identifier identifying the wire transfer (a base32-encoded value) - wtid: WireTransferIdentifierRawP; - - // target account that received the wire transfer - payto_uri: string; - - // base URL of the exchange that made the wire transfer - exchange_url: string; - } - interface MerchantTrackTransferResponse { - // Total amount transferred - total: Amount; - - // Applicable wire fee that was charged - wire_fee: Amount; - - // Time of the execution of the wire transfer by the exchange, according to the exchange - execution_time: Timestamp; - - // details about the deposits - deposits_sums: MerchantTrackTransferDetail[]; - } - interface MerchantTrackTransferDetail { - // Business activity associated with the wire transferred amount - // deposit_value. - order_id: string; - - // The total amount the exchange paid back for order_id. - deposit_value: Amount; - - // applicable fees for the deposit - deposit_fee: Amount; - } - - type ExchangeConflictDetails = WireFeeConflictDetails | TrackTransferConflictDetails - // Note: this is not the full 'proof' of missbehavior, as - // the bogus message from the exchange with a signature - // over the 'different' wire fee is missing. - // - // This information is NOT provided by the current implementation, - // because this would be quite expensive to generate and is - // hardly needed _here_. Once we add automated reports for - // the Taler auditor, we need to generate this data anyway - // and should probably return it here as well. - interface WireFeeConflictDetails { - // Numerical error code: - code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_BAD_WIRE_FEE"; + // details about the deposits + deposits_sums: MerchantTrackTransferDetail[]; + } + interface MerchantTrackTransferDetail { + // Business activity associated with the wire transferred amount + // deposit_value. + order_id: string; - // Text describing the issue for humans. - hint: string; - - - // Wire fee (wrongly) charged by the exchange, breaking the - // contract affirmed by the exchange_sig. - wire_fee: Amount; - - // Timestamp of the wire transfer - execution_time: Timestamp; - - // The expected wire fee (as signed by the exchange) - expected_wire_fee: Amount; - - // Expected closing fee (needed to verify signature) - expected_closing_fee: Amount; - - // Start date of the expected fee structure - start_date: Timestamp; + // The total amount the exchange paid back for order_id. + deposit_value: Amount; - // End date of the expected fee structure - end_date: Timestamp; + // applicable fees for the deposit + deposit_fee: Amount; + } - // Signature of the exchange affirming the expected fee structure - master_sig: EddsaSignature; - - // Master public key of the exchange - master_pub: EddsaPublicKey; - } - interface TrackTransferConflictDetails { - // Numerical error code - code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_CONFLICTING_REPORTS"; - - // Text describing the issue for humans. - hint: string; - - // Offset in the exchange_transfer where the - // exchange's response fails to match the exchange_deposit_proof. - conflict_offset: number; - - // The response from the exchange which tells us when the - // coin was returned to us, except that it does not match - // the expected value of the coin. - // - // This field is NOT provided by the current implementation, - // because this would be quite expensive to generate and is - // hardly needed _here_. Once we add automated reports for - // the Taler auditor, we need to generate this data anyway - // and should probably return it here as well. - // exchange_transfer?: TrackTransferResponse; + type ExchangeConflictDetails = + | WireFeeConflictDetails + | TrackTransferConflictDetails; + // Note: this is not the full 'proof' of missbehavior, as + // the bogus message from the exchange with a signature + // over the 'different' wire fee is missing. + // + // This information is NOT provided by the current implementation, + // because this would be quite expensive to generate and is + // hardly needed _here_. Once we add automated reports for + // the Taler auditor, we need to generate this data anyway + // and should probably return it here as well. + interface WireFeeConflictDetails { + // Numerical error code: + code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_BAD_WIRE_FEE"; + + // Text describing the issue for humans. + hint: string; + + // Wire fee (wrongly) charged by the exchange, breaking the + // contract affirmed by the exchange_sig. + wire_fee: Amount; + + // Timestamp of the wire transfer + execution_time: Timestamp; + + // The expected wire fee (as signed by the exchange) + expected_wire_fee: Amount; + + // Expected closing fee (needed to verify signature) + expected_closing_fee: Amount; + + // Start date of the expected fee structure + start_date: Timestamp; + + // End date of the expected fee structure + end_date: Timestamp; + + // Signature of the exchange affirming the expected fee structure + master_sig: EddsaSignature; + + // Master public key of the exchange + master_pub: EddsaPublicKey; + } + interface TrackTransferConflictDetails { + // Numerical error code + code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_CONFLICTING_REPORTS"; - // Public key of the exchange used to sign the response to - // our deposit request. - deposit_exchange_pub: EddsaPublicKey; + // Text describing the issue for humans. + hint: string; - // Signature of the exchange signing the (conflicting) response. - // Signs over a struct TALER_DepositConfirmationPS. - deposit_exchange_sig: EddsaSignature; - - // Hash of the merchant's bank account the wire transfer went to - h_wire: HashCode; - - // Hash of the contract terms with the conflicting deposit. - h_contract_terms: HashCode; + // Offset in the exchange_transfer where the + // exchange's response fails to match the exchange_deposit_proof. + conflict_offset: number; - // At what time the exchange received the deposit. Needed - // to verify the \exchange_sig\. - deposit_timestamp: Timestamp; - - // At what time the refund possibility expired (needed to verify exchange_sig). - refund_deadline: Timestamp; - - // Public key of the coin for which we have conflicting information. - coin_pub: EddsaPublicKey; + // The response from the exchange which tells us when the + // coin was returned to us, except that it does not match + // the expected value of the coin. + // + // This field is NOT provided by the current implementation, + // because this would be quite expensive to generate and is + // hardly needed _here_. Once we add automated reports for + // the Taler auditor, we need to generate this data anyway + // and should probably return it here as well. + // exchange_transfer?: TrackTransferResponse; - // Amount the exchange counted the coin for in the transfer. - amount_with_fee: Amount; + // Public key of the exchange used to sign the response to + // our deposit request. + deposit_exchange_pub: EddsaPublicKey; - // Expected value of the coin. - coin_value: Amount; + // Signature of the exchange signing the (conflicting) response. + // Signs over a struct TALER_DepositConfirmationPS. + deposit_exchange_sig: EddsaSignature; - // Expected deposit fee of the coin. - coin_fee: Amount; + // Hash of the merchant's bank account the wire transfer went to + h_wire: HashCode; - // Expected deposit fee of the coin. - deposit_fee: Amount; + // Hash of the contract terms with the conflicting deposit. + h_contract_terms: HashCode; - } + // At what time the exchange received the deposit. Needed + // to verify the \exchange_sig\. + deposit_timestamp: Timestamp; - // interface TrackTransferProof { - // // signature from the exchange made with purpose - // // TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT - // exchange_sig: EddsaSignature; + // At what time the refund possibility expired (needed to verify exchange_sig). + refund_deadline: Timestamp; - // // 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; + // Public key of the coin for which we have conflicting information. + coin_pub: EddsaPublicKey; - // // hash of the wire details (identical for all deposits) - // // Needed to check the exchange_sig - // h_wire: HashCode; - // } + // Amount the exchange counted the coin for in the transfer. + amount_with_fee: Amount; - } + // Expected value of the coin. + coin_value: Amount; + // Expected deposit fee of the coin. + coin_fee: Amount; - interface ContractTerms { - // Human-readable description of the whole purchase - summary: string; - - // Map from IETF BCP 47 language tags to localized summaries - summary_i18n?: { [lang_tag: string]: string }; - - // Unique, free-form identifier for the proposal. - // Must be unique within a merchant instance. - // For merchants that do not store proposals in their DB - // before the customer paid for them, the order_id can be used - // by the frontend to restore a proposal from the information - // encoded in it (such as a short product identifier and timestamp). - order_id: string; - - // Total price for the transaction. - // The exchange will subtract deposit fees from that amount - // before transferring it to the merchant. - amount: Amount; - - // The URL for this purchase. Every time is is visited, the merchant - // will send back to the customer the same proposal. Clearly, this URL - // can be bookmarked and shared by users. - fulfillment_url?: string; - - // Maximum total deposit fee accepted by the merchant for this contract - max_fee: Amount; - - // Maximum wire fee accepted by the merchant (customer share to be - // divided by the 'wire_fee_amortization' factor, and further reduced - // if deposit fees are below 'max_fee'). Default if missing is zero. - max_wire_fee: Amount; - - // Over how many customer transactions does the merchant expect to - // amortize wire fees on average? If the exchange's wire fee is - // above 'max_wire_fee', the difference is divided by this number - // to compute the expected customer's contribution to the wire fee. - // The customer's contribution may further be reduced by the difference - // between the 'max_fee' and the sum of the actual deposit fees. - // Optional, default value if missing is 1. 0 and negative values are - // invalid and also interpreted as 1. - wire_fee_amortization: number; - - // List of products that are part of the purchase (see Product). - products: Product[]; - - // Time when this contract was generated - timestamp: TalerProtocolTimestamp; - - // After this deadline has passed, no refunds will be accepted. - refund_deadline: TalerProtocolTimestamp; - - // After this deadline, the merchant won't accept payments for the contact - pay_deadline: TalerProtocolTimestamp; - - // Transfer deadline for the exchange. Must be in the - // deposit permissions of coins used to pay for this order. - wire_transfer_deadline: TalerProtocolTimestamp; - - // Merchant's public key used to sign this proposal; this information - // is typically added by the backend Note that this can be an ephemeral key. - merchant_pub: EddsaPublicKey; - - // Base URL of the (public!) merchant backend API. - // Must be an absolute URL that ends with a slash. - merchant_base_url: string; - - // More info about the merchant, see below - merchant: Merchant; - - // The hash of the merchant instance's wire details. - h_wire: HashCode; - - // Wire transfer method identifier for the wire method associated with h_wire. - // The wallet may only select exchanges via a matching auditor if the - // exchange also supports this wire method. - // The wire transfer fees must be added based on this wire transfer method. - wire_method: string; - - // Any exchanges audited by these auditors are accepted by the merchant. - auditors: Auditor[]; - - // Exchanges that the merchant accepts even if it does not accept any auditors that audit them. - exchanges: Exchange[]; - - // Delivery location for (all!) products. - delivery_location?: Location; - - // Time indicating when the order should be delivered. - // May be overwritten by individual products. - delivery_date?: TalerProtocolTimestamp; - - // Nonce generated by the wallet and echoed by the merchant - // in this field when the proposal is generated. - nonce: string; - - // Specifies for how long the wallet should try to get an - // automatic refund for the purchase. If this field is - // present, the wallet should wait for a few seconds after - // the purchase and then automatically attempt to obtain - // a refund. The wallet should probe until "delay" - // after the payment was successful (i.e. via long polling - // or via explicit requests with exponential back-off). - // - // In particular, if the wallet is offline - // at that time, it MUST repeat the request until it gets - // one response from the merchant after the delay has expired. - // If the refund is granted, the wallet MUST automatically - // recover the payment. This is used in case a merchant - // knows that it might be unable to satisfy the contract and - // desires for the wallet to attempt to get the refund without any - // customer interaction. Note that it is NOT an error if the - // merchant does not grant a refund. - auto_refund?: RelativeTime; - - // Extra data that is only interpreted by the merchant frontend. - // Useful when the merchant needs to store extra information on a - // contract without storing it separately in their database. - extra?: any; - - // Minimum age buyer must have (in years). Default is 0. - minimum_age?: Integer; + // Expected deposit fee of the coin. + deposit_fee: Amount; } + // interface TrackTransferProof { + // // 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; + + // // hash of the wire details (identical for all deposits) + // // Needed to check the exchange_sig + // h_wire: HashCode; + // } + } + + interface ContractTerms { + // Human-readable description of the whole purchase + summary: string; + + // Map from IETF BCP 47 language tags to localized summaries + summary_i18n?: { [lang_tag: string]: string }; + + // Unique, free-form identifier for the proposal. + // Must be unique within a merchant instance. + // For merchants that do not store proposals in their DB + // before the customer paid for them, the order_id can be used + // by the frontend to restore a proposal from the information + // encoded in it (such as a short product identifier and timestamp). + order_id: string; + + // Total price for the transaction. + // The exchange will subtract deposit fees from that amount + // before transferring it to the merchant. + amount: Amount; + + // The URL for this purchase. Every time is is visited, the merchant + // will send back to the customer the same proposal. Clearly, this URL + // can be bookmarked and shared by users. + fulfillment_url?: string; + + // Maximum total deposit fee accepted by the merchant for this contract + max_fee: Amount; + + // Maximum wire fee accepted by the merchant (customer share to be + // divided by the 'wire_fee_amortization' factor, and further reduced + // if deposit fees are below 'max_fee'). Default if missing is zero. + max_wire_fee: Amount; + + // Over how many customer transactions does the merchant expect to + // amortize wire fees on average? If the exchange's wire fee is + // above 'max_wire_fee', the difference is divided by this number + // to compute the expected customer's contribution to the wire fee. + // The customer's contribution may further be reduced by the difference + // between the 'max_fee' and the sum of the actual deposit fees. + // Optional, default value if missing is 1. 0 and negative values are + // invalid and also interpreted as 1. + wire_fee_amortization: number; + + // List of products that are part of the purchase (see Product). + products: Product[]; + + // Time when this contract was generated + timestamp: TalerProtocolTimestamp; + + // After this deadline has passed, no refunds will be accepted. + refund_deadline: TalerProtocolTimestamp; + + // After this deadline, the merchant won't accept payments for the contact + pay_deadline: TalerProtocolTimestamp; + + // Transfer deadline for the exchange. Must be in the + // deposit permissions of coins used to pay for this order. + wire_transfer_deadline: TalerProtocolTimestamp; + + // Merchant's public key used to sign this proposal; this information + // is typically added by the backend Note that this can be an ephemeral key. + merchant_pub: EddsaPublicKey; + + // Base URL of the (public!) merchant backend API. + // Must be an absolute URL that ends with a slash. + merchant_base_url: string; + + // More info about the merchant, see below + merchant: Merchant; + + // The hash of the merchant instance's wire details. + h_wire: HashCode; + + // Wire transfer method identifier for the wire method associated with h_wire. + // The wallet may only select exchanges via a matching auditor if the + // exchange also supports this wire method. + // The wire transfer fees must be added based on this wire transfer method. + wire_method: string; + + // Any exchanges audited by these auditors are accepted by the merchant. + auditors: Auditor[]; + + // Exchanges that the merchant accepts even if it does not accept any auditors that audit them. + exchanges: Exchange[]; + + // Delivery location for (all!) products. + delivery_location?: Location; + + // Time indicating when the order should be delivered. + // May be overwritten by individual products. + delivery_date?: TalerProtocolTimestamp; + + // Nonce generated by the wallet and echoed by the merchant + // in this field when the proposal is generated. + nonce: string; + + // Specifies for how long the wallet should try to get an + // automatic refund for the purchase. If this field is + // present, the wallet should wait for a few seconds after + // the purchase and then automatically attempt to obtain + // a refund. The wallet should probe until "delay" + // after the payment was successful (i.e. via long polling + // or via explicit requests with exponential back-off). + // + // In particular, if the wallet is offline + // at that time, it MUST repeat the request until it gets + // one response from the merchant after the delay has expired. + // If the refund is granted, the wallet MUST automatically + // recover the payment. This is used in case a merchant + // knows that it might be unable to satisfy the contract and + // desires for the wallet to attempt to get the refund without any + // customer interaction. Note that it is NOT an error if the + // merchant does not grant a refund. + auto_refund?: RelativeTime; + + // Extra data that is only interpreted by the merchant frontend. + // Useful when the merchant needs to store extra information on a + // contract without storing it separately in their database. + extra?: any; + + // Minimum age buyer must have (in years). Default is 0. + minimum_age?: Integer; + } } |