path: root/texinfo/taler-merchant-api-tutorial.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename taler-merchant-api-tutorial.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 3.4.3.@*
@end ifinfo
@settitle Taler Merchant API Tutorial
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory CATEGORY
@direntry
* MENU ENTRY: (taler-merchant-api-tutorial.info). DESCRIPTION
@end direntry

@definfoenclose strong,`,'
@definfoenclose emph,`,'
@c %**end of header

@copying
@quotation
GNU Taler 0.9.0, Jun 20, 2022

GNU Taler team

Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
@end quotation

@end copying

@titlepage
@title Taler Merchant API Tutorial
@insertcopying
@end titlepage
@contents

@c %** start of user preamble

@c %** end of user preamble

@ifnottex
@node Top
@top Taler Merchant API Tutorial
@insertcopying
@end ifnottex

@c %**start of body
@anchor{taler-merchant-api-tutorial doc}@anchor{0}
@c This file is part of GNU TALER.
@c Copyright (C) 2014-2020 Taler Systems SA
@c 
@c TALER is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
@c 
@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
@c 
@c You should have received a copy of the GNU Affero General Public License along with
@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
@c 
@c @author Marcello Stanisci
@c @author Florian Dold
@c @author Christian Grothoff

@menu
* Introduction:: 
* Merchant Payment Processing:: 
* Giving Refunds:: 
* Repurchase detection and fulfillment URLs:: 
* Giving Customers Tips:: 
* Advanced topics:: 
* Index:: 

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* About GNU Taler:: 
* About this tutorial:: 
* Architecture overview:: 
* Public Sandbox Backend and Authentication:: 
* Merchant Instances:: 

Merchant Payment Processing

* Creating an Order for a Payment:: 
* Checking Payment Status and Prompting for Payment:: 

Advanced topics

* Session-Bound Payments:: 
* Product Identification:: 
* The Taler Order Format:: 

@end detailmenu
@end menu

@node Introduction,Merchant Payment Processing,Top,Top
@anchor{taler-merchant-api-tutorial gnu-taler-merchant-api-tutorial}@anchor{1}@anchor{taler-merchant-api-tutorial introduction}@anchor{2}@anchor{taler-merchant-api-tutorial merchant-api-tutorial}@anchor{3}
@chapter Introduction


@menu
* About GNU Taler:: 
* About this tutorial:: 
* Architecture overview:: 
* Public Sandbox Backend and Authentication:: 
* Merchant Instances:: 

@end menu

@node About GNU Taler,About this tutorial,,Introduction
@anchor{taler-merchant-api-tutorial about-gnu-taler}@anchor{4}
@section About GNU Taler


GNU Taler is an open protocol for an electronic payment system with a
free software reference implementation. GNU Taler offers secure, fast
and easy payment processing using well understood cryptographic
techniques. GNU Taler allows customers to remain anonymous, while
ensuring that merchants can be held accountable by governments. Hence,
GNU Taler is compatible with anti-money-laundering (AML) and
know-your-customer (KYC) regulation, as well as data protection
regulation (such as GDPR).

@node About this tutorial,Architecture overview,About GNU Taler,Introduction
@anchor{taler-merchant-api-tutorial about-this-tutorial}@anchor{5}
@section About this tutorial


This tutorial addresses how to process payments using the GNU Taler merchant
Backend.  The audience for this tutorial are @emph{developers} of merchants (such
as Web shops) that are working on integrating GNU Taler with the
customer-facing Frontend and the staff-facing Backoffice.

This chapter explains some basic concepts. In the
second chapter, you will learn how to do basic payments.

This version of the tutorial has examples for Python3. It uses the
@code{requests} library for HTTP requests. Versions for other
languages/environments are available as well.

If you want to look at some simple, running examples, check out these:


@itemize -

@item 
The essay merchant@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/blog}
that sells single chapters of a book.

@item 
The donation page@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/donations}
that accepts donations for software projects and gives donation
receipts.

@item 
The
survey@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/survey}
that gives users who answer a question a small reward.

@item 
The WooCommerce plugin@footnote{https://git.taler.net/gnu-taler-payment-for-woocommerce.git/}
which is a comprehensive integration into a Web shop including the refund business
process.
@end itemize

@node Architecture overview,Public Sandbox Backend and Authentication,About this tutorial,Introduction
@anchor{taler-merchant-api-tutorial architecture-overview}@anchor{6}
@section Architecture overview


The Taler software stack for a merchant consists of the following main
components:

@geindex frontend


@itemize -

@item 
A frontend which interacts with the customer’s browser. The frontend
enables the customer to build a shopping cart and place an order.
Upon payment, it triggers the respective business logic to satisfy
the order. This component is not included with Taler, but rather
assumed to exist at the merchant. This tutorial describes how to
develop a Taler frontend.
@end itemize

@geindex backend


@itemize -

@item 
A Taler-specific payment backend which makes it easy for the frontend
to process financial transactions with Taler. For this tutorial, you
will use a public sandbox backend. For production use, you must
either set up your own backend or ask another person to do so for
you.
@end itemize

The following image illustrates the various interactions of these key
components:

@image{taler-merchant-api-tutorial-figures/arch-api,,,,png}

The backend provides the cryptographic protocol support, stores
Taler-specific financial information and communicates with the GNU Taler
exchange over the Internet. The frontend accesses the backend via a
RESTful API. As a result, the frontend never has to directly communicate
with the exchange, and also does not deal with sensitive data. In
particular, the merchant’s signing keys and bank account information are
encapsulated within the Taler backend.

Some functionality of the backend (the “public interface“) is exposed to the
customer’s browser directly. In the HTTP API, all private endpoints (for the
Backoffice) are prefixed with @code{/private/}.  This tutorial focuses on the
@code{/private/} endpoints. The public interface is directly used by the wallet
and not relevant for the merchant (other than that the API must be exposed).

@geindex sandbox
@geindex authorization

@node Public Sandbox Backend and Authentication,Merchant Instances,Architecture overview,Introduction
@anchor{taler-merchant-api-tutorial public-sandbox-backend-and-authentication}@anchor{7}
@section Public Sandbox Backend and Authentication


How the frontend authenticates to the Taler backend depends on the
configuration. See taler-merchant-manual.

The public sandbox backend @indicateurl{https://backend.demo.taler.net/} uses an API
key in the @code{Authorization} header. The value of this header must be
@code{ApiKey sandbox} for the public sandbox backend.

@example
>>> import requests
>>> requests.get("https://backend.demo.taler.net",
...              headers=@{"Authorization": "ApiKey sandbox"@})
<Response [200]>
@end example

If an HTTP status code other than 200 is returned, something went wrong.
You should figure out what the problem is before continuing with this
tutorial.

The sandbox backend @indicateurl{https://backend.demo.taler.net/} uses @code{KUDOS} as an
imaginary currency. Coins denominated in @code{KUDOS} can be withdrawn from
@indicateurl{https://bank.demo.taler.net/}.

@geindex instance

@node Merchant Instances,,Public Sandbox Backend and Authentication,Introduction
@anchor{taler-merchant-api-tutorial merchant-instances}@anchor{8}
@section Merchant Instances


The same Taler merchant backend server can be used by multiple separate
merchants that are separate business entities. Each of these separate
business entities is called a @emph{merchant instance}, and is identified by
an alphanumeric @emph{instance id}. If the instance is omitted, the instance
id @code{default} is assumed.

The following merchant instances are configured on
@indicateurl{https://backend.demo.taler.net/}:


@itemize -

@item 
@code{GNUnet} (The GNUnet project), reachable at @indicateurl{https://backend.demo.taler.net/instances/gnunet/}

@item 
@code{FSF} (The Free Software Foundation), reachable at @indicateurl{https://backend.demo.taler.net/instances/fsf/}

@item 
@code{Tor} (The Tor Project), reachable at @indicateurl{https://backend.demo.taler.net/instances/tor/}

@item 
@code{default} (Kudos Inc.), reachable at @indicateurl{https://backend.demo.taler.net/}
@end itemize

@cartouche
@quotation Note 
These are fictional merchants used for our demonstrators and
not affiliated with or officially approved by the respective projects.
@end quotation
@end cartouche

All endpoints for instances offer the same API. Thus, which instance
to be used is simply included in the base URL of the merchant backend.

@node Merchant Payment Processing,Giving Refunds,Introduction,Top
@anchor{taler-merchant-api-tutorial id1}@anchor{9}@anchor{taler-merchant-api-tutorial merchant-payment-processing}@anchor{a}
@chapter Merchant Payment Processing


@geindex order

@menu
* Creating an Order for a Payment:: 
* Checking Payment Status and Prompting for Payment:: 

@end menu

@node Creating an Order for a Payment,Checking Payment Status and Prompting for Payment,,Merchant Payment Processing
@anchor{taler-merchant-api-tutorial creating-an-order-for-a-payment}@anchor{b}
@section Creating an Order for a Payment


Payments in Taler revolve around an @emph{order}, which is a machine-readable
description of the business transaction for which the payment is to be
made. Before accepting a Taler payment as a merchant you must create
such an order.

This is done by POSTing a JSON object to the backend’s @code{/private/orders} API
endpoint. At least the following fields must be given inside the @code{order}
field:

@geindex summary

@geindex fulfillment URL


@itemize -

@item 
@code{amount}: The amount to be paid, as a string in the format
@code{CURRENCY:DECIMAL_VALUE}, for example @code{EUR:10} for 10 Euros or
@code{KUDOS:1.5} for 1.5 KUDOS.

@item 
@code{summary}: A human-readable summary for what the payment is about. The
summary should be short enough to fit into titles, though no hard
limit is enforced.

@item 
@code{fulfillment_url}: A URL that will be displayed once the payment is
completed. For digital goods, this should be a page that displays the
product that was purchased. On successful payment, the wallet
automatically appends the @code{order_id} as a query parameter, as well
as the @code{session_sig} for session-bound payments (discussed below).
@end itemize

Orders can have many more fields, see @ref{c,,The Taler Order Format}.  When POSTing an order,
you can also specify additional details such as an override
for the refund duration and instructions for inventory
management. These are rarely needed and not covered in this
tutorial; please see the core/api-merchant reference
manual for details.

A minimal Python snippet for creating an order would look like this:

@example
>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=false)
>>> response = requests.post("https://backend.demo.taler.net/private/order",
...               json=body,
...               headers=@{"Authorization": "ApiKey sandbox"@})
<Response [200]>
@end example

@geindex claim token

The backend will fill in some details missing in the order, such as the
address of the merchant instance. The full details are called the
@emph{contract terms}.

@geindex contract terms

@cartouche
@quotation Note 
The above request disables the use of claim tokens by setting the
@code{create_token} option to @code{false}.  If you need claim tokens,
you must adjust the code to construct the @code{taler://pay/} URI
given below to include the claim token.
@end quotation
@end cartouche

After successfully @code{POST}ing to @code{/private/orders}, an @code{order_id} will be
returned. Together with the merchant @code{instance}, the order id uniquely
identifies the order within a merchant backend.  Using the order ID, you
can trivially construct the respective @code{taler://pay/} URI that must
be provided to the wallet.  Let @code{example.com} be the domain name where
the public endpoints of the instance are reachable. The Taler pay URI is
then simply @code{taler://pay/example.com/$ORDER_ID/} where @code{$ORDER_ID}
must be replaced with the ID of the order that was returned.

You can put the @code{taler://} URI as the target of a link to open the Taler
wallet via the @code{taler://} schema, or put it into a QR code.  However, for a
Web shop, the easiest way is to simply redirect the browser to
@code{https://example.com/orders/$ORDER_ID/}.  That page will then trigger the
Taler wallet. Here the backend generates the right logic to trigger the
wallet, supporting the various types of Taler wallets in existence.  Instead
of constructing the above URL by hand, it is best to obtain it by checking for
the payment status as described in the next section.

@node Checking Payment Status and Prompting for Payment,,Creating an Order for a Payment,Merchant Payment Processing
@anchor{taler-merchant-api-tutorial checking-payment-status-and-prompting-for-payment}@anchor{d}
@section Checking Payment Status and Prompting for Payment


Given the order ID, the status of a payment can be checked with the
@code{/private/orders/$ORDER_ID/} endpoint. If the payment is yet to be completed
by the customer, @code{/private/orders/$ORDER_ID} will give the frontend a URL
(under the name @code{payment_redirect_url}) that will trigger the customer’s
wallet to execute the payment. This is basically the
@code{https://example.com/orders/$ORDER_ID/} URL we discussed above.

Note that the best way to obtain the @code{payment_redirect_url} is to check the
status of the payment, even if you know that the user did not pay yet.  There
are a few corner cases to consider when constructing this URL, so asking the
backend to do it is the safest method.

@example
>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/private/orders/" + order_id,
...                  headers=@{"Authorization": "ApiKey sandbox"@})
>>> print(r.json())
@end example

If the @code{order_status} field in the response is @code{paid}, you will not
get a @code{payment_redirect_url} and instead information about the
payment status, including:


@itemize -

@item 
@code{contract_terms}: The full contract terms of the order.

@item 
@code{refunded}: @code{true} if a (possibly partial) refund was granted for
this purchase.

@item 
@code{refunded_amount}: Amount that was refunded
@end itemize

Once the frontend has confirmed that the payment was successful, it
usually needs to trigger the business logic for the merchant to fulfill
the merchant’s obligations under the contract.

@cartouche
@quotation Note 
You do not need to keep querying to notice changes
to the order's transaction status.  The endpoints
support long polling, simply specify a @code{timeout_ms}
query parameter with how long you want to wait at most
for the order status to change to @code{paid}.
@end quotation
@end cartouche
@anchor{taler-merchant-api-tutorial giving-refunds}@anchor{e}
@geindex refunds

@node Giving Refunds,Repurchase detection and fulfillment URLs,Merchant Payment Processing,Top
@anchor{taler-merchant-api-tutorial id2}@anchor{f}
@chapter Giving Refunds


A refund in GNU Taler is a way to “undo” a payment. It needs to be
authorized by the merchant. Refunds can be for any fraction of the
original amount paid, but they cannot exceed the original payment.
Refunds are time-limited and can only happen while the exchange holds
funds for a particular payment in escrow. The time during which a refund
is possible can be controlled by setting the @code{refund_deadline} in an
order. The default value for this refund deadline is specified in the
configuration of the merchant’s backend.

The frontend can instruct the merchant backend to authorize a refund by
@code{POST}ing to the @code{/private/orders/$ORDER_ID/refund} endpoint.

The refund request JSON object has only two fields:


@itemize -

@item 
@code{refund}: Amount to be refunded. If a previous refund was authorized
for the same order, the new amount must be higher, otherwise the
operation has no effect. The value indicates the total amount to be
refunded, @emph{not} an increase in the refund.

@item 
@code{reason}: Human-readable justification for the refund. The reason is
only used by the Back Office and is not exposed to the customer.
@end itemize

If the request is successful (indicated by HTTP status code 200), the
response includes a @code{taler_refund_uri}. The frontend must redirect
the customer’s browser to that URL to allow the refund to be processed
by the wallet.

This code snipped illustrates giving a refund:

@example
>>> import requests
>>> refund_req = dict(refund="KUDOS:10",
...                   reason="Customer did not like the product")
>>> requests.post("https://backend.demo.taler.net/private/orders/"
...               + order_id + "/refund", json=refund_req,
...               headers=@{"Authorization": "ApiKey sandbox"@})
<Response [200]>
@end example

@cartouche
@quotation Note 
After granting a refund, the public
@code{https://example.com/orders/$ORDER_ID/} endpoint will
change its wallet interaction from requesting payment to
offering a refund.  Thus, frontends may again redirect
browsers to this endpoint.  However, to do so, a
@code{h_contract} field must be appended
(@code{?h_contract=$H_CONTRACT}) as the public endpoint requires
it to authenticate the client.  The required
@code{$H_CONTRACT} value is returned in the refund response
under the @code{h_contract} field.
@end quotation
@end cartouche

@geindex repurchase

@node Repurchase detection and fulfillment URLs,Giving Customers Tips,Giving Refunds,Top
@anchor{taler-merchant-api-tutorial repurchase}@anchor{10}@anchor{taler-merchant-api-tutorial repurchase-detection-and-fulfillment-urls}@anchor{11}
@chapter Repurchase detection and fulfillment URLs


A possible problem for merchants selling access to digital articles
is that a customer may have paid for an article on one device, but
may then want to read it on a different device, possibly one that
does not even have a Taler wallet installed.

Naturally, at this point the customer would at first still be prompted to pay
for the article again. If the customer then opens the @code{taler://} link in the
wallet that did previously pay for the article (for example by scanning the QR
code on the desktop with the Android App), the wallet will claim the contract,
detect that the fulfillment URL is identical to one that it already has made a
payment for in the past, and initiate @strong{repurchase redirection}: Here, the
wallet will contact the merchant and replay the previous payment, except this
time using the (current) session ID of the browser (it learns the session ID
from the QR code).

The merchant backend then updates the session ID of the existing order to
the current session ID of the browser.  When the payment status for the
"new" unpaid order is checked (or already in long-polling), the backend
detects that for the browser's @emph{session ID} and @emph{fulfillment URL} there is an
existing paid contract. It then tells the browser to immediately redirect to
the fulfillment URL where the already paid article is available.

To ensure this mechanism works as designed, merchants must make sure to not
use the same fulfillment URL for different products or for physical products
where customers may be expected to buy the article repeatedly.  Similarly,
it is crucial that merchants consistently use the same fulfillment URL for
the same digital product where repurchase detection is desired.

Note that changing the session ID to a different device requires the
involvement of the wallet that made the payment, thus reasonably limiting the
possibility of broadly sharing the digital purchases.  Repurchase detection is
also @emph{only} done for HTTP(S) fulfillment URLs. In particular, this means
fulfillment URIs like @code{taler://fulfillment-success/$MESSAGE} are not
considered to identify a resource you can pay for and thus do not have to be
unique.
@anchor{taler-merchant-api-tutorial giving-customers-tips}@anchor{12}
@geindex tips

@node Giving Customers Tips,Advanced topics,Repurchase detection and fulfillment URLs,Top
@anchor{taler-merchant-api-tutorial id4}@anchor{13}
@chapter Giving Customers Tips


GNU Taler allows Web sites to grant small amounts directly to the
visitor. The idea is that some sites may want incentivize actions such
as filling out a survey or trying a new feature. It is important to note
that tips are not enforceable for the visitor, as there is no contract.
It is simply a voluntary gesture of appreciation of the site to its
visitor. However, once a tip has been granted, the visitor obtains full
control over the funds provided by the site.

The “merchant” backend of the site must be properly configured for
tipping, and sufficient funds must be made available for tipping See
Taler Merchant Operating Manual.

To check if tipping is configured properly and if there are sufficient
funds available for tipping, query the @code{/tip-query} endpoint:

@example
>>> import requests
>>> requests.get("https://backend.demo.taler.net/tip-query?instance=default",
...              headers=@{"Authorization": "ApiKey sandbox"@})
<Response [200]>
@end example
@anchor{taler-merchant-api-tutorial authorize-tip}@anchor{14}
To authorize a tip, @code{POST} to @code{/tip-authorize}. The following fields
are recognized in the JSON request object:


@itemize -

@item 
@code{amount}: Amount that should be given to the visitor as a tip.

@item 
@code{instance}: Merchant instance that grants the tip (each instance may
have its own independent tipping funds configured).

@item 
@code{justification}: Description of why the tip was granted. Human-readable
text not exposed to the customer, but used by the Back Office.

@item 
@code{next_url}: The URL that the user’s browser should be redirected to by
the wallet, once the tip has been processed.
@end itemize

The response from the backend contains a @code{tip_redirect_url}. The
customer’s browser must be redirected to this URL for the wallet to pick
up the tip.
@anchor{taler-merchant-api-tutorial pick-up-tip}@anchor{15}
This code snipped illustrates giving a tip:

@example
>>> import requests
>>> tip_req = dict(amount="KUDOS:0.5",
...                instance="default",
...                justification="User filled out survey",
...                next_url="https://merchant.com/thanks.html")
>>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req,
...              headers=@{"Authorization": "ApiKey sandbox"@})
<Response [200]>
@end example

@node Advanced topics,Index,Giving Customers Tips,Top
@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{16}@anchor{taler-merchant-api-tutorial id6}@anchor{17}
@chapter Advanced topics


@menu
* Session-Bound Payments:: 
* Product Identification:: 
* The Taler Order Format:: 

@end menu

@node Session-Bound Payments,Product Identification,,Advanced topics
@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{18}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{19}
@section Session-Bound Payments


@geindex session

Sometimes checking if an order has been paid for is not enough. For
example, when selling access to online media, the publisher may want to
be paid for exactly the same product by each customer. Taler supports
this model by allowing the mechant to check whether the “payment
receipt” is available on the user’s current device. This prevents users
from easily sharing media access by transmitting a link to the
fulfillment page. Of course, sophisticated users could share payment
receipts as well, but this is not as easy as sharing a link, and in this
case they are more likely to just share the media directly.

To use this feature, the merchant must first assign the user’s current
browser an ephemeral @code{session_id}, usually via a session cookie. When
executing or re-playing a payment, the wallet will receive an additional
signature (@code{session_sig}). This signature certifies that the wallet
showed a payment receipt for the respective order in the current
session.

@geindex cookie

Session-bound payments are triggered by passing the @code{session_id}
parameter to the @code{/check-payment} endpoint. The wallet will then
redirect to the fulfillment page, but include an additional
@code{session_sig} parameter. The frontend can query @code{/check-payment}
with both the @code{session_id} and the @code{session_sig} to verify that the
signature is correct.

The last session ID that was successfully used to prove that the payment
receipt is in the user’s wallet is also available as @code{last_session_id}
in the response to @code{/check-payment}.

@node Product Identification,The Taler Order Format,Session-Bound Payments,Advanced topics
@anchor{taler-merchant-api-tutorial id8}@anchor{1a}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1b}
@section Product Identification


@geindex resource url

In some situations the user may have paid for some digital good, but the
frontend does not know the exact order ID, and thus cannot instruct the
wallet to reveal the existing payment receipt. This is common for simple
shops without a login system. In this case, the user would be prompted
for payment again, even though they already purchased the product.

To allow the wallet to instead find the existing payment receipt, the
shop must use a unique fulfillment URL for each product. Then, the
frontend must provide an additional @code{resource_url} parameter to to
@code{/check-payment}. It should identify this unique fulfillment URL for
the product. The wallet will then check whether it has paid for a
contract with the same @code{resource_url} before, and if so replay the
previous payment.

@node The Taler Order Format,,Product Identification,Advanced topics
@anchor{taler-merchant-api-tutorial id9}@anchor{1c}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1d}
@section The Taler Order Format


A Taler order can specify many details about the payment. This section
describes each of the fields in depth.

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

@geindex amount


@table @asis

@item amount

Specifies the total amount to be paid to the merchant by the
customer.
@end table

@geindex fees

@geindex maximum deposit fee


@table @asis

@item 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 @code{amount}.
@end table

@geindex fees

@geindex maximum wire fee


@table @asis

@item max_wire_fee

Maximum wire fee accepted by the merchant (customer share to be
divided by the @code{wire_fee_amortization} factor, and further reduced if
deposit fees are below @code{max_fee}). Default if missing is zero.
@end table

@geindex fees

@geindex maximum fee amortization


@table @asis

@item 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
@code{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
@code{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.
@end table

@geindex pay_url


@table @asis

@item pay_url

Which URL accepts payments. This is the URL where the wallet will
POST coins.
@end table

@geindex fulfillment URL


@table @asis

@item 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.
@end table

@geindex order ID


@table @asis

@item order_id

Alphanumeric identifier, freely definable by the merchant. Used by
the merchant to uniquely identify the transaction.
@end table

@geindex summary


@table @asis

@item 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.
@end table

@geindex payment deadline


@table @asis

@item 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 @code{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.
@end table

@geindex refund deadline


@table @asis

@item 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 @code{pay_deadline}.
@end table

@geindex product description


@table @asis

@item products

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


@table @asis

@item description

Description of the product.

@item quantity

Quantity of the items to be shipped. May specify a unit (e.g. @code{1 kg})
or just the count.

@item price

Price for @code{quantity} units of this product shipped to the given
@code{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@comma{}2^@{51@})}.

@item 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.

@item delivery_date

Time by which the product is to be delivered to the
@code{delivery_location}.

@item delivery_location

This should give a label in the @code{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 @code{product_id} or @code{price} may not be specified in the
contract. Similarly, for virtual products delivered directly via the
fulfillment URI, there is no @code{delivery_location}.

@item merchant


@table @asis

@item address

This should give a label in the @code{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 @code{locations} map, specifying the
jurisdiction under which this contract is to be arbitrated.
@end table
@end table

@geindex location


@table @asis

@item 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:


@table @asis

@item name

Receiver name for delivery, either business or person name.

@item country

Name of the country for delivery, as found on a postal package,
e.g. “France”.

@item state

Name of the state for delivery, as found on a postal package, e.g.
“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.
@end table
@end table

@cartouche
@quotation 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.
@end quotation
@end cartouche

@node Index,,Advanced topics,Top
@unnumbered Index


@printindex ge

@anchor{c}@w{                              }
@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{                              }

@c %**end of body
@bye