Merchant/Customer Interaction Guide

The audience for the Mechant/Customer Interaction Guide is the merchant who wishes to set up a “web shop” that works with the Taler payment system.

Introduction

The Taler payment cycle involves six parties: (a) customer, (b) exchange, (c) merchant, (d) customer’s bank, (e) exchange’s bank, (f) merchant’s bank.

The exchange is the central entity that mediates the wire transfer of real currency between (d), (e), (f) by way of coins, cryptographically secure tokens passed between (a), (b), (c).

There are six steps to a Taler payment cycle.

In step 1, (a) directs (d) to make real funds available to (b).

In step 2, (d) does a wire transfer of real funds to (e), fulfilling the request from step 1. (b) generates coins corresponding to those real funds; these are called the reserve.

In step 3, (a) withdraws coins, either wholly or partially, from (b). These coins are kept in a wallet under control of (a). The coins in the wallet are unlinkable to the identity of (a) that was revealed during the withdraw operation.

In step 4, (a) authorizes payment of coins from the wallet to (c). This transfers payment coins from the wallet to (c), and change coins from (b) to the wallet (unless the payment amount exactly matches the denomination of the coins in the wallet).

In step 5, (c) deposits coins into (b). At this point, (b) knows the identity of (c), but not of (a). Taler uses cryptography to validate that the coins are unique and were issued by (b), but (b) cannot determine to whom the coins were originally issued.

In step 6, (b) directs (e) to wire transfer real funds corresponding to the accumulated deposited coins to (f).

NB: The Taler payment cycle is part of the Taler payment system, which includes also an auditor component, not described here.

This guide focuses on step 4, the interaction between the customer and the merchant. In particular, we first review two basic interaction flows (with and without shopping cart), then describe Taler features involved in the interaction, the decisions you (the merchant) must make, and how to configure the Taler merchant backend to best support those decisions. Lastly, we present protocol traces for various fictitious interaction flows.

Two Basic Flows

There are two basic payment flows, the first involving a shopping cart, and the second, without (individual product selection / purchase). We distinguish these because for some purchases, a shopping cart is overkill. In either case, Taler can integrate with your inventory management system. Additionally, Taler offers repurchase detection / prevention, most suitable for digital goods.

In the shopping cart experience, you first offer a product on the website. The customer adds the product to their shopping cart, at which point you may optionally lock the product in the inventory system for a certain period of time. The accumulated set of products in the shopping cart is the order. This process repeats until the customer is ready to move to the checkout phase.

At checkout, you may optionally support different payment methods (and make this choice available to the customer) for the order. 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: - 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).

If the customer does nothing (timeout / the contract expires), 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 payment, the customer’s wallet transfers payment coins to you, 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; - repurchase detection / prevention can be useful (for digital products).

Taler Details

This section describes aspects of Taler involved in the basic payment flows in more detail. Each aspect also includes one or more backend API calls that are demonstrated in the next section.

product locking

Taler can integrate with your inventory system to set aside a certain quantity of a product for some duration of time. This is called product locking. This is useful for physical goods, or for goods that have a limited supply, such as airline tickets. Even for digital goods, product locking may be useful to effect exclusivity.

