diff options
| -rw-r--r-- | conf.py | 6 | ||||
| -rw-r--r-- | fdl-1.3.rst | 26 | ||||
| -rw-r--r-- | taler-merchant-api-tutorial.rst | 5 | ||||
| -rw-r--r-- | taler-merchant-manual.rst | 439 |
4 files changed, 173 insertions, 303 deletions
@@ -77,16 +77,16 @@ master_doc = 'index' # General information about the project. project = u'GNU Taler' -copyright = u'2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)' +copyright = u'2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+)' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.6pre1' +version = '0.8pre0' # The full version, including alpha/beta/rc tags. -release = '0.6.0pre1' +release = '0.8.0pre0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/fdl-1.3.rst b/fdl-1.3.rst index 6dec4945..49bf2d3e 100644 --- a/fdl-1.3.rst +++ b/fdl-1.3.rst @@ -12,7 +12,7 @@ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE -^^^^^^^^^^^ +----------- The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure @@ -36,7 +36,7 @@ published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------- This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be @@ -124,7 +124,7 @@ these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING -^^^^^^^^^^^^^^^^^^^ +------------------- You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the @@ -140,7 +140,7 @@ You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the @@ -178,7 +178,7 @@ Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS -^^^^^^^^^^^^^^^^ +---------------- You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the @@ -264,7 +264,7 @@ give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified @@ -289,7 +289,7 @@ sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”. 6. COLLECTIONS OF DOCUMENTS -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------- You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this @@ -303,7 +303,7 @@ License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------- A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or @@ -322,7 +322,7 @@ equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION -^^^^^^^^^^^^^^ +-------------- Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing @@ -342,7 +342,7 @@ If a section in the Document is Entitled “Acknowledgements”, Title (section 1) will typically require changing the actual title. 9. TERMINATION -^^^^^^^^^^^^^^ +-------------- You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, @@ -370,7 +370,7 @@ reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 10. FUTURE REVISIONS OF THIS LICENSE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------ The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will @@ -390,7 +390,7 @@ used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document. 11. RELICENSING -^^^^^^^^^^^^^^^ +--------------- “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides @@ -419,7 +419,7 @@ under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing. ADDENDUM: How to use this License for your documents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------------- To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index f97f96c1..6442e7c2 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -66,7 +66,7 @@ components: The following image illustrates the various interactions of these key components: -|image0| +.. image:: arch-api.png The backend provides the cryptographic protocol support, stores Taler-specific financial information and communicates with the GNU Taler @@ -736,6 +736,3 @@ locations 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. - - -.. |image0| image:: arch-api.png diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index dfa6492e..8fcb487e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -50,8 +50,8 @@ operating a basic backend. Architecture overview --------------------- -:keywords: crypto-currency -:keywords: KUDOS +.. index:: crypto-currency +.. index:: KUDOS Taler is a pure payment system, not a new crypto-currency. As such, it operates in a traditional banking context. In particular, this means @@ -60,33 +60,31 @@ regular bank account, and payments can be executed in ordinary currencies such as USD or EUR. For testing purposes, Taler uses a special currency “KUDOS” and includes its own special bank. +.. index:: frontend +.. index:: back office +.. index:: backend +.. index:: DBMS +.. index:: Postgres + The Taler software stack for a merchant consists of four main components: -- frontend - A frontend which interacts with the customer’s browser. The frontend +- 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 manual describes how to integrate Taler with Web shop frontends. - -- back office - A back office application that enables the shop operators to view +- A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is again not included with Taler, but rather assumed to exist at the merchant. This manual will describe how to integrate such a component to handle payments managed by Taler. - -- backend - A Taler-specific payment backend which makes it easy for the frontend +- A Taler-specific payment backend which makes it easy for the frontend to process financial transactions with Taler. The next two chapters will describe how to install and configure this backend. - -- DBMS - Postgres - A DBMS which stores the transaction history for the Taler backend. +- A DBMS which stores the transaction history for the Taler backend. For now, the GNU Taler reference implemenation only supports Postgres, but the code could be easily extended to support another DBMS. @@ -94,11 +92,10 @@ components: The following image illustrates the various interactions of these key components: -:: +.. image:: arch-api.png - Missing diagram image +.. index:: RESTful -RESTful Basically, the backend provides the cryptographic protocol support, stores Taler-specific financial information in a DBMS and communicates with the GNU Taler exchange over the Internet. The frontend accesses the @@ -128,7 +125,7 @@ system. .. _Installation-of-dependencies: Installation of dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following packages need to be installed before we can compile the backend: @@ -173,9 +170,9 @@ the libgnunetutil and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: Installing libgnunetutil -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: GNUnet +.. index:: GNUnet Before you install libgnunetutil, you must download and install the dependencies mentioned in the previous section, otherwise the build may @@ -200,9 +197,9 @@ which requires you to run the last step as ``root``. .. _Installing-the-GNU-Taler-exchange: Installing the GNU Taler exchange -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: exchange +.. index:: exchange After installing GNUnet, you can download and install the exchange as follows: @@ -227,9 +224,9 @@ installed GNUnet to ``/usr/local`` in the previous step. .. _Installing-the-GNU-Taler-merchant-backend: Installing the GNU Taler merchant backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: backend +.. index:: backend The following steps assume all dependencies are installed. @@ -257,8 +254,8 @@ GNUnet to ``/usr/local`` in the previous steps. Installing Taler on Debian GNU/Linux ------------------------------------ -:keywords: Wheezy -:keywords: Debian +.. index:: Wheezy +.. index:: Debian Debian wheezy is too old and lacks most of the packages required. @@ -318,8 +315,8 @@ if you used the Debian wheezy instructions above, you need to pass How to configure the merchant’s backend ======================================= -:keywords: taler-config -:keywords: taler.conf +.. index:: taler-config +.. index:: taler.conf The installation already provides reasonable defaults for most of the configuration options. However, some must be provided, in particular the @@ -336,22 +333,33 @@ see `Using taler-config <#Using-taler_002dconfig>`__. Backend options --------------- +.. index:: DBMS +.. index:: Postgres +.. index:: UNIX domain socket +.. index:: TCP +.. index:: port +.. index:: currency +.. index:: KUDOS +.. index:: exchange +.. index:: instance +.. index:: wire format + The following table describes the options that commonly need to be modified. Here, the notation ``[$section]/$option`` denotes the option ``$option`` under the section ``[$section]`` in the configuration file. + Service address - The following option sets the transport layer address used by the - merchant backend: +^^^^^^^^^^^^^^^ -:keywords: UNIX domain socket -:keywords: TCP +The following option sets the transport layer address used by the +merchant backend: :: [MERCHANT]/SERVE = TCP | UNIX - If given, +If given, - ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT`` @@ -360,13 +368,12 @@ Service address latter takes the usual permission mask given as a number, e.g. 660 for user/group read-write access. - The frontend can then connect to the backend over HTTP using the - specified address. If frontend and backend run within the same - operating system, the use of a UNIX domain socket is recommended to - avoid accidentally exposing the backend to the network. +The frontend can then connect to the backend over HTTP using the specified +address. If frontend and backend run within the same operating system, the +use of a UNIX domain socket is recommended to avoid accidentally exposing +the backend to the network. -:keywords: port - To run the Taler backend on TCP port 8888, use: +To run the Taler backend on TCP port 8888, use: :: @@ -374,70 +381,68 @@ Service address $ taler-config -s MERCHANT -o PORT -V 8888 Currency - Which currency the Web shop deals in, i.e. “EUR” or “USD”, is - specified using the option +^^^^^^^^ + +Which currency the Web shop deals in, i.e. “EUR” or “USD”, is +specified using the option -:keywords: currency -:keywords: KUDOS :: [TALER]/CURRENCY - For testing purposes, the currency MUST match “KUDOS” so that tests - will work with the Taler demonstration exchange at - https://exchange.demo.taler.net/: +For testing purposes, the currency MUST match “KUDOS” so that tests +will work with the Taler demonstration exchange at +https://exchange.demo.taler.net/: :: $ taler-config -s TALER -o CURRENCY -V KUDOS Database -:keywords: DBMS +^^^^^^^^ - In principle is possible for the backend to support different DBMSs. - The option +In principle is possible for the backend to support different DBMSs. +The option :: [MERCHANT]/DB - specifies which DBMS is to be used. However, currently only the value - "postgres" is supported. This is also the default. +specifies which DBMS is to be used. However, currently only the value +"postgres" is supported. This is also the default. - In addition to selecting the DBMS software, the backend requires - DBMS-specific options to access the database. +In addition to selecting the DBMS software, the backend requires +DBMS-specific options to access the database. - For postgres, you need to provide: +For postgres, you need to provide: :: [merchantdb-postgres]/config -:keywords: Postgres - - This option specifies a postgres access path using the format - ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the - Postgres database you want to use. Suppose ``$USER`` is the name of - the user who will run the backend process. Then, you need to first - run +This option specifies a postgres access path using the format +``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the +Postgres database you want to use. Suppose ``$USER`` is the name of +the user who will run the backend process. Then, you need to first +run :: $ sudu -u postgres createuser -d $USER - as the Postgres database administrator (usually ``postgres``) to - grant ``$USER`` the ability to create new databases. Next, you should - as ``$USER`` run: +as the Postgres database administrator (usually ``postgres``) to +grant ``$USER`` the ability to create new databases. Next, you should +as ``$USER`` run: :: $ createdb $DBNAME - to create the backend’s database. Here, ``$DBNAME`` must match the - database name given in the configuration file. +to create the backend’s database. Here, ``$DBNAME`` must match the +database name given in the configuration file. - To configure the Taler backend to use this database, run: +To configure the Taler backend to use this database, run: :: @@ -445,11 +450,11 @@ Database -V postgres:///$DBNAME Exchange -:keywords: exchange +^^^^^^^^ - To add an exchange to the list of trusted payment service providers, - you create a section with a name that starts with “exchange-”. In - that section, the following options need to be configured: +To add an exchange to the list of trusted payment service providers, +you create a section with a name that starts with “exchange-”. In +that section, the following options need to be configured: - The “url” option specifies the exchange’s base URL. For example, to use the Taler demonstrator use: @@ -468,92 +473,28 @@ Exchange $ taler-config -s EXCHANGE-demo -o master_key \ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 - Note that multiple exchanges can be added to the system by using - different tokens in place of ``demo`` in the example above. Note - that all of the exchanges must use the same currency. If you need - to support multiple currencies, you need to configure a backend - per currency. +Note that multiple exchanges can be added to the system by using +different tokens in place of ``demo`` in the example above. Note +that all of the exchanges must use the same currency. If you need +to support multiple currencies, you need to configure a backend +per currency. -Instances -:keywords: instance - The backend allows the user to run multiple instances of shops with - distinct business entities against a single backend. Each instance - uses its own bank accounts and key for signing contracts. It is - mandatory to configure a "default" instance. - - The “KEYFILE” option specifies the file containing the instance’s - private signing key. For example, use: +Auditor +^^^^^^^ - :: +FIXME: document here how to add an auditor to the list of +trusted auditors! - $ taler-config -s INSTANCE-default -o KEYFILE \ - -V '${TALER_CONFIG_HOME}/merchant/instace/default.key' - - The “NAME” option specifies a human-readable name for the - instance. For example, use: - - :: - - $ taler-config -s INSTANCE-default -o NAME \ - -V 'Kudos Inc.' - - - The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME” - options are discussed in Tipping visitors - -Accounts -:keywords: wire format - - In order to receive payments, the merchant backend needs to - communicate bank account details to the exchange. For this, the - configuration must include one or more sections named “ACCOUNT-name” - where ``name`` can be replaced by some human-readable word - identifying the account. For each section, the following options - should be provided: - - - The “URL” option specifies a ``payto://``-URL for the account of - the merchant. For example, use: - - :: - - $ taler-config -s ACCOUNT-bank -o NAME \ - -V 'payto://x-taler-bank/bank.demo.taler.net/4' - - - The “WIRE_RESPONSE” option specifies where Taler should store the - (salted) JSON encoding of the wire account. The file given will be - created if it does not exist. For example, use: - - :: - - $ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \ - -V '{$TALER_CONFIG_HOME}/merchant/bank.json' - - - For each ``instance`` that should use this account, you should set - ``HONOR_instance`` and ``ACTIVE_instance`` to YES. The first - option will cause the instance to accept payments to the account - (for existing contracts), while the second will cause the backend - to include the account as a possible option for new contracts. - - For example, use: - - :: - - $ taler-config -s ACCOUNT-bank -o HONOR_default \ - -V YES - $ taler-config -s ACCOUNT-bank -o ACTIVE_default \ - -V YES - - to use “account-bank” for the “default” instance. - - Note that additional instances can be specified using different - tokens in the section name instead of ``default``. .. _Sample-backend-configuration: Sample backend configuration ---------------------------- -:keywords: configuration +.. index:: configuration The following is an example for a complete backend configuration: @@ -570,24 +511,14 @@ The following is an example for a complete backend configuration: [MERCHANTDB-postgres] CONFIG = postgres:///donations - [INSTANCE-default] - KEYFILE = $DATADIR/key.priv - NAME = "Kudos Inc." - - [ACCOUNT-bank] - URL = payto://x-taler-bank/bank.demo.taler.net/4 - WIRE_RESPONSE = $DATADIR/bank.json - HONOR_default = YES - ACTIVE_default = YES - TALER_BANK_AUTH_METHOD = basic - USERNAME = my_user - PASSWORD = 1234pass - [merchant-exchange-trusted] + # FIXME: check this is up-to-date! EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 CURRENCY = KUDOS + [FIXME: add example for AUDITOR!] + Given the above configuration, the backend will use a database named ``donations`` within Postgres. @@ -604,8 +535,8 @@ them. Launching the backend --------------------- -:keywords: backend -:keywords: taler-merchant-httpd +.. index:: backend +.. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the merchant backend using: @@ -632,6 +563,37 @@ Please note that your backend is right now likely globally reachable. Production systems should be configured to bind to a UNIX domain socket or properly restrict access to the port. +.. _Instances: + +Instances +========= + +The backend allows the user to run multiple instances of shops with +distinct business entities against a single backend. Each instance +uses its own bank accounts and key for signing contracts. It is +mandatory to configure at least the "default" instance. + +Instances can be configured by POSTing the necessary requests to the +backend (possibly via a Web interface -- once we implement that). + +FIXME: more details on how to setup instances here! + + +Accounts +-------- + +The main configuration data that must be provided for each instance +is the bank account information. + +In order to receive payments, the merchant backend needs to +communicate bank account details to the exchange. + +The bank account information is provided in the form of +a ``payto://``-URL. + +FIXME: more details on how to setup accounts here! + + .. _Testing: Testing @@ -683,7 +645,7 @@ Run the test in the following way: $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL] The argument ``config`` given to ``-c`` points to the configuration file -and is optional – ``~/.config/taler.conf`` will be checked by default. +and is optional – ``^/.config/taler.conf`` will be checked by default. By default, the tool forks two processes: one for the merchant backend, and one for the exchange. The option ``-e`` (``-m``) avoids any exchange (merchant backend) fork, and just runs the generator against the @@ -745,7 +707,7 @@ Advanced topics Configuration format -------------------- -:keywords: configuration +.. index:: configuration In Taler realm, any component obeys to the same pattern to get configuration values. According to this pattern, once the component has @@ -819,7 +781,7 @@ configuration file used in our demos. See under ``deployment/config``. Using taler-config ------------------ -:keywords: taler-config +.. index:: taler-config The tool ``taler-config`` can be used to extract or manipulate configuration values; however, the configuration use the well-known INI @@ -859,42 +821,22 @@ compare: :: - $ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE - $ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE + $ taler-config -s PATHS \ + -o TALER_DATA_HOME + $ taler-config -f -s PATHS \ + -o TALER_DATA_HOME While the configuration file is typically located at ``$HOME/.config/taler.conf``, an alternative location can be specified to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c`` option. -.. _Merchant-key-management: - -Merchant key management ------------------------ - -:keywords: merchant key -:keywords: KEYFILE - -The option “KEYFILE” in the section “INSTANCE-default” specifies the -path to the instance’s private key. You do not need to create a key -manually, the backend will generate it automatically if it is missing. -While generally unnecessary, it is possible to display the corresponding -public key using the ``gnunet-ecc`` command-line tool: - -:: - - $ gnunet-ecc -p \ - $(taler-config -f -s INSTANCE-default \ - -o KEYFILE) - .. _Tipping-visitors: Tipping visitors ---------------- -:keywords: tipping +.. index:: tipping Taler can also be used to tip Web site visitors. For example, you may be running an online survey, and you want to reward those people that have @@ -904,118 +846,48 @@ how to setup the Taler merchant backend for tipping. There are four basic steps that must happen to tip a visitor. -.. _Configure-a-reserve-and-exchange-for-tipping: - -Configure a reserve and exchange for tipping -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:keywords: gnunet-ecc -:keywords: reserve key - -To tip users, you first need to create a reserve. A reserve is a pool of -money held in escrow at the Taler exchange. This is the source of the -funds for the tips. Tipping will fail (resulting in disappointed -visitors) if you do not have enough funds in your reserve! - -First, we configure the backend. You need to enable tipping for each -instance separately, or you can use an instance only for tipping. To -configure the “default” instance for tipping, use the following -configuration: - -:: - - [INSTANCE-default] - # this is NOT the tip.priv - KEYFILE = signing_key.priv - # replace the URL with the URL of the exchange you will use - TIP_EXCHANGE = https://exchange:443/ - # here put the path to the file created with "gnunet-ecc -g1 tip.priv" - TIP_RESERVE_PRIV_FILENAME = tip.priv - -Note that the KEYFILE option should have already been present for the -instance. It has nothing to do with the “tip.priv” file we created -above, and you should probably use a different file here. - -Instead of manually editing the configuration, you could also run: - -:: - - $ taler-config -s INSTANCE-default \ - -o TIP_RESERVE_PRIV_FILENAME \ - -V tip.priv - $ taler-config -s INSTANCE-default \ - -o TIP_EXCHANGE \ - -V https://exchange:443/ - -Next, to create the ``TIP_RESERVE_PRIV_FILENAME`` file, use: - -:: - - $ gnunet-ecc -g 1 \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) - -This will create a file with the private key that will be used to -identify the reserve. You need to do this once for each instance that is -configured to tip. - -Now you can (re)start the backend with the new configuration. +FIXME: write current explanation! .. _Fund-the-reserve: Fund the reserve -~~~~~~~~~~~~~~~~ - -:keywords: reserve -:keywords: close +^^^^^^^^^^^^^^^^ -To fund the reserve, you must first extract the public key from -“tip.priv”: +.. index:: reserve +.. index:: close -:: - - $ gnunet-ecc --print-public-key \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) - -In our example, the output for the public key is: +In our example, the output for the wire transfer subject is: :: QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG You now need to make a wire transfer to the exchange’s bank account -using the public key as the wire transfer subject. The exchange’s bank -account details can be found in JSON format at -“https://exchange:443//wire/METHOD” where METHOD is the respective wire -method (i.e. “sepa”). Depending on the exchange’s operator, you may also -be able to find the bank details in a human-readable format on the main -page of the exchange. +using the public key as the wire transfer subject. Make your wire transfer and (optionally) check at -“https://exchange:443/reserve/status/reserve_pub=QPE24X...” whether your -transfer has arrived at the exchange. +“https://exchange/reserves/QPE24X...” whether your transfer has arrived at the +exchange. Once the funds have arrived, you can start to use the reserve for tipping. -Note that an exchange will typically close a reserve after four weeks, -wiring all remaining funds back to the sender’s account. Thus, you -should plan to wire funds corresponding to a campaign of about two weeks -to the exchange initially. If your campaign runs longer, you should wire -further funds to the reserve every other week to prevent it from -expiring. +Note that an exchange will typically close a reserve after four weeks, wiring +all remaining funds back to the sender’s account. Thus, you should plan to +wire funds corresponding to a campaign of about two weeks to the exchange +initially. If your campaign runs longer, you should setup another reserve +every other week to ensure one is always ready. .. _Authorize-a-tip: Authorize a tip -~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^ -When your frontend has reached the point where a client is supposed to -receive a tip, it needs to first authorize the tip. For this, the -frontend must use the “/tip-authorize” API of the backend. To authorize -a tip, the frontend has to provide the following information in the body -of the POST request: +When your frontend has reached the point where a client is supposed to receive +a tip, it needs to first authorize the tip. For this, the frontend must use +the “/private/reserves/$RID/tip-authorize” API of the backend. To authorize a +tip, the frontend has to provide the following information in the body of the +POST request: - The amount of the tip @@ -1040,18 +912,19 @@ missconfigured instances or a lack of remaining funds for tipping. .. _Picking-up-of-the-tip: Picking up of the tip -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ -The wallet will POST a JSON object to the shop’s “/tip-pickup” handler. +The wallet will POST a JSON object to the shop’s “/tips/$TIP/pickup” handler. The frontend must then forward this request to the backend. The response generated by the backend can then be forwarded directly to the wallet. -.. _Generate-payments: +.. _Benchmarking: -Generate payments ------------------ +Benchmarking +------------ + +.. index:: testing database -testing database The merchant codebase offers the ``taler-merchant-benchmark`` tool to populate the database with fake payments. This tool is in charge of starting a merchant, exchange, and bank processes, and provide them all |