7. GNU Taler bank manual

7.1. Introduction

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

7.1.2. About this manual

This manual documents how the demonstrator bank interoperates with the other GNU Taler components. The demonstrator bank implements a simple closed banking system for the purpose of illustrating how GNU Taler works in the Taler demo. It could also be used as a starting point for a local/regional currency. Finally, “real” banks might use it as a reference implementation for a tight integration with the GNU Taler wallet.

7.2. Reference

7.2.1. Bank-Wallet interaction

The HTTP status code 202 Accepted can be used by the bank website to trigger operations in the user agent. The operation is determined by the X-Taler-Operation header. The following operations are understood:

create-reserve

Ask the Taler wallet to create a reserve and call back the bank with the reserve public key. The following headers are mandatory:

  • X-Taler-Callback-Url: URL that the wallet will visit when the reserve was created and the user has selected an exchange.
  • X-Taler-Wt-Types: JSON-encoded array of wire transfer types that this bank supports.
  • X-Taler-Amount: The amount that will be transferred to the reserve.
  • X-Taler-Sender-Wire: JSON-encoded wire account details of the sender, that is the user that is currently logged in with the bank and creates the reserve.

The following header is optional:

  • X-Taler-Suggested-Exchange: Exchange that the bank recommends the customer to use. Note that this is a suggestion and can be ignored by the wallet or changed by the user.

On successful reserve creation, the wallet will navigate to the callback URL (effectively requesting it with a GET) with the following additional request parameters:

  • exchange: The URL of the exchange selected by the user
  • wire_details: The wire details of the exchange.
  • reserve_pub: The reserve public key that the bank should transmit to the exchange when transmitting the funds.
confirm-reserve

To secure the operation, the (demo) bank then shows a “CAPTCHA page” – a real bank would instead show some PIN entry dialog or similar security method – where the customer can finally prove she their identity and thereby confirm the withdraw operation to the bank.

Afterwards, the bank needs to confirm to the wallet that the user completed the required steps to transfer funds to an exchange to establish the reserve identified by the X-Taler-Reserve-Pub header.

This does not guarantee that the reserve is already created at the exchange (since the actual money transfer might be executed asynchronously), but it informs that wallet that it can start polling for the reserve.

7.2.2. Bank-Exchange interaction

The interaction between a bank and the exchange happens in two situations: when a wallet withdraws coins, and when the exchange pays a merchant.

Withdraw

Once a withdrawal operation with the wallet has been confirmed, the the bank must wire transfer the withdrawn amount from the customer account to the exchange’s. After this operation is done, the exchange needs to be informed so that it will create the reserve.

For the moment, the bank will use the exchange’s /admin/add/incoming API, providing those arguments it got along the X-Taler-Callback-Url URL. (In the future, the exchange will poll for this information.) However, the bank will define two additional values for this API: execution_date (a operation’s timestamp), and transfer_details (just a “seed” to make unique the operation). See https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions.

The polling mechanism is possbile thanks to the /history API provided by the bank. The exchange will periodically use this API to see if it has received new wire transfers; upon receiving a new wire transfer, the exchange will automatically create a reserve and allow the money sender to withdraw.

GET /history

Ask the bank to return a list of money transactions related to a caller’s bank account.

  • auth a string indicating the authentication method to use; only "basic" value is accepted so far. The username and password credentials have to be sent along the HTTP request headers. Namely, the bank will look for the following two headers: X-Taler-Bank-Username and X-Taler-Bank-Password, which will contain those plain text credentials.
  • delta returns the first N records younger (older) than start if +N (-N) is specified.
  • start according to delta, only those records with row id strictly greater (lesser) than start will be returned. This argument is optional; if not given, delta youngest records will be returned.
  • direction optional argument taking values debit or credit, according to the caller willing to receive both incoming and outgoing, only outgoing, or only incoming records
  • account_number optional argument indicating the bank account number whose history is to be returned. If not given, then the history of the calling user will be returned

Exchange pays merchant

To allow the exchange to send payments to a merchant, the bank exposes the /admin/add/incoming API to exchanges.

POST /admin/add/incoming

Ask the bank to transfer money from the caller’s account to the receiver’s.

  • auth a string indicating the authentication method to use; only "basic" value is accepted so far. The username and password credentials have to be sent along the HTTP request headers. Namely, the bank will look for the following two headers: X-Taler-Bank-Username and X-Taler-Bank-Password, which will contain those plain text credentials.
  • amount a JSON object complying to the Taler amounts layout. Namely, this object must contain the following fields: value (number), fraction (number), and currency (string).
  • exchange_url a string indicating the calling exchange base URL. The bank will use this value to define wire transfers subject lines.
  • wtid a alphanumeric string that uniquely identifies this transfer at the exchange database. The bank will use this value too to define wire transfers subject lines. Namely, subject lines will have the following format: 'wtid exchange_url'.
  • debit_account number indicating the exchange bank account. NOTE: this field is currently ignored, as the bank can retrieve the exchange account number from the login credentials. However, in future release, an exchange could have multiple account at the same bank, thereby it will have the chance to specify any of them in this field.
  • credit_account bank account number that will receive the transfer. Tipically the merchant account number.