To lock a product, use: POST [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock, specifying a duration and a quantity.

If the customer removes a product from the shopping cart, you can unlock 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. Taxes can be set when the product is added to the inventory, prior to any customer purchase experience (see POST [/instances/$INSTANCE]/private/products, GET [/instances/$INSTANCE]/private/products, and GET [/instances/$INSTANCE]/private/products/$PRODUCT_ID) or specified explicitly by the frontend when adding products to an order that are not managed by the backend inventory (see POST [/instances/$INSTANCE]/private/orders).
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 order.

You can set default_max_deposit_fee in POST /private/instances, or override the default by setting 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.

You can set default_max_wire_fee in POST /private/instances, and max_wire_fee in the contract. If unspecified, the default value is zero (meaning you bear the entire fee).

You can amortize the wire fee across a number of customers by setting default_wire_fee_amortization in POST /private/instances, and wire_fee_amortization in the contract. This is the number of customer transactions over which you expect to amortize wire fees on average. If unspecified, the default value is one.

Note

POST /private/instances must be done at instance-setup time (prior to any purchase).

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 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 by including the names of the respective fields in one or more special _forgettable field(s) in the contract.

Then, you can use: PATCH [/instances/$INSTANCE]/private/orders/$ORDER_ID/forget to forget those details.

claim token

The claim token is a sort of handle on the order and its payment. It is useful when the order ID is easily guessable (e.g. incrementing serial number), to prevent one customer hijacking the order of another. On the other hand, even if the order ID is not easily guessable, if you don’t care about order theft (e.g. infinite supply, digital goods) and you wish to reduce the required processing (e.g. smaller QR code), you can safely disable the claim token.

By default, Taler creates a claim token for each order. To disable this, you can specify create_token to be false in POST [/instances/$INSTANCE]/private/orders.

refund deadline

The refund deadline specifies the time after which you will prohibit refunds. Refunds may be full or partial. Refunds do not require customer details. You can configure the deadline to expire immediately to effect an “all sales are final” policy.

To set the deadline, specify refund_delay in POST [/instances/$INSTANCE]/private/orders. To disable refunds altogether, omit this field.

auto-refund period

The Taler protocol can automatically offer refunds to the customer’s wallet without their explicit prompting during the auto-refund period.

This is useful in the case where the purchase cannot be fulfilled (e.g. jammed vending machine), but there is no way to notify the customer about a refund.

If specified, after contract authorization, the customer’s wallet will repeatedly check for either fulfillment or refund, up to the end of the auto-refund period. (If neither occur within that period, the customer should complain to you for breach of contract.)

To set the auto-refund period, specify auto_refund in POST [/instances/$INSTANCE]/private/orders.

repurchase detection / prevention

Taler can detect a repurchase attempt and prevent it from going through. This feature allows customers to purchase a digital good only once, but to later access the same digital good repeatedly (e.g. reload in browser, after network trouble, etc.) without having to pay again.

This feature is automatic in the protocol; you do not need to do anything to enable it.

Note

For repurchase detection / prevention to work reliably, you must use the same fulfillment URI for the same product and likewise different fulfillment URIs for different products.

fulfillment URI

This may be the actual product (digital goods), or a tracking URL (physical goods). If you issue a claim token with the contract, the customer can access the fulfillment URI from a different device than the one where the wallet is installed.

The fulfillment URI is normally included in the contract. You specify it in POST [/instances/$INSTANCE]/private/orders.

If the fulfillment URI contains the literal string ${ORDER_ID} (including curly braces), that will be replaced by the order ID when POSTing to the merchant. (FIXME: What does “POSTing to the merchant” mean?) This is useful when the backend auto-generates the order ID.

Sample Interaction Traces

In the following descriptions, C stands for customer, W stands for customer’s wallet, M stands for merchant (you), and E stands for exchange. Unless otherwise noted, all API calls are directed toward the Taler backend.

Also, all the traces share the initial pre-sales configuration step.

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: POST /private/instances

// InstanceConfigurationMessage
{
  "payto_uris": ["payto://iban/CH9300762011623852957"],
  "id": "default",
  "name": "Pretty Pianos",
  "auth":
  // InstanceAuthConfigurationMessage
  {
    "method": "external",
    "token": "secret-token:eighty-eight-keys"
  },
  "default_max_wire_fee": "KUDOS:5.0",
  "default_wire_fee_amortization": 1,
  "default_max_deposit_fee": "KUDOS:10.0",
  "default_wire_transfer_delay": "2 days",
  "default_pay_delay": "5 hours"
}
// (backend returns 204 No content)

The fictitious store, Pretty Pianos, has only two products: - pianos (physical good); - Beethoven Sonatas (sheet music PDF files, digital good).

M: POST /instances/default/private/products

// ProductAddDetail
{
  "product_id": "p001",
  "description": "piano",
  "unit": "unit",
  "image": "data:image/png;base64,AAA=",
  "price": "KUDOS:20000.0",
  "taxes": [],
  "total_stock": 3,
  "next_restock": "2021-04-22",
  "_forgettable": ["image"]
}
// (backend returns 204 No content)

Note that the image field is mentioned by name in the _forgettable field’s list value. This means the image value is marked as forgettable. This will come into play later (see below).

M: POST /instances/default/private/products

// ProductAddDetail
{
  "product_id": "f001",
  "description": "Beethoven Sonatas",
  "unit": "file",
  "price": "KUDOS:9.87",
  "taxes": [],
  "total_stock": -1
}
// (backend returns 204 No content)

Note that there is no next_restock field in this ProductAddDetail object. This is because the total_stock field has value -1 (meaning “infinite”) since the product is a PDF file.

Scenario 1: Simple File Purchase

The first scenario is a simple file purchase, without shopping cart, similar to the GNU Essay demo experience.

Because there are infinite supplies of product f001, there is really no need for inventory management. However, you choose to anyway generate a separate order ID in the backend for accounting purposes. Also, since the product is an easily reproduced digital good, you decline to offer the customer the ability to select a “quantity” other than 1 (one), and decide that “all sales are final” (no refund possible). On the other hand, you wish to enable repurchase detection / prevention feature, so that once customers pay for the PDF file, they need never pay again for it.

When the customer clicks on the product’s “buy” button, you first POST to /private/orders to create an order:

M: POST /instances/default/private/orders

// PostOrderRequest
{
  "order":
  // Order (MinimalOrderDetail)
  {
    "amount": "KUDOS:9.87",
    "summary": "Beethoven Sonatas",
    "fulfillment_URI": "https://example.com/f001?${ORDER_ID}"
  },
  "create_token": true
}

Notes: - There is no refund_delay field (no refunds possible). - We show the create_token field with value true even though

that is the default (for illustrative purposes).
  • The order value is actually a MinimalOrderDetail object.
  • The fulfillment_URI value includes the product ID and the literal string ${ORDER_ID}, to be replaced by the backend-generated order ID.

The backend returns 200 OK with the body:

// PostOrderResponse
{
  "order_id": "G93420934823",
  "token": "TEUFHEFBQALK"
}

Notes: - The backend-generated order ID is G93420934823. - The claim token is TEUFHEFBQALK.

(FIXME: Replace w/ more realistic examples?)

Now that there is an order in the system, the wallet claims the order.

W: POST /orders/G93420934823/claim

// ClaimRequest
{
  "nonce": "lksjdflaksjfdlaksjf",
  "token": "TEUFHEFBQALK"
}

Notes: - The nonce value is a randomly-generated string. - The POST endpoint includes the order ID G93420934823. - The token value is the claim token TEUFHEFBQALK

received in the PostOrderResponse.

The backend returns 200 OK with body:

// ContractTerms
{
  "summary": "one copy of Beethoven Sonatas",
  "order_id": "G93420934823",
  "amount": "KUDOS:9.87000000",
  "fulfillment_url": "https://example.com/f001?G93420934823",
  "max_fee": FIXME,
  "max_wire_fee": FIXME,
  "wire_fee_amortization": 1,
  "products": [
    // Product
    {
      "product_id": "f001",
      "description": "Beethoven Sonatas"
    }
  ],
  "timestamp": { "t_ms": 1616537665000 },
  "refund_deadline": { "t_ms": 1616537665000 },
  "pay_deadline": { "t_ms": 1616537725000 },
  "wire_transfer_deadline": { "t_ms": 1616537785000 },
  "merchant_pub": FIXME,
  "merchant_base_url": "https://example.com/",
  "merchant":
    // Merchant
    {
    },
  "h_wire": FIXME,
  "wire_method": FIXME,
  "auditors": [
    // Auditor
  ],
  "exchanges": [
    // Exchange
  ],
  "nonce": "lksjdflaksjfdlaksjf"
}

Notes: - The order_id value is the one given in the PostOrderResponse. - The timestamp value represents 2021-03-23 22:14:25 UTC

in milliseconds after the epoch.
  • The refund_deadline value is the same as the timestamp value (no refunds possible).
  • The pay_deadline value is one minute after the timestamp value.
  • The wire_transfer_deadline value is two minutes after the timestamp value.
  • The products value is a list of one element (one Product object), which omits the price field since that is included in the ContractTerms.amount value. Also, its quantity defaults to 1 (one).
  • The nonce value is the same one specified by the wallet.

At this point, the wallet displays the contract terms (or a subset of them) to the customer, who now has the option to accept the contract or reject it (either explicitly by pressing a “cancel” button, or implicitly by waiting for the offer to time out).

The customer accepts the contract:

W: POST /orders/G93420934823/pay

// PayRequest
{
  "coins": [
    // CoinPaySig
    {
      "coin_sig": ...,
      "coin_pub": ...,
      "ub_sig": ...,
      "h_denom": ...,
      "contribution": "KUDOS:8.0",
      "exchange_url": ...
    },
    {
      "coin_sig": ...,
      "coin_pub": ...,
      "ub_sig": ...,
      "h_denom": ...,
      "contribution": "KUDOS:2.0",
      "exchange_url": ...
    }
  ]
}

Notes: - There is no session ID in the PayRequest object. - The total of the contribution is 8.0 + 2.0 = 10.0 KUDOS,

which is enough to cover the purchase price (9.87 KUDOS).

The backend returns 200 OK with body:

// PaymentResponse
{
  "sig": "..." // EddsaSignature
}

FIXME: At this point, does the wallet need to query (status)? Also, does the frontend need to do anything else?

The wallet then redirects to the fulfillment URI, which displays (or makes available for download) the PDF file “Beethoven Sonatas”.

TODO/FIXME: Add more scenarios (including JSON).