aboutsummaryrefslogtreecommitdiff
path: root/doc/merchant-api.content.texi
blob: 4ab09bda9388fc2334a8f9ac36a4163401727ebc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
@c *****************************************
@c This file is supposed to be included from
@c the language-specific tutorial.
@c *****************************************

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying
This document is a tutorial for the GNU Taler Merchant API (version @value{VERSION}, @value{UPDATED})

Copyright @copyright{} 2018 Taler Systems SA

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@c If your tutorial is published on paper by the FSF, it should include
@c The standard FSF Front-Cover and Back-Cover Texts, as given in
@c maintain.texi.
@c
@c Titlepage
@c
@titlepage
@title The GNU Taler Merchant API tutorial
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Christian Grothoff (@email{christian@@grothoff.org})
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@author Florian Dold (@email{florian.dold@@inria.fr})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@ifnottex
@node Top
@top The GNU Taler Merchant API Tutorial (Version for @value{LANGNAME})
@insertcopying
@end ifnottex


@menu
* Introduction::                                  What this tutorial is about
* Accepting a Simple Payment::                    How to accept simple payments
* Giving Refunds::                                How to give refunds to customers
* Giving Customers Tips::                         How to reward customers with tips
* Advanced topics::                               Detailed solutions to specific issues


Appendices

* GNU-LGPL::                     The GNU Lesser General Public License says how you
                                 can use the code of libtalermerchant.so in your own projects.
* GNU-FDL::                      The GNU Free Documentation License says how you
                                 can copy and share the documentation of GNU Taler.

Indices

* Concept Index::               Index of concepts and programs.
@end menu


@node Introduction
@chapter Introduction

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


@section About this tutorial

This tutorial addresses how to process payments using the GNU Taler merchant
Backend. This chapter explains some basic concepts.  In the second chapter, you
will learn how to do basic payments.

@clear GOT_LANG
@ifset LANG_PYTHON
@set GOT_LANG 1
This version of the tutorial has examples for Python3.
It uses the requests library for HTTP requests.
@end ifset
@ifset LANG_CURL
@set GOT_LANG 1
This version of the tutorial has examples for the
command line with cURL.
@end ifset
@ifset LANG_PHP
This version of the tutorial has examples for PHP,
using libcurl.
@end ifset
@c
Versions for other languages/environments are available as well.

