diff options
-rw-r--r-- | anastasis.rst | 20 | ||||
-rw-r--r-- | taler-mcig.rst | 104 |
2 files changed, 97 insertions, 27 deletions
diff --git a/anastasis.rst b/anastasis.rst index 7c10d01f..61b0ed9d 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -1576,13 +1576,24 @@ Arguments (example): "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" } + +Expected new state (depending on method and whether it requires payment): + .. code-block:: json { - "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30", - "answer": "answer to secure question" + "backup_state": "CHALLENGE_SOLVING", + "selected_challenge_uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" + } + +.. code-block:: json + + { + "backup_state": "CHALLENGE_PAYING", + "selected_challenge_uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" } + **pay:** Arguments (example): @@ -1590,7 +1601,7 @@ Arguments (example): .. code-block:: json { - "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" + "payment_secret": "ABCDADF242525AABASD52525235ABABFDABABANALASDAAKASDAS" } @@ -1604,21 +1615,18 @@ Arguments (example): .. code-block:: json { - "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30", "answer": "answer to secure question" } .. code-block:: json { - "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30", "pin": 1234 } .. code-block:: json { - "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30", "hash": "SOMEBASE32ENCODEDHASHVALUE" } diff --git a/taler-mcig.rst b/taler-mcig.rst index 5c2115c4..c8c3d82a 100644 --- a/taler-mcig.rst +++ b/taler-mcig.rst @@ -67,32 +67,38 @@ This guide assumes you and the customer agree to use the Taler payment system. At this point, you generate a *contract* and present it to the customer for authorization. The contract includes: -- some kind of identification for the selected product(s); -- an itemized price list; -- applicable taxes and fees; -- (optional) information on how you deal with *forgettable customer details*; -- (optional) the duration of the lock on the product(s); +- the total amount due; +- a short summary; +- a *fulfillment URI*; +- the *duration* of the offer + (how long the customer has to authorize before timeout); +- (optional) an itemized product list, with + - (optional) some kind of identification for the selected product(s); +- (optional) applicable taxes and fee limits; +- (optional) an order ID (if omitted, the backend will auto-generate one); +- (optional) information which details are *forgettable*; - (optional) a *claim token* that the customer can use later; - (optional) information on the *refund deadline*; - (optional) information on the the *auto-refund period* (how long does - the wallet check for refunds without user prompting for it); -- the total amount due; -- the *duration* of the offer - (how long the customer has to authorize before timeout). + the wallet check for refunds without user prompting for it). If the customer does nothing (timeout / the contract expires), -you *unlock* the product(s) and end the transaction. +the merchant backend automatically *unlocks* the product(s), +allowing other consumers to add more items of the limited stock +to their orders. -On the other hand, if the customer authorizes the contract, +On the other hand, if the customer authorizes payment, the customer's wallet transfers payment coins to you, -and you display to the customer the *fulfillment URI*. +previously locked products are removed from inventory, +and (if possible) the wallet redirects the customer +to the *fulfillment URI*. The individual product selection / purchase experience is like the shopping cart experience with the following exceptions: - there is no shopping cart -- the order is solely the selected product; - Taler payment method is assumed; - customer selection moves directly to checkout; -- there is *repurchase detection / prevention* (for digital products). +- *repurchase detection / prevention* can be useful (for digital products). Taler Details @@ -119,24 +125,33 @@ in the next section. the product by using the same API call, specifying a ``quantity`` of 0 (zero). (Products are also unlocked automatically on timeout / contract expiration.) + Before you can lock products, you need to manage the inventory, creating + an entry for the product (assigning a $PRODUCT_ID) and configure the + available stock. This can be done using the + Taler merchant backoffice Web interface. + + .. note:: + + Once we have documentation for that web interface, we should link to it here. + **taxes** The default taxes for each product is part of the product ``price`` maintained by the backend. - This is set when the product is added to the inventory, + Taxes can be set when the product is added to the inventory, prior to any customer purchase experience (see :http:post:`[/instances/$INSTANCE]/private/products`, :http:get:`[/instnaces/$INSTANCE]/private/products`, - and :http:get:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID`). - - FIXME: Front-end override? + and :http:get:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID`) + or specified explicitly by the frontend when adding + products products to an order that are not managed by the backend inventory. **fees** The Taler protocol charges a *deposit fee* (see step 5, above), which you may choose to pay or to pass on to the customer. - This can be configured to a maximum amount, per customer. + This can be configured to a maximum amount, per order. You can set ``default_max_deposit_fee`` in :http:post:`/private/instances`, - and ``max_fee`` in the contract. + or override the default by setting and ``max_fee`` when creating an order. There is also the *wire fee* (see step 6, above), which you may choose to pay or to pass on to the customer. @@ -158,12 +173,13 @@ in the next section. **forgettable customer details** Although Taler allows the customer to remain anonymous, you may need to collect customer details (e.g. for shipping). - Taler has support for forgetting these details, to comply with GDPR + Taler has support for forgetting such details, to comply with GDPR (for example). This can occur even in the face of refunds (see below). To forget a set of details, first the details that are to be forgotten - must be marked (FIXME: How?, When?). + must be marked by including the names of the respective fields + in a special field " (FIXME: How?, When? => see: https://bugs.gnunet.org/view.php?id=6365). Then, you can use: :http:patch:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/forget` to forget those details. @@ -172,10 +188,25 @@ in the next section. The claim token is a sort of handle on the order and its payment. With it, the customer can access the fulfillment URI from a different device than the one where the wallet is installed. + FIXME: that is not the point. The point is that even if the + $ORDER_ID can be guessed, the claim token cannot. Thus, a + merchant can prevent a third party from claiming an order + (by guessing the order ID). Imagine selling concert tickets, + and your order IDs are 1,2,3,4,5,. I could try to hijack other + visitor's orders (before they have a chance to claim them), + using a claim token prevents this. By default, Taler creates a claim token for each order. To disable this, you can specify ``create_token`` to be ``False`` in :http:post:`[/instances/$INSTANCE]/private/orders`. + => needs guideance as to when to do this, i.e. when + there is no worry about people 'stealing' orders + compiled by others, either because the order ID is + high-entropy OR [[because there is an infinite supply + and we are not concerned about order-theft attacks + (say by a competitor trying to prevent legitimate + customers from claiming their orders) AND want the + QR code to get smaller / scan more easily.]] **refund deadline** The refund deadline specifies the time after which you will prohibit @@ -197,6 +228,14 @@ in the next section. FIXME: Is this the same as the refund deadline? FIXME: API call? + This is useful if it is impossible to notify the customer + about a refund. Example is the Snack machine, where a failure + to dispense a product triggers a refund, but the snack machine + has no good way to tell the shopper that it has issued a refund. + So here, the wallet will _watch_ for say 5 minutes for an auto-refund, + which is automatically issued by the snack machine (if the optical + barrier detects that it could not dispense the product) and appears in the + wallet without the buyer needing to take any action. **repurchase detection / prevention** Taler can detect a repurchase attempt and prevent it from going through. @@ -206,6 +245,10 @@ in the next section. This feature is automatic in the protocol; you do not need to do anything to enable it. + EH, I think you must ensure that you use the + same fulfillment URI for the same product for this to work, + and IIRC you must similarly NOT (re)use the same fulfillment + URL for different products. **fulfillment URI** This may be the actual product (digital goods), @@ -216,6 +259,9 @@ in the next section. The fulfillment URI is normally included in the contract. You specify it in :http:post:`[/instances/$INSTANCE]/private/orders`. + NOTE: explain hack to have the backend include the order ID in + the fulfillment URI somewhere (useful if the backend auto-generates + an order ID). Sample Interaction Traces @@ -235,6 +281,17 @@ Pre-Sales Configuration In the pre-sales configuration step, you set up the *default instance*, and add products to the inventory. +NOTE: not sure we want to ultimately document this HERE. Most merchants +should do _this_ part via the Merchant Web interface that Sebastian is +building right now, and for that we want a separate guide that explains +the API (as you do here), and the Web interface. In this document, +we should focus on how the merchant integrates the (Web)front-end with the +backend, not how the backend itself is configured. +(This also applies to the other instance setup parts you described +above => refer to other guide, but of course specify how we can +override defaults from instance setup per-order.) + + M: :http:post:`/private/instances` .. code-block:: javascript @@ -259,6 +316,7 @@ M: :http:post:`/private/instances` // (backend returns 204 No content) // FIXME: Does InstanceAuthConfigurationMessage require re-configuration? + // => Don't understand question, note that API changed here recently. The fictitious store, Pretty Pianos, has only two products: - pianos (physical good); @@ -280,6 +338,10 @@ M: :http:post:`/instances/default/private/products` } // (backend returns 204 No content) + // FIXME: also add product preview image, and + // maybe use that as a good example for a + // forgettable detail + M: :http:post:`/instances/default/private/products` .. code-block:: javascript |