intro-bank-apis.rst (5981B)
1 ################################################ 2 Introduction to Taler (Core-)Banking Integration 3 ################################################ 4 5 This chapter provides an overview of the different ways that a bank or core 6 banking system can provide integration with GNU Taler. 7 8 9 Settlement Account Access 10 ######################### 11 12 To make a GNU Taler deployment possible, the exchange service needs API access 13 to a settlement bank account. The settlement account is used to fund digital 14 cash withdrawals into users' Taler wallets, as well as to pay out merchants 15 that deposited digital cash with the exchange. 16 17 The following two operations need to be supported by the settlement account: 18 19 1. Querying transactions on the settlement account. 20 2. Initiating payments (simple credit transfer). 21 22 Note that there is only **one** settlement account needed per Taler deployment. 23 There is no per-user settlement account. Thus, creating or managing bank 24 accounts is not a requirement. 25 26 A core banking system could directly provide the HTTP/REST APIs 27 consumed by the Taler exchange (:doc:`api-bank-integration`). Otherwise, an adapter (typically part 28 of the libeufin component) needs to be written. 29 30 31 Improved Withdrawal Process 32 ########################### 33 34 In principle, any typical account-based (core-)banking system can be used as 35 the underlying account-based financial layer for GNU Taler. 36 37 However, without extra support from the bank, withdrawals can be difficult for 38 unexperienced users. Thus to make sure that a Taler deployment can achieve 39 mass adoption from non-technical users, extra integration by the bank / core 40 banking system should be provided. 41 42 Withdrawals without any extra support from the core banking system require the 43 user to make a transaction to a particular bank account (i.e. the exchange's 44 settlement account) with a rather long cryptographic identifier in the subject. 45 This identifier is generated by the user's wallet when initiating a withdrawal 46 from the wallet application. If the user misspells the identifier, the payment 47 will be sent back automatically by the exchange. 48 49 However, until the wire transfer is successfully completed, the wallet has no 50 information about whether the transfer was already made by the user or if it 51 was even made correctly. This makes it hard to show accurate information to 52 the user about the status of withdrawing digital cash into their Taler wallet. 53 54 55 Withdrawal Bank-Integration API 56 =============================== 57 58 A core banking system can provide better support for GNU Taler withdrawals by 59 allowing users to initiate *Taler withdrawal operations* from their bank 60 account (e.g. in their banking app or online banking). A Taler withdrawal 61 operation has a unique identifier (chosen/generated by the core banking 62 system), called the WOPID (Withdrawal Operation Identifier). 63 64 The core banking system can provide a (public) API to access withdrawal 65 operations (:doc:`api-bank-integration`). 66 67 The wallet learns the WOPID and API address via a ``taler://withdraw/...`` 68 QR-Code or link. 69 70 The wallet generates the cryptographic identifiers required for the withdrawal, 71 allows the user to choose an exchange (the bank may suggest a default one!), 72 and then submits this information (chosen exchange, reserve public key) for the 73 respective WOPID to the bank-integration API. 74 75 The user can then confirm the withdrawal by completing the 2FA of 76 their bank account for the operation. (Alternatively, the user can abort the operation 77 in their banking client / 2FA app.) 78 79 Upon completion of the 2FA / confirmation step, the core banking system 80 initiates a credit transfer for the withdrawal operations (with the chosen 81 exchange as the creditor and the cryptographic identifier / reserve pub in the 82 subject). Afterwards, the withdrawal operation is marked as done. 83 84 The wallet can continuously query the status of the withdrawal operation (via 85 the API address and WOPID). 86 In the Taler wallet app, the user can now always see the accurate status of 87 their withdrawal operation (e.g. bank transfer done, aborted, confirmation/2FA 88 pending). 89 90 91 Payto-URI Integration 92 ===================== 93 94 When initiating a withdrawal from the Taler wallet, the wallet can generate a 95 payto:// link or QR code (see `RFC 8905 <https://www.rfc-editor.org/rfc/rfc8905.txt>`_) 96 with the payment information necessary to make a 97 credit transfer to the exchange's settlement account. 98 99 Banking apps may provide integration here simply by handling payto:// URIs. 100 101 Integration based on payto:// URIs prevents mistakes in typing the 102 cryptographic identifier and bank account number during withdrawals. However, 103 it still does not allow the wallet do accurately show the status of a 104 withdrawal to the user. 105 106 107 Future: Intent-Based Integration on Android 108 =========================================== 109 110 (This type of integration is currently not specified, but planned for the future.) 111 112 On the Android platform, applications can communicate via 113 `Intents <https://developer.android.com/guide/components/intents-filters>`_. 114 That would allow the Taler wallet to open a credit transfer dialog in a 115 supported banking app to fund a withdrawal. The banking app can send the 116 status of the credit transfer (confirmed/aborted by the user) back to the 117 wallet, which can then show more accurate status information about the 118 withdrawal to the user. 119 120 121 Integration for Merchants 122 ######################### 123 124 The Taler merchant backend has the option to connect to what 125 we call the :doc:`Bank Revenue API <api-bank-revenue>`. 126 127 A core banking system may provide this API to merchants that have a business 128 account at the that bank. The API provides read-only access to incoming 129 transactions on the merchant bank account. 130 131 It allows merchants to easily and automatically reconcile incoming bank 132 transfers from the Taler exchange's settlement account with the respective 133 Taler payments. Usually multiple Taler payments are aggregated into one larger 134 payment in the underlying banking layer.