3.1.6. The Taler Order Format#

The Taler order format describes the JSON that must be POSTed to the merchant backend to create an order. It is the prototype from which the merchant backend will create the actual contract terms.

There are different versions for order format; they are described in detail in the Reference manual.

Note

Financial amounts are always specified as a string in the format "CURRENCY:DECIMAL_VALUE".

This section provides an overview of the most common fields:

amount: Specifies the total amount to be paid to the merchant by the customer.

max_fee: This is the maximum total amount of deposit fees that the merchant is willing to pay. If the deposit fees for the coins exceed this amount, the customer has to include it in the payment total. The fee is specified using the same format used for amount.

max_wire_fee: 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.

wire_fee_amortization: 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. Zero and negative values are invalid and also interpreted as 1.

pay_url: Which URL accepts payments. This is the URL where the wallet will POST coins.

fulfillment_url: Which URL should the wallet go to for obtaining the fulfillment, for example the HTML or PDF of an article that was bought, or an order tracking system for shipments, or a simple human-readable Web page indicating the status of the contract.

order_id: Alphanumeric identifier, freely definable by the merchant. Used by the merchant to uniquely identify the transaction.

summary: Short, human-readable summary of the contract. To be used when displaying the contract in just one line, for example in the transaction history of the customer.
timestamp: Time at which the offer was generated.

pay_deadline: Timestamp of the time by which the merchant wants the exchange to definitively wire the money due from this contract. Once this deadline expires, the exchange will aggregate all deposits where the contracts are past the refund_deadline and execute one large wire payment for them. Amounts will be rounded down to the wire transfer unit; if the total amount is still below the wire transfer unit, it will not be disbursed.

refund_deadline: Timestamp until which the merchant willing (and able) to give refunds for the contract using Taler. Note that the Taler exchange will hold the payment in escrow at least until this deadline. Until this time, the merchant will be able to sign a message to trigger a refund to the customer. After this time, it will no longer be possible to refund the customer. Must be smaller than the pay_deadline.

products

Array of products that are being sold to the customer. Each entry contains a tuple with the following values:

description: Description of the product.
quantity: Quantity of the items to be shipped. May specify a unit (e.g. 1 kg) or just the count.
price: Price for quantity units of this product shipped to the given delivery_location. Note that usually the sum of all of the prices should add up to the total amount of the contract, but it may be different due to discounts or because individual prices are unavailable.
product_id: Unique ID of the product in the merchant’s catalog. Can generally be chosen freely as it only has meaning for the merchant, but should be a number in the range $[0,2^{51})$ .
taxes: Map of applicable taxes to be paid by the merchant. The label is the name of the tax, i.e. VAT, sales tax or income tax, and the value is the applicable tax amount. Note that arbitrary labels are permitted, as long as they are used to identify the applicable tax regime. Details may be specified by the regulator. This is used to declare to the customer which taxes the merchant intends to pay, and can be used by the customer as a receipt. The information is also likely to be used by tax audits of the merchant.
delivery_date: Time by which the product is to be delivered to the delivery_location.
delivery_location: This should give a label in the locations map, specifying where the item is to be delivered.

Values can be omitted if they are not applicable. For example, if a purchase is about a bundle of products that have no individual prices or product IDs, the product_id or price may not be specified in the contract. Similarly, for virtual products delivered directly via the fulfillment URI, there is no delivery_location.

merchant

address: This should give a label in the locations map, specifying where the merchant is located.
name: This should give a human-readable name for the merchant’s business.
jurisdiction: This should give a label in the locations map, specifying the jurisdiction under which this contract is to be arbitrated.

locations

Associative map of locations used in the contract. Labels for locations in this map can be freely chosen and used whenever a location is required in other parts of the contract. This way, if the same location is required many times (such as the business address of the customer or the merchant), it only needs to be listed (and transmitted) once, and can otherwise be referred to via the label. A non-exhaustive list of location attributes is the following:

name: Receiver name for delivery, either business or person name.
country: Name of the country for delivery, as found on a postal package, e.g. “France”.
state: Name of the state for delivery, as found on a postal package, e.g. “NY”.
region: Name of the region for delivery, as found on a postal package.
province: Name of the province for delivery, as found on a postal package.
city: Name of the city for delivery, as found on a postal package.
zip_code: ZIP code for delivery, as found on a postal package.
street: Street name for delivery, as found on a postal package.
street_number: Street number (number of the house) for delivery, as found on a postal package.

Note

Locations are not required to specify all of these fields, and they is also allowed to have additional fields. Contract renderers must render at least the fields listed above, and should render fields that they do not understand as a key-value list.