diff options
Diffstat (limited to 'core/intro-bank-apis.rst')
-rw-r--r-- | core/intro-bank-apis.rst | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst new file mode 100644 index 00000000..f4307138 --- /dev/null +++ b/core/intro-bank-apis.rst @@ -0,0 +1,134 @@ +################################################ +Introduction to Taler (Core-)Banking Integration +################################################ + +This chapter provides an overview of the different ways that a bank or core +banking system can provide integration with GNU Taler. + + +Settlement Account Access +######################### + +To make a GNU Taler deployment possible, the exchange service needs API access +to a settlement bank account. The settlement account is used to fund digital +cash withdrawals into users' Taler wallets, as well as to pay out merchants +that deposited digital cash with the exchange. + +The following two operations need to be supported by the settlement account: + +1. Querying transactions on the settlement account. +2. Initiating payments (simple credit transfer). + +Note that there is only **one** settlement account needed per Taler deployment. +There is no per-user settlement account. Thus, creating or managing bank +accounts is not a requirement. + +A core banking system could directly provide the HTTP/REST APIs +consumed by the Taler exchange (:doc:`api-bank-integration`). Otherwise, an adapter (typically part +of the libeufin component) needs to be written. + + +Improved Withdrawal Process +########################### + +In principle, any typical account-based (core-)banking system can be used as +the underlying account-based financial layer for GNU Taler. + +However, without extra support from the bank, withdrawals can be difficult for +unexperienced users. Thus to make sure that a Taler deployment can achieve +mass adoption from non-technical users, extra integration by the bank / core +banking system should be provided. + +Withdrawals without any extra support from the core banking system require the +user to make a transaction to a particular bank account (i.e. the exchange's +settlement account) with a rather long cryptographic identifier in the subject. +This identifier is generated by the user's wallet when initiating a withdrawal +from the wallet application. If the user misspells the identifier, the payment +will be sent back automatically by the exchange. + +However, until the wire transfer is successfully completed, the wallet has no +information about whether the transfer was already made by the user or if it +was even made correctly. This makes it hard to show accurate information to +the user about the status of withdrawing digital cash into their Taler wallet. + + +Withdrawal Bank-Integration API +=============================== + +A core banking system can provide better support for GNU Taler withdrawals by +allowing users to initiate *Taler withdrawal operations* from their bank +account (e.g. in their banking app or online banking). A Taler withdrawal +operation has a unique identifier (chosen/generated by the core banking +system), called the WOPID (Withdrawal Operation Identifier). + +The core banking system can provide a (public) API to access withdrawal +operations (:doc:`api-bank-integration`). + +The wallet learns the WOPID and API address via a ``taler://withdraw/...`` +QR-Code or link. + +The wallet generates the cryptographic identifiers required for the withdrawal, +allows the user to choose an exchange (the bank may suggest a default one!), +and then submits this information (chosen exchange, reserve public key) for the +respective WOPID to the bank-integration API. + +The user can then confirm the withdrawal by completing the 2FA of +their bank account for the operation. (Alternatively, the user can abort the operation +in their banking client / 2FA app.) + +Upon completion of the 2FA / confirmation step, the core banking system +initiates a credit transfer for the withdrawal operations (with the chosen +exchange as the creditor and the cryptographic identifier / reserve pub in the +subject). Afterwards, the withdrawal operation is marked as done. + +The wallet can continuously query the status of the withdrawal operation (via +the API address and WOPID). +In the Taler wallet app, the user can now always see the accurate status of +their withdrawal operation (e.g. bank transfer done, aborted, confirmation/2FA +pending). + + +Payto-URI Integration +===================== + +When initiating a withdrawal from the Taler wallet, the wallet can generate a +payto:// link or QR code (see `RFC 8905 <https://www.rfc-editor.org/rfc/rfc8905.txt>`_) +with the payment information necessary to make a +credit transfer to the exchange's settlement account. + +Banking apps may provide integration here simply by handling payto:// URIs. + +Integration based on payto:// URIs prevents mistakes in typing the +cryptographic identifier and bank account number during withdrawals. However, +it still does not allow the wallet do accurately show the status of a +withdrawal to the user. + + +Future: Intent-Based Integration on Android +=========================================== + +(This type of integration is currently not specified, but planned for the future.) + +On the Android platform, applications can communicate via +`Intents <https://developer.android.com/guide/components/intents-filters>`_. +That would allow the Taler wallet to open a credit transfer dialog in a +supported banking app to fund a withdrawal. The banking app can send the +status of the credit transfer (confirmed/aborted by the user) back to the +wallet, which can then show more accurate status information about the +withdrawal to the user. + + +Integration for Merchants +######################### + +The Taler merchant backend has the option to connect to what +we call the :doc:`Bank Revenue API <api-bank-revenue>`. + +A core banking system may provide this API to merchants that have a business +account at the that bank. The API provides read-only access to incoming +transactions on the merchant bank account. + +It allows merchants to easily and automatically reconcile incoming bank +transfers from the Taler exchange's settlement account with the respective +Taler payments. Usually multiple Taler payments are aggregated into one larger +payment in the underlying banking layer. |