@cindex examples
@cindex git
If you want to look at some simple, running examples, check out these:
@itemize
@item
The @url{https://git.taler.net/blog.git/tree/talerblog/blog/blog.py, essay merchant} that
sells single chapters of a book.
@item
The @url{https://git.taler.net/donations.git/tree/talerdonations/donations/donations.py, donation page} that
accepts donations for software projects and gives donation receipts.
@item
The @url{https://git.taler.net/survey.git/tree/talersurvey/survey/survey.py,survey} that
gives users who answer a question a small reward.
@end itemize

@section Architecture overview

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

@itemize
@cindex frontend
@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.
@cindex backend
@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{arch-api, 3in}

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 also exposed to the
customer's browser directly.  In the HTTP API, all public endpoints are prefixed with @code{/public/}.

@section Public Sandbox Backend and Authentication
@cindex sandbox
@cindex authorization

How the frontend authenticates to the Taler backend depends on the configuration. @xref{Top,,, manual, Taler Merchant Operating Manual}.

The public sandbox backend @url{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.

@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
curl -i 'https://backend.demo.taler.net/' \
  --header "Authorization: ApiKey sandbox"
# HTTP/1.1 200 OK
# [...]
#
# Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> import requests
>>> requests.get("https://backend.demo.taler.net",
...              headers={"Authorization": "ApiKey sandbox"})
<Response [200]>
@end verbatim
@end example
@end ifset
@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $c = curl_init("https://backend.demo.taler.net/");
php >  $options = array(CURLOPT_RETURNTRANSFER => true,
php (                   CURLOPT_CUSTOMREQUEST => "GET",
php (                   CURLOPT_HTTPHEADER => array("Authorization: ApiKey sandbox"));
php > curl_setopt_array ($c, $options);
php > $r = curl_exec ($c);
php > echo curl_getinfo ($c, CURLINFO_HTTP_CODE);
200
php > echo $r;
Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.
@end verbatim
@end example
@end ifset
@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear

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 @url{https://backend.demo.taler.net/} uses @code{KUDOS} as
an imaginary currency.  Coins denominated in @code{KUDOS} can be withdrawn
from @url{https://bank.demo.taler.net/}.

@section Merchant Instances
@cindex instance

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 @url{https://backend.demo.taler.net/}:
@itemize
@item @code{GNUnet} (The GNUnet project)
@item @code{FSF} (The Free Software Foundation)
@item @code{Tor} (The Tor Project)
@item @code{default} (Kudos Inc.)
@end itemize

Note that these are fictional merchants used for our demonstrators and
not affiliated with or officially approved by the respective projects.


@node Accepting a Simple Payment
@chapter Accepting a Simple Payment

@section Creating an Order for a Payment
@cindex order

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{/order} API endpoint.  At least the
following fields must be given:

@itemize
@item @var{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 @var{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 @var{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).
@end itemize

Orders can have many more fields, see @ref{The Taler Order Format}.

After successfully @code{POST}ing to @code{/order}, an @code{order_id} will be
returned.  Together with the merchant @code{instance}, the order id uniquely
identifies the order within a merchant backend.

@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
@verbatim
ORDER='
{"order": {
  "amount": "KUDOS:10",
  "summary": "Donation",
  "fulfillment_url": "https://example.com/thanks.html"}}
'

curl -i -X POST 'https://backend.demo.taler.net/order' \
     --header "Authorization: ApiKey sandbox" -d "$ORDER"
# HTTP/1.1 200 OK
# [...]
#
# {
#   "order_id": "2018.058.21.46.06-024C85K189H8P"
# }
@end verbatim
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> import requests
>>> order = dict(order=dict(amount="KUDOS:10",
...                         summary="Donation",
...                         fulfillment_url="https://example.com/thanks.html"))
>>> order_resp = requests.post("https://backend.demo.taler.net/order", json=order,
...               headers={"Authorization": "ApiKey sandbox"})
<Response [200]>
@end verbatim
@end example
@end ifset
@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $c = curl_init("https://backend.demo.taler.net/order");
php > $json = array("order"=>
php (   array("amount"=>"KUDOS:1",
php (         "fulfillent_url"=>"https://example.com/thanks.html", 
php (         "summary"=>"nice product"));
php > $options = array(CURLOPT_RETURNTRANSFER=>true,
php (                  CURLOPT_CUSTOMREQUEST=>"POST",
php (                  CURLOPT_POSTFIELDS=>json_encode($json),
php (                  CURLOPT_HTTPHEADER=>array("Authorization: ApiKey sandbox"));
php > curl_setopt_array($c, $options);
php > $r = curl_exec($c);
php > echo curl_getinfo($c, CURLINFO_HTTP_CODE);
200
php > echo $r;
{
  "order_id": "2018.072.12.48.51-014DKDKBMHPDP"
}
@end verbatim
@end example
@end ifset
@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear

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}.
@cindex contract
@cindex terms

@section Checking Payment Status and Prompting for Payment
The status of a payment can be checked with the @code{/check-payment} endpoint.  If the payment
is yet to be completed by the customer, @code{/check-payment} will give the frontend a URL (the @var{payment_redirect_url})
that will trigger the customer's wallet to execute the payment.

Note that the only way to obtain the @var{payment_redirect_url} is to check the status of the payment,
even if you know that the user did not pay yet.

@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
@verbatim
ORDER_ID="2018.058.21.46.06-024C85K189H8P"
curl -i "https://backend.demo.taler.net/check-payment?order_id=$ORDER_ID" \
  --header "Authorization: ApiKey sandbox"
# HTTP/1.1 200 OK
# [...]
#
# {
#   "payment_redirect_url":
#      "https://backend.demo.taler.net/public/trigger-pay?[...]",
#   "paid": false
# }
@end verbatim
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/check-payment",
...                  params=dict(order_id=order_resp.json()["order_id"]),
...                  headers={"Authorization": "ApiKey sandbox"})
>>> print(r.json())
@end verbatim
@end example
@end ifset
@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $ORDER_ID = "2018.072.12.48.51-014DKDKBMHPDP";
php > curl_init ("https://backend.demo.taler.net/check-payment?order_id=$ORDER_ID");
php > $options = array(CURLOPT_RETURNTRANSFER=>true,
php (                   CURLOPT_CUSTOMREQUEST=>"GET",
php (                   CURLOPT_HTTPHEADER=>array(
php (                     "Authorization: ApiKey sandbox"));
php > curl_setopt_array($c, $options);
php > $r = curl_exec($c);
php > echo $r;
@end verbatim
@end example
@end ifset
@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear

If the @var{paid} field in the response is @code{true}, the other
fields in the response will be different. Once the payment was
completed by the user, the response will contain the following fields:

@itemize
@item @var{paid}: Set to @var{true}.
@item @var{contract_terms}:  The full contract terms of the order.
@item @var{refunded}: @code{true} if a (possibly partial) refund was granted for this purchase.
@item @var{refunded_amount}:  Amount that was refunded
@item @var{last_session_id}:  Last session ID used by the customer's wallet. @xref{Session-Bound Payments}.
@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.


@node Giving Refunds
@chapter Giving Refunds
@cindex 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{/refund} endpoint.

The refund request JSON object has the following fields:
@itemize
@item @var{order_id}: Identifies for which order a customer should be refunded.
@c NOTE: the merchant does NOT default to instance "default".
@item @var{instance}: Merchant instance to use.
@item @var{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 @var{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{refund_redirect_url}.  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:
@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
@verbatim
REFUND_REQ='
{"order_id": "2018.058.21.46.06-024C85K189H8P",
 "refund": "KUDOS:10",
 "instance": "default",
 "reason": "Customer did not like the product"}
'

curl -i -X POST 'https://backend.demo.taler.net/refund' \
     --header "Authorization: ApiKey sandbox" -d "$REFUND_REQ"
# HTTP/1.1 200 OK
# [...]
#
# {
#   [...]
#   "refund_redirect_url": "[...]"
# }
@end verbatim
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> import requests
>>> refund_req = dict(order_id="2018.058.21.46.06-024C85K189H8P",
...                   refund="KUDOS:10",
...                   instance="default",
...                   reason="Customer did not like the product")
>>> requests.post("https://backend.demo.taler.net/refund", json=refund_req,
...              headers={"Authorization": "ApiKey sandbox"})
<Response [200]>
@end verbatim
@end example
@end ifset

@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $REFUND_REQ = array("order_id"=>$ORDER_ID,
php (                     "refund"=>"KUDOS:0.5",
php (                     "instance"=>"default",
php (                     "reason"=>"Customer did not like product");
php > $options = array(CURLOPT_RETURNTRANSFER=>true,
php (                  CURLOPT_CUSTOMREQUEST=>"POST",
php (                  CURLOPT_HTTPHEADER=>array(
php (                    "Authorization: ApiKey sandbox"),
php (                  CURLOPT_POSTFIELDS=>json_encode($REFUND_REQ));
php > $c = curl_init("https://backend.demo.taler.net/refund");
php > curl_setopt_array($c, $options);
php > $r = curl_exec($c);
php > echo $r;
php > echo curl_getinfo($c, CURLINFO_HTTP_CODE);
200 # Make sure you paid first!
@end verbatim
@end example
@end ifset
@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear

@node Giving Customers Tips
@chapter Giving Customers Tips
@cindex tips

@c NOTE: Terminology should not be merchant/customer here, as
@c the relationship is completely different. So I use
@c ``site'' and ``visitor'', as that is right now the proper
@c context. We may want to use more payment-ish terminology
@c in the future, but ``donor'' and ``grantee'' sound excessive
@c in the context of ``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 @xref{Top,,, manual,
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:

@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
@verbatim
curl -i 'https://backend.demo.taler.net/tip-query?instance=default' --header "Authorization: ApiKey sandbox"
# HTTP/1.1 200 OK
# [...]
#
# {
#  [...]
#  "amount_available": "KUDOS:153.47",
#  "amount_authorized": "KUDOS:10"
# }
@end verbatim
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> import requests
>>> requests.get("https://backend.demo.taler.net/tip-query?instance=default",
...              headers={"Authorization": "ApiKey sandbox"})
<Response [200]>
@end verbatim
@end example
@end ifset
@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $c = curl_init("https://backend.demo.taler.net/tip-query?instance=default");
php >  $options = array(CURLOPT_RETURNTRANSFER=>true,
php (                   CURLOPT_CUSTOMREQUEST=>"GET",
php (                   CURLOPT_HTTPHEADER=>array(
php (                     "Authorization: ApiKey sandbox"));
php > curl_setopt_array($c, $options);
php > $r = curl_exec($c);
php > echo curl_getinfo($c, CURLINFO_HTTP_CODE);
200
@end verbatim
@end example
@end ifset
@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear

@cindex authorize tip
To authorize a tip, @code{POST} to @code{/tip-authorize}.  The following fields are recognized in the JSON
request object:

@itemize
@item @var{amount}: Amount that should be given to the visitor as a tip.
@item @var{instance}: Merchant instance that grants the tip (each instance may have its own independend tipping funds configured).
@item @var{justification}: Description of why the tip was granted.  Human-readable text not exposed to the customer, but used by the Back Office.
@item @var{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.
@cindex pick up tip

This code snipped illustrates giving a tip:
@clear GOT_LANG
@ifset LANG_CURL
@set GOT_LANG 1
@example
@verbatim
TIP_REQ='
{"amount": "KUDOS:0.5",
 "instance": "default",
 "justification": "User filled out survey",
 "next_url": "https://merchant.com/thanks.html"}
'

curl -i -X POST 'https://backend.demo.taler.net/tip-authorize' \
     --header "Authorization: ApiKey sandbox" -d "$TIP_REQ"
# HTTP/1.1 200 OK
# [...]
#
# {
#   [...]
#   "tip_redirect_url": "[...]"
# }
@end verbatim
@end example
@end ifset
@ifset LANG_PYTHON
@set GOT_LANG 1
@example
@verbatim
>>> 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 verbatim
@end example
@end ifset

@ifset LANG_PHP
@set GOT_LANG 1
@example
@verbatim
php > $TIP_REQ = array(
php (   "amount"=>"KUDOS:1",
php (   "instance"=>"default",
php (   "justification"=>"surveying",
php (   "next_url"=>"https://example.com/survey-thanks.html");
php > $options = array(CURLOPT_RETURNTRANSFER=>true,
php (                  CURLOPT_CUSTOMREQUEST=>"POST",
php (                  CURLOPT_POSTFIELDS=>json_encode($TIP_REQ),
php (                  CURLOPT_HTTPHEADER=>array("Authorization: ApiKey sandbox"));
php > $c = curl_init("https://backend.demo.taler.net/tip-authorize");
php > curl_setopt_array($c, $options);
php > $r = curl_exec($c);
php > echo curl_getinfo($c, CURLINFO_HTTP_CODE); 
200
@end verbatim
@end example
@end ifset

@ifclear GOT_LANG
@example
(example not available for this language)
@end example
@end ifclear


@node Advanced topics
@chapter Advanced topics

@menu
* Detecting the Presence of the Taler Wallet::  Detecting the Presence of the Taler Wallet
* Integration with the Back Office::            Integration with the Back Office
* Session-Bound Payments::                      Session-bound payments for digital goods
* Product Identification::                      Product Identification
* The Taler Order Format::                      The Taler Order Format
@end menu

@node Detecting the Presence of the Taler Wallet
@section Detecting the Presence of the Taler Wallet
@cindex wallet

Taler offers ways to detect whether a user has the wallet installed in
their browser. This allows Web sites to adapt accordingly.  Note that
not all platforms can do presence detection reliably.  Some platforms
might have a Taler wallet installed as a separate App instead of using
a Web extension.  In these cases, presence detection will fail. Thus,
sites may want to allow users to request Taler payments even if a
wallet could not be detected, especially for visitors using mobiles.

@subsection Presence detection without JavaScript
Presence detection without JavaScript is based on CSS classes.  You can hide or
show elements selectively depending on whether the wallet is detected or not.

In order to work correctly, a special fallback stylesheet must be included that
will be used when the wallet is not present.  The stylesheet can be put into
any file, but must be included via a @code{link} tag with the @code{id}
attribute set to @code{taler-presence-stylesheet}.  If a wallet is present, it
will ``hijack'' this stylesheet to change how elements with the following
classes are rendered:

The following CSS classes can be used:
@table @code
@item taler-installed-hide
A CSS rule will set the @code{display} property for this class to @code{none} once the Taler wallet is installed and enabled.
If the wallet is not installed, @code{display} will be @code{inherit}.

@item taler-installed-show
A CSS rule will set the @code{display} property for this class to @code{inherit} once the Taler wallet is installed and enabled.
If the wallet is not installed, @code{display} will be @code{none}.

@end table

The following is a complete example:

@smallexample
<!DOCTYPE html>
<html data-taler-nojs="true">
  <head>
    <title>Tutorial</title>
    <link rel="stylesheet"
          type="text/css"
          href="/web-common/taler-fallback.css"
          id="taler-presence-stylesheet" />
  </head>
  <body>
    <p class="taler-installed-hide">
      No wallet found.
    </p>
    <p class="taler-installed-show">
      Wallet found!
    </p>
  </body>
</html>
@end smallexample

The @code{taler-fallback.css} is part of the Taler's @emph{web-common} repository,
available at @url{https://git.taler.net/web-common.git/tree/taler-fallback.css}.
You may have to adjust the @code{href} attribute in the HTML code above to point
to the correct location of the @code{taler-fallback.css} file on your Web site.

@subsection Detection with JavaScript

The following functions are defined in the @code{taler} namespace of the @code{taler-wallet-lib} helper library
available at @url{https://git.taler.net/web-common.git/tree/taler-wallet-lib.js}.

@table @code
@item onPresent(callback: () => void)
Adds a callback to be called when support for Taler payments is detected.

@item onAbsent(callback: () => void)
Adds a callback to be called when support for Taler payments is disabled.

@end table

Note that the registered callbacks may be called more than once. This may
happen if a user disables or enables the wallet in the browser's extension
settings while a shop's frontend page is open.

@c FIXME: include full example of Web site including taler-wallet-lib.js
@c and using JS detection actions.  (alert()?)

@node Integration with the Back Office
@section Integration with the Back Office

Taler ships a Back Office application as a stand-alone Web application.
The Back Office has its own documentation at @url{https://docs.taler.net/backoffice/html/manual.html}.

Developers wishing to tightly integrate back office support for
Taler-based payments into an existing back office application should
focus on the wire transfer tracking and transaction history sections
of the Taler Backend API specification at
@url{https://docs.taler.net/api/api-merchant.html}

@node Session-Bound Payments
@section Session-Bound Payments
@cindex 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.
@cindex cookie

Session-bound payments are triggerd 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 successfuly 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}.
@c FIXME: used for what?

@node Product Identification
@section Product Identification
@cindex 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 reveil
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.
@c FIXME: design question (!): why do we not simply set a flag (``unique fulfillment url'')
@c instead of passing the fulfillment URL a *second* time to the backend?
@c (and having to worry about it being the same as in the order on /order)?


@c Section describing the format of Taler contracts/proposals in detail

@node The Taler Order Format
@section The Taler Order Format
@cindex contract
@cindex terms
@cindex order

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"}.

@table @var
@item amount
@cindex amount
Specifies the total amount to be paid to the merchant by the customer.

@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 max_wire_fee
@cindex fees
@cindex maximum wire fee
Maximum wire fee accepted by the merchant (customer share to be
divided by the 'wire_fee_amortization' factor, and further reduced
if deposit fees are below 'max_fee').  Default if missing is zero.


@item wire_fee_amortization
@cindex fees
@cindex maximum 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 '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 'max_fee' and the sum of the actual deposit fees.
Optional, default value if missing is 1.  0 and negative values are
invalid and also interpreted as 1.

@item pay_url
@cindex pay_url
Which URL accepts payments. This is the URL where the wallet will POST
coins.

@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 order_id
@cindex order ID
Alphanumeric identifier, freely definable by the merchant.
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.
@c FIXME: a receipt not including the item's price?
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 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 receiver name for delivery, either business or person name.

@end table

Note that 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 table


@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@node GNU-LGPL
@unnumbered GNU-LGPL
@cindex license
@cindex LGPL
@include lgpl.texi

@node GNU-FDL
@unnumbered GNU-FDL
@cindex license
@cindex GNU Free Documentation License
@include fdl-1.3.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp