commit e7abc4f2119c778a79983d49887a9426de6f0d25
parent ed58cbe6c34993272d40bf10d401042ab09fdc4b
Author: Florian Dold <florian@dold.me>
Date: Thu, 8 Feb 2024 15:42:05 +0100
draft intro to bank integration
Diffstat:
2 files changed, 106 insertions(+), 0 deletions(-)
diff --git a/core/index-bank-apis.rst b/core/index-bank-apis.rst
@@ -27,6 +27,7 @@ Bank RESTful APIs
.. toctree::
:maxdepth: 1
+ intro-bank-apis
api-corebank
api-bank-wire
api-bank-revenue
diff --git a/core/intro-bank-apis.rst b/core/intro-bank-apis.rst
@@ -0,0 +1,105 @@
+################################################
+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, the user experience for Taler
+withdrawals is not ideal.
+
+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, the wallet has no information about whether bank 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 (chose exchange, reserve public key) for the
+respective WOPID to the bank-integration API.
+
+The user can then confirm (or abort!) the withdrawal on their bank account.
+
+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 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. 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.
+
