commit 5947ae651ea354a188cb8d21605d546a1cc38d2e
parent 1cfc56f43ef5afbb1adf6947978a2391cd9451f1
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 19 Nov 2016 19:30:10 +0100
documenting more of the contract structure
Diffstat:
| M | php/doc/tutorial.texi | | | 180 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- |
1 file changed, 175 insertions(+), 5 deletions(-)
diff --git a/php/doc/tutorial.texi b/php/doc/tutorial.texi
@@ -471,21 +471,188 @@ loop we construct the list of the transaction IDs paid back by @code{wtid}.
@node Advanced topics
@chapter Advanced topics
-@c FIXME: add menu!
+@menu
+* Presence detection:: Reacting to the presence of a Taler wallet
+* Taler contracts:: Building Taler contracts
+* Inline contracts:: Snding contracts with the HTTP header
+* Payments using JavaScript:: Triggering payments using JavaScript
+* The Fulfillment page:: The rationale behind the fulfillment page design
+@end menu
+
+@node Presence detection
@section Reacting to the presence of a Taler wallet
+@cindex wallet
FIXME.
@c with and without JavaScript!
+@node Taler contracts
@section Building Taler contracts
+@cindex contract
-FIXME.
-@c this should discuss all of the different items in a Taler contract.
+A Taler contract can specify many details about the transaction.
+This section describes each of the fields in depth.
+
+@table @var
+@item amount
+@cindex amount
+Specifies the total amount to be paid to the merchant by the customer.
+The amount is broken up into a @var{value}, a @var{fraction}
+(100.000.000 @var{fraction} units correspond to one @var{value}) and
+the @var{currency}. For example, @code{EUR 1.50} would be represented
+as the tuple @code{value = 1, fraction = 50000000, currency = "EUR"}.
+
+@item max_fee
+@cindex fees
+@cindex maximum deposit 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 triplet used for @var{amount}.
+
+@item fulfillment_url
+@cindex 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.
+
+@item transaction_id
+@cindex transaction ID
+Numeric transaction ID, must be in the range @math{[0,2^{51})}.
+Used by the merchant to uniquely identify the transaction.
+
+@item summary
+@cindex 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.
+
+@item timestamp
+Time at which the offer was generated.
+@c FIXME: describe time format in detail here
+
+@item pay_deadline
+@cindex payment 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 @var{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.
+
+@item refund_deadline
+@cindex 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 @var{pay_deadline}.
+
+@item products
+@cindex product description
+Array of products that are being sold to the customer. Each
+entry contains a tuple with the following values:
+
+@table @var
+@item description
+Description of the product.
+@item quantity
+Quantity of the items to be shipped. May specify a unit (@code{1 kg})
+or just the count.
+@item price
+Price for @var{quantity} units of this product shipped to the
+given @var{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.
+@item 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 @math{[0,2^{51})}.
+@item taxes
+Map of applicable taxes to be paid by the merchant. The label is the
+name of the tax, i.e. @var{VAT}, @var{sales tax} or @var{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.
+@item delivery_date
+Time by which the product is to be delivered to the
+@var{delivery_location}.
+@item delivery_location
+This should give a label in the @var{locations} map, specifying
+where the item is to be delivered.
+@end table
+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 @var{product_id} or @var{price} may not be
+specified in the contract. Similarly, for virtual products delivered
+directly via the fulfillment URI, there is no delivery location.
+
+@item repurchase_correlation_id
+@cindex repurchase correlation ID
+@c FIXME: explain!!!
+
+@item merchant
+@table @var
+@item address
+This should give a label in the @var{locations} map, specifying
+where the merchant is located.
+@item name
+This should give a human-readable name for the merchant's business.
+@item jurisdiction
+This should give a label in the @var{locations} map, specifying
+the jurisdiction under which this contract is to be arbitrated.
+@end table
+
+@item locations
+@cindex location
+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:
+@table @var
+@item country
+Name of the country for delivery, as found on a postal package, i.e. ``France''.
+@item state
+Name of the state for delivery, as found on a postal package, i.e. ``NY''.
+@item region
+Name of the region for delivery, as found on a postal package.
+@item province
+Name of the province for delivery, as found on a postal package.
+@item city
+Name of the city for delivery, as found on a postal package.
+@item ZIP code
+ZIP code for delivery, as found on a postal package.
+@item street
+Street name for delivery, as found on a postal package.
+@item street number
+Street number (number of the house) for delivery, as found on a postal package.
+@item name
+@end table
+Note that locations are not required to specify all of these fields,
+and it 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.
+
+@end table
+@node Inline contracts
@section Inlining contracts in HTTP headers
+@cindex optimization
+@cindex contract
In the example in section FIXME, we told the wallet the URL from where
it should fetch the contract. Instead of specifying the contract via
@@ -493,8 +660,10 @@ an URL, it is also possible to inline short contracts directly.
FIXME: explain how.
-
+@node Payments using JavaScript
@section Triggering payments using JavaScript
+@cindex JavaScript
+@cindex payment
In the example in section FIXME, we used a GET request to trigger the
payment. This section describes how we could have instead performed
@@ -519,8 +688,9 @@ parameter to @code{executePayment}.
@end itemize
-
+@node The Fulfillment page
@section Design considerations for the fulfillment page
+@cindex fulfillment page
The fulfillment page mechanism is designed to provide the following two properties:
