proposals.texi (7424B)
1 @c Section describing the format of Taler contracts/proposals in detail 2 3 @node The Taler proposal format 4 @section The Taler proposal format 5 @cindex contract 6 7 A Taler proposal can specify many details about the transaction. 8 This section describes each of the fields in depth. 9 10 @table @var 11 @item amount 12 @cindex amount 13 Specifies the total amount to be paid to the merchant by the customer. 14 The amount is broken up into a @var{value}, a @var{fraction} 15 (100.000.000 @var{fraction} units correspond to one @var{value}) and 16 the @var{currency}. For example, @code{EUR 1.50} would be represented 17 as the tuple @code{value = 1, fraction = 50000000, currency = "EUR"}. 18 19 @item max_fee 20 @cindex fees 21 @cindex maximum deposit fee 22 This is the maximum total amount of deposit fees that the merchant is 23 willing to pay. If the deposit fees for the coins exceed this amount, 24 the customer has to include it in the payment total. The fee is 25 specified using the same triplet used for @var{amount}. 26 27 28 @item max_wire_fee 29 @cindex fees 30 @cindex maximum wire fee 31 Maximum wire fee accepted by the merchant (customer share to be 32 divided by the 'wire_fee_amortization' factor, and further reduced 33 if deposit fees are below 'max_fee'). Default if missing is zero. 34 35 36 @item wire_fee_amortization 37 @cindex fees 38 @cindex maximum fee amortization 39 Over how many customer transactions does the merchant expect to 40 amortize wire fees on average? If the exchange's wire fee is 41 above 'max_wire_fee', the difference is divided by this number 42 to compute the expected customer's contribution to the wire fee. 43 The customer's contribution may further be reduced by the difference 44 between the 'max_fee' and the sum of the actual deposit fees. 45 Optional, default value if missing is 1. 0 and negative values are 46 invalid and also interpreted as 1. 47 48 @item pay_url 49 @cindex pay_url 50 Which URL accepts payments. This is the URL where the wallet will POST 51 coins. 52 53 @item fulfillment_url 54 @cindex fulfillment URL 55 Which URL should the wallet go to for obtaining the fulfillment, 56 for example the HTML or PDF of an article that was bought, or an 57 order tracking system for shipments, or a simple human-readable 58 Web page indicating the status of the contract. 59 60 @item order_id 61 @cindex order ID 62 Alphanumeric identifier, freely definable by the merchant. 63 Used by the merchant to uniquely identify the transaction. 64 65 @item summary 66 @cindex summary 67 Short, human-readable summary of the contract. To be used when 68 displaying the contract in just one line, for example in the 69 transaction history of the customer. 70 71 @item timestamp 72 Time at which the offer was generated. 73 @c FIXME: describe time format in detail here 74 75 @item pay_deadline 76 @cindex payment deadline 77 Timestamp of the time by which the merchant wants the exchange 78 to definitively wire the money due from this contract. Once 79 this deadline expires, the exchange will aggregate all 80 deposits where the contracts are past the @var{refund_deadline} 81 and execute one large wire payment for them. Amounts will be 82 rounded down to the wire transfer unit; if the total amount is 83 still below the wire transfer unit, it will not be disbursed. 84 85 @item refund_deadline 86 @cindex refund deadline 87 Timestamp until which the merchant willing (and able) to give refunds 88 for the contract using Taler. Note that the Taler exchange will hold 89 the payment in escrow at least until this deadline. Until this time, 90 the merchant will be able to sign a message to trigger a refund to the 91 customer. After this time, it will no longer be possible to refund 92 the customer. Must be smaller than the @var{pay_deadline}. 93 94 @item products 95 @cindex product description 96 Array of products that are being sold to the customer. Each 97 entry contains a tuple with the following values: 98 99 @table @var 100 @item description 101 Description of the product. 102 @item quantity 103 Quantity of the items to be shipped. May specify a unit (@code{1 kg}) 104 or just the count. 105 @item price 106 Price for @var{quantity} units of this product shipped to the 107 given @var{delivery_location}. Note that usually the sum of all 108 of the prices should add up to the total amount of the contract, 109 but it may be different due to discounts or because individual 110 prices are unavailable. 111 @item product_id 112 Unique ID of the product in the merchant's catalog. Can generally 113 be chosen freely as it only has meaning for the merchant, but 114 should be a number in the range @math{[0,2^{51})}. 115 @item taxes 116 Map of applicable taxes to be paid by the merchant. The label is the 117 name of the tax, i.e. @var{VAT}, @var{sales tax} or @var{income tax}, 118 and the value is the applicable tax amount. Note that arbitrary 119 labels are permitted, as long as they are used to identify the 120 applicable tax regime. Details may be specified by the regulator. 121 This is used to declare to the customer which taxes the merchant 122 intends to pay, and can be used by the customer as a receipt. 123 @c FIXME: a receipt not including the item's price? 124 The information is also likely to be used by tax audits of the merchant. 125 @item delivery_date 126 Time by which the product is to be delivered to the 127 @var{delivery_location}. 128 @item delivery_location 129 This should give a label in the @var{locations} map, specifying 130 where the item is to be delivered. 131 @end table 132 Values can be omitted if they are not applicable. For example, if a 133 purchase is about a bundle of products that have no individual prices 134 or product IDs, the @var{product_id} or @var{price} may not be 135 specified in the contract. Similarly, for virtual products delivered 136 directly via the fulfillment URI, there is no delivery location. 137 138 @item merchant 139 @table @var 140 @item address 141 This should give a label in the @var{locations} map, specifying 142 where the merchant is located. 143 @item name 144 This should give a human-readable name for the merchant's business. 145 @item jurisdiction 146 This should give a label in the @var{locations} map, specifying 147 the jurisdiction under which this contract is to be arbitrated. 148 @end table 149 150 @item locations 151 @cindex location 152 Associative map of locations used in the contract. Labels for 153 locations in this map can be freely chosen and used whenever 154 a location is required in other parts of the contract. This way, 155 if the same location is required many times (such as the business 156 address of the customer or the merchant), it only needs to be 157 listed (and transmitted) once, and can otherwise be referred to 158 via the label. A non-exhaustive list of location attributes 159 is the following: 160 @table @var 161 @item country 162 Name of the country for delivery, as found on a postal package, i.e. ``France''. 163 @item state 164 Name of the state for delivery, as found on a postal package, i.e. ``NY''. 165 @item region 166 Name of the region for delivery, as found on a postal package. 167 @item province 168 Name of the province for delivery, as found on a postal package. 169 @item city 170 Name of the city for delivery, as found on a postal package. 171 @item ZIP code 172 ZIP code for delivery, as found on a postal package. 173 @item street 174 Street name for delivery, as found on a postal package. 175 @item street number 176 Street number (number of the house) for delivery, as found on a postal package. 177 @item name receiver name for delivery, either business or person name. 178 179 @end table 180 181 Note that locations are not required to specify all of these fields, 182 and it is also allowed to have additional fields. Contract renderers 183 must render at least the fields listed above, and should render fields 184 that they do not understand as a key-value list. 185 186 @end table