[taler-docs] branch master updated: draft intro to bank integration

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new e7abc4f2 draft intro to bank integration
e7abc4f2 is described below

commit e7abc4f2119c778a79983d49887a9426de6f0d25
Author: Florian Dold <florian@dold.me>
AuthorDate: Thu Feb 8 15:42:05 2024 +0100

    draft intro to bank integration
---
 core/index-bank-apis.rst |   1 +
 core/intro-bank-apis.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)

diff --git a/core/index-bank-apis.rst b/core/index-bank-apis.rst
index ad3bae1c..f108df32 100644
--- 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
new file mode 100644
index 00000000..df14a688
--- /dev/null
+++ 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.
+

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.