diff options
Diffstat (limited to 'texinfo/taler-merchant-api-tutorial.texi')
| -rw-r--r-- | texinfo/taler-merchant-api-tutorial.texi | 75 |
1 files changed, 37 insertions, 38 deletions
diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi index 35557ef0..bf5aaefa 100644 --- a/texinfo/taler-merchant-api-tutorial.texi +++ b/texinfo/taler-merchant-api-tutorial.texi @@ -21,11 +21,11 @@ @copying @quotation -GNU Taler 0.8.0pre0, Jan 27, 2021 +GNU Taler 0.8.0pre0, Apr 26, 2021 GNU Taler team -Copyright @copyright{} 2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -142,7 +142,7 @@ 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 -requests library for HTTP requests. Versions for other +@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: @@ -293,7 +293,7 @@ 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 is +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 @@ -331,28 +331,28 @@ field: @itemize - @item -amount: The amount to be paid, as a string in the format +@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 -summary: A human-readable summary for what the payment is about. The +@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 -fulfillment_url: A URL that will be displayed once the payment is +@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 later). +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 read the core/api-merchant reference +tutorial; please see the core/api-merchant reference manual for details. A minimal Python snippet for creating an order would look like this: @@ -436,14 +436,14 @@ payment status, including: @itemize - @item -contract_terms: The full contract terms of the order. +@code{contract_terms}: The full contract terms of the order. @item -refunded: @code{true} if a (possibly partial) refund was granted for +@code{refunded}: @code{true} if a (possibly partial) refund was granted for this purchase. @item -refunded_amount: Amount that was refunded +@code{refunded_amount}: Amount that was refunded @end itemize Once the frontend has confirmed that the payment was successful, it @@ -453,7 +453,7 @@ 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 endpoint +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}. @@ -485,13 +485,13 @@ The refund request JSON object has only two fields: @itemize - @item -refund: Amount to be refunded. If a previous refund was authorized +@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 -reason: Human-readable justification for the refund. The reason is +@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 @@ -551,8 +551,8 @@ 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 +"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. @@ -566,7 +566,7 @@ 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 “taler://fulfillment-success/$MESSAGE” are not +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} @@ -598,8 +598,7 @@ funds available for tipping, query the @code{/tip-query} endpoint: ... headers=@{"Authorization": "ApiKey sandbox"@}) <Response [200]> @end example - -authorize tip +@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: @@ -607,25 +606,25 @@ are recognized in the JSON request object: @itemize - @item -amount: Amount that should be given to the visitor as a tip. +@code{amount}: Amount that should be given to the visitor as a tip. @item -instance: Merchant instance that grants the tip (each instance may +@code{instance}: Merchant instance that grants the tip (each instance may have its own independent tipping funds configured). @item -justification: Description of why the tip was granted. Human-readable +@code{justification}: Description of why the tip was granted. Human-readable text not exposed to the customer, but used by the Back Office. @item -next_url: The URL that the user’s browser should be redirected to by +@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. pick up tip - +up the tip. +@anchor{taler-merchant-api-tutorial pick-up-tip}@anchor{15} This code snipped illustrates giving a tip: @example @@ -640,7 +639,7 @@ This code snipped illustrates giving a tip: @end example @node Advanced topics,Index,Giving Customers Tips,Top -@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{14}@anchor{taler-merchant-api-tutorial id6}@anchor{15} +@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{16}@anchor{taler-merchant-api-tutorial id6}@anchor{17} @chapter Advanced topics @@ -652,7 +651,7 @@ This code snipped illustrates giving a tip: @end menu @node Session-Bound Payments,Product Identification,,Advanced topics -@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{16}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{17} +@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{18}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{19} @section Session-Bound Payments @@ -689,7 +688,7 @@ 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{18}@anchor{taler-merchant-api-tutorial product-identification}@anchor{19} +@anchor{taler-merchant-api-tutorial id8}@anchor{1a}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1b} @section Product Identification @@ -697,7 +696,7 @@ in the response to @code{/check-payment}. 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 reveil the existing payment receipt. This is common for simple +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. @@ -710,7 +709,7 @@ 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{1a}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1b} +@anchor{taler-merchant-api-tutorial id9}@anchor{1c}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1d} @section The Taler Order Format @@ -743,7 +742,7 @@ customer. 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 @code{amount}. +specified using the same format used for @code{amount}. @end table @geindex fees @@ -885,7 +884,7 @@ or just the count. @item price -Price for quantity units of this product shipped to the given +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 @@ -911,19 +910,19 @@ 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 -delivery_location. +@code{delivery_location}. @item delivery_location -This should give a label in the locations map, specifying where +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 product_id or price may not be specified in the +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 delivery location. +fulfillment URI, there is no @code{delivery_location}. @item merchant @@ -1021,8 +1020,8 @@ render fields that they do not understand as a key-value list. @printindex ge -@anchor{c}@w{ } @anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ } +@anchor{c}@w{ } @c %**end of body @bye |