diff options
Diffstat (limited to 'libeufin')
36 files changed, 1270 insertions, 5188 deletions
diff --git a/libeufin/api-common.rst b/libeufin/api-common.rst deleted file mode 100644 index 58ae7e37..00000000 --- a/libeufin/api-common.rst +++ /dev/null @@ -1,93 +0,0 @@ -==================================== -Common LibEuFin HTTP API Conventions -==================================== - - -Contact details -^^^^^^^^^^^^^^^ - -.. ts:def:: EmailAddress - - type EmailAddress = string; - -.. ts:def:: PhoneNumber - - type PhoneNumber = string; - -Phone numbers should start with the ``+`` symbol and the country code. - -Ratios and Fees -^^^^^^^^^^^^^^^ - -.. ts:def:: LibeufinNumber - - type LibeufinNumber = number; - -**Note:** this quantity is normally enforced to have at most -two decimal digits. The reason is to preserve the 2-decimal -digits policy of the `Amount` type, as `LibeufinNumber` is used -to multiply `Amount`. - -Amounts -^^^^^^^ - -.. ts:def:: Amount - - type Amount = string; - -Amounts have the ``$currency:X.Y`` format, where the -fractional part is optional and may contain at most two -digits. - -Permissions -^^^^^^^^^^^ - -This type epresses which permissions for a subject -apply on a resource. - -.. ts:def:: LibeufinPermission - - interface LibeufinPermission { - subjectType: string; - subjectId: string; - resourceType: string; - resourceId: string; - permissionName: string - } -Fetch params -^^^^^^^^^^^^ - -.. _fetch-params: - -.. ts:def:: FetchParams - - interface FetchParams { - - // Because transactions are delivered by banks in "batches", - // then every batch can have different qualities. This value - // lets the request specify which type of batch ought to be - // returned. Currently, the following two type are supported: - // - // 'report': typically includes only non booked transactions. - // 'statement': typically includes only booked transactions. - level: "report" | "statement" | "all"; - - // This type indicates the time range of the query. - // It allows the following values: - // - // 'latest': retrieves the last transactions from the bank. - // If there are older unread transactions, those will *not* - // be downloaded. - // - // 'all': retrieves all the transactions from the bank, - // until the oldest. - // - // 'previous-days': currently *not* implemented, it will allow - // the request to download transactions from - // today until N days before. - // - // 'since-last': retrieves all the transactions since the last - // time one was downloaded. - // - rangeType: "latest" | "all" | "previous-days" | "since-last"; - }; diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst deleted file mode 100644 index 2ec90322..00000000 --- a/libeufin/api-nexus.rst +++ /dev/null @@ -1,1060 +0,0 @@ -.. target audience: core developer - -Nexus API -########### - -.. contents:: Table of Contents - -HTTP API -======== - -In the current version, the API calls are only available to -the superuser, when no authorization condition is explictly stated. - -Configuration -------------- - - -Returns configuration values currently used by Nexus. -This call is unauthenticated. - -.. http:get:: {nexusBase}/config - - **Response:** - - .. ts:def:: ConfigResponse - - interface ConfigResponse { - - // nexus version, X.Y.Z format. - version: string; - } - - -Authentication --------------- - -Currently every request made to nexus must be authenticated using the *HTTP -basic auth* mechanism. - -Other authentication mechanisms (e.g. OpenID Connect) might -be supported in the future. - -User Management ---------------- - -.. http:get:: {nexusBase}/user - - Get information about the current user. The username carried - along the HTTP basic auth points at the user to be shown. - - **Response:** - - .. ts:def:: GetUserResponse - - interface UserResponse { - - // User name - username: string; - - // Is this a super user? - superuser: Boolean; - } - -.. http:post:: {nexusBase}/users/{userName}/password - - Change password of the ``{userName}`` user. The call is - available to any superuser on any username. - - **Request:** - - .. code-block:: ts - - interface UserChangePassword { - newPassword: string; - } - - **Response:** - - :http:statuscode:`200 OK`: The password was successfully changeD. - - -.. http:post:: {nexusBase}/users - - Create a new user. Only a superuser can call this API. - - **Request:** - - The body is a `User` object. - - **Response:** - - :http:statuscode:`409 Conflict`: Username is not available. - - **Details:** - - .. ts:def:: User - - interface User { - - // User name - username: string; - - // Initial password - password: string; - } - - -.. http:get:: {nexusBase}/users - - Return the list of all users. - - **Response:** - - .. ts:def:: UsersResponse - - interface UsersResponse { - users: UserResponse[]; - } - -.. _nexus-permissions-api: - -Permissions API ---------------- - -The permissions API manages authorization of access of subjects -(usually users) to resources. - -Permissions are modeled a set of ``(subject, resource, permission)`` -triples. Subjects and resources consist of a type and an identifier. - -Superusers are not subject to further permission checks, they are -allowed to do any operation. - -The following subject types are currently supported: - -* ``user``: An authenticated user. The subject ID - is interpreted as the user ID. - -The following permissions are currently defined: - -* ``facade.talerWireGateway.history``: Allows querying the - transaction history through a Taler wire gateway facade. -* ``facade.talerWireGateway.transfer``: Allows creating payment - initiations to transfer money via a Taler wire gateway facade. - -The following resource IDs are currently supported: - -* ``facade``: A LibEuFin facade. The resource ID is interpreted - as the facade name. - -* ``bank-account``: A Nexus bank account, currently used in - `scheduled tasks <nexus-task_>`_ of type ``fetch`` and ``submit``. - -.. http:get:: {nexusbase}/permissions - - Lists all permissions. - - **Response** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - permissions: LibeufinPermission[]; - } - -.. http:post:: {nexusbase}/permissions - - Modifies permissions. - - **Request** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - action: "grant" | "revoke"; - permission: LibeufinPermission; - } - - **Response** - - The response is an empty JSON object. - - -Test API --------- - -.. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type} - - This call allows tests to **directly** give Nexus a Camt document. After - the processing, all the payment(s) details should be ingested as if the - Camt came normally from a bank / the Sandbox. ``acctid`` must match the - label of a locally imported bank account, and ``type`` for now can only be - ``C53``. - - **Response** - - The successful case should respond with a ``200 OK`` and an empty JSON body. - -Bank Accounts -------------- - -Neuxs maintains a copy of the bank account transaction history and -balance information, manages payment initiations of the account and -tracks the initiations of payments. - -.. http:get:: {nexusBase}/bank-accounts - - **Response:** - - A list of `BankAccount` objects that belong to the requester. - The list is held in the ``accounts`` field. - - .. ts:def:: BankAccount - - interface BankAccount { - // mnemonic name identifying this bank account. - nexusBankAccountId: string; - // IBAN - iban: string; - // BIC - bic: string; - // Legal subject owning the account. - ownerName: string; - } - - -.. http:get:: {nexusBase}/bank-accounts/{my-acct} - - Get basic information about the bank account named ``my-acct``. - - .. ts:def:: BankAccountInfoWithBalance - - interface BankAccountInfoWithBalance { - // ID number of the database row being the default bank connection - // of ``my-acct``. - defaultBankConnection: number; - // Payto://-URI of ``my-acct``. - accountPaytoUri: string; - // Balance of ``my-acct`` as it was downloaded from the bank - // along the last Camt document. A human-readable message - // will inform the requester, should this value not be found. - lastSeenBalance: string; - } - -.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit - - Asks nexus to submit one prepare payment at the bank. - - :http:statuscode:`404 Not found`: the unique identifier **or** - the bank connection could not be found in the system - - -.. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid} - - Asks the status of payment ``$uuid``. - - **Response:** - - .. ts:def:: PaymentStatus - - interface PaymentStatus { - // Can be "BOOK" or "PDNG" ('pending'). - status: string; - - // Payment unique identifier - paymentInitiationId: string; - - // True for submitted payments - submitted: boolean; - - // Creditor IBAN - creditorIban: string; - - // Creditor BIC - creditorBic: string; - - // Creditor legal name - creditorName: string; - - // Amount - amount: string; - - // Subject - subject: string; - - // Date of submission (in dashed form YYYY-MM-DD) - submissionDate: string; - - // Date of preparation (in dashed form YYYY-MM-DD) - preparationDate: string; - } - -.. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations - - Asks nexus the list of initiated payments. At this stage of the API, - **all** is returned: submitted and non-submitted payments. - - **Response** - - .. ts:def:: InitiatedPayments - - interface InitiatedPayments { - - // list of all the initiated payments' UID. - initiatedPayments: PaymentStatus[]; - } - - -.. http:post:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations - - Ask nexus to prepare instructions for a new payment. - Note that ``my-acct`` is the bank account that will be - **debited** after this operation. - - **Request:** - - .. ts:def:: PreparedPaymentRequest - - interface PreparedPaymentRequest { - // IBAN that will receive the payment. - iban: string; - // BIC hosting the IBAN. - bic: string; - // Legal subject that will receive the payment. - name: string; - // payment subject. - subject: string; - // amount, in the format CURRENCY:XX.YY - amount: string - } - - **Response:** - - .. ts:def:: PreparedPaymentResponse - - interface PreparedPaymentResponse { - - // Opaque identifier to be communicated when - // the user wants to submit the payment to the - // bank. - uuid: string; - } - -.. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions - - Nexus will download bank transactions using the given connection. - - **Request:** - - Refer to :ref:`FetchParams <fetch-params>` for - ``level`` and ``rangeType`` specifications. - - .. ts:def:: CollectedTransaction - - interface CollectedTransaction { - level: string; - rangeType: string; - // Bank connection to use. Uses the default bank connection, - // when not given. - bankConnection: string?; - } - - **Response:** - - .. code-block:: ts - - interface NewTransactions { - // How many transactions are new to Nexus. - newTransactions: number; - // How many transactions got downloaded by the request. - // Note that a transaction can be downloaded multiple - // times but only counts as new once. - downloadedTransactions: number; - } - - :http:statuscode:`500 Internal Server Error`: Nexus itself had a problem - along the operation, and not the bank. - - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions - - Shows all the transactions fetched for ``{acctid}``. - - **Query parameters:** - - **Response:** A object with a unique field named ``transactions`` - that contains a list of `Transaction` objects. - - .. ts:def:: Transaction - - interface Transaction { - - // money moved by the transaction - amount: string; - - // CRDT or DBIT - creditDebitIndicator: string - - // Two of the most used values are BOOK, or PENDING - status: string; - - // FIXME - bankTransactionCode: string; - - // FIXME - valueDate: string; - - // When this payment got booked. In the form YYYY-MM-DD - bookingDate: string; - - // FIXME - accountServicerRef: string; - - // FIXME - batches: { - // list of batched transactions - batchTransactions: BatchedTransaction[]; - }; - } - - .. ts:def:: BatchedTransaction - - interface BatchedTransaction { - // FIXME - amount: string; - // FIXME - creditDebitIndicator: string; - // FIXME - details { - debtor: { - name: string; - }; - debtorAccount: { - iban: string; - }; - // Missing, when the payment is DBIT. - debtorAgent: { - bic: string; - }; - creditor: { - name: string; - }; - creditorAccount: { - iban: string; - }; - // Missing, when the payment is CRDT. - creditorAgent: { - iban: string; - }; - // FIXME - endToEndId: string; - // FIXME - unstructuredRemittanceInformation: string; - } - } - -Scheduling API --------------- - -.. http:post:: {nexusBase}/bank-accounts/{acctid}/schedule - - This endpoint allows the caller to define a recurrent - execution of a task. - - **Request** - - .. ts:def:: ScheduleTask - - interface ScheduleTask { - // Name to assign to the task being created. - name: string; - - // a Unix-compatible cron pattern representing - // the frequency of execution of this task. - cronspec: string; - - // Can take values "fetch" (to download the history - // of the requester's bank account) or "submit" (to submit - // any initiated payment associated to the requester's - // bank account). - type: string; - - // Currently only used for "fetch" operations but required - // for any type of task. Whatever value "submit" tasks pass - // here, it is not going to be consumed by Nexus. Typically, - // submit tasks pass FetchParams with all of its fields set - // as null. - params: FetchParams; - } - - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} - - Shows ``taskId`` state. - - .. _nexus-task: - - **Response** - - .. ts:def:: NexusTask - - // This object is a mere reflection of - // what the Nexus database keeps to implement - // the scheduling feature. - - interface NexusTask { - // The resource being impacted by this operation. - // Typically a (Nexus) bank account being ``fetch``ed - // or whose payments are ``submit``ted. In this cases, - // this value is the "bank-account" constant. - resourceType: string; - // Name of the resource. In case of "bank-account", that - // is the name under which the bank account was imported - // from the bank. - resourceId: string; - // Task name, equals 'taskId' - taskName: string; - // Values allowed are "fetch" or "submit". - taskType: string; - // FIXME: describe. - taskCronSpec: string; - // Only meaningful for "fetch" types. - taskParams: FetchParams; - // Timestamp in secons when the next iteration will run. - nextScheduledExecutionSec: number; - // Timestamp in seconds when the previous iteration ran. - prevScheduledExecutionSec: number; - } - - -.. http:delete:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} - - This call deletes the task associated to ``taskId``. - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule - - Shows all the scheduled tasks from ``acctid``. - - **Response** - - .. ts:def:: TaskCollection - - interface TaskCollection { - - // This field can contain *multiple* objects of the type sampled below. - schedule: { - - 'task-name': { - cronspec: string; - type: "fetch" | "submit"; - params: FetchParams; - } - } - } - - -Bank Connections ----------------- - -Bank connections connect the local Nexus bank account to the bank. - -.. http:post:: <nexus>/bank-connections - - Activate a new bank connection for the requesting user. - - **Request:** - - This request can accept two formats, depending on whether a - new bank connection is being made, or a connection backup is - being restored. - - - This type allows the creation of new bank accounts. - - .. _new-conn: - - .. ts:def:: NewBankConnection - - interface NewBankConnection { - - source: string; // only "new" allowed - - // connection name. - name: string; - - // type of the connection to make: "ebics" for example. - type: string; - - // Strictly dependent from the connection type. - data: any; - } - - This type allows to restore a previously made bank connection. - - .. _restore-conn: - - .. ts:def:: BankConnectionRestore - - interface BankConnectionRestore { - - source: "backup"; - - // connection name. - name: string; - - // Backup data, as typically returned by the - // "../export-backup" API. - backup: any; - - passphrase?: string; - } - - The following examples show the EBICS types for creating and - restoring a connection. - - This type is found in the ``data`` field of `NewBankConnection <new-conn_>`_. - - .. _ebics-new-conn: - - .. ts:def:: EbicsNewConnection - - interface EbicsNewConnection { - userID: string, - partnerID: string, - hostID: string, - ebicsURL: string, - systemID?: string - } - - This type is found in the ``backup`` field of `BankConnectionRestore <restore-conn_>`_. - - .. ts:def:: EbicsBackup - - interface EbicsBackup { - type: string, // constant to "ebics" - userID: string, - partnerID: string, - hostID: string, - ebicsURL: string, - - // The following three values are the EBICS private keys. - authBlob: string, - encBlob: string, - sigBlob: string - } - - **Response:** - - :http:statuscode:`406 Not acceptable`: a connection with the - requested name already exists for this user. - -.. http:post:: {nexusBase}/bank-connections/delete-connection - - **Request:** - - .. ts:def:: BankConnectionDeletion - - interface BankConnectionDeletion { - // label of the bank connection to delete - bankConnectionId: string; - } - -.. http:get:: {nexusBase}/bank-connections - - List available bank connections. - - **Response** - - A JSON object whose ``bankConnections`` element is a list of the following type: - - .. ts:def:: BankConnection - - interface BankConnection { - - // connection type. For example "ebics". - type: string; - - // connection name as given by the user at - // the moment of creation. - name: string; - } - - -.. http:get:: {nexusBase}/bank-connections/{connId} - - Get information about one bank connection. - - .. ts:def:: BankConnectionInfo - - interface BankConnectionInfo { - type: string; - owner: string; - // if true, this connection can be used to communicate - // with the bank. - ready: boolean; - // Depends on the type. - details: any; - } - - For example, the following type occupies the ``details`` - field for EBICS connections. - - .. ts:def:: EbicsConnectionInfo - - interface EbicsConnectionInfo { - ebicsUrl: string; - ebicsHostId: string; - partnerId: string; - userId: string; - } - -.. http:post:: {nexusBase}/bank-connections/{connId}/connect - - Initialize the connection by talking to the bank. For EBICS - connections, this endpoint causes Nexus to submit its own keys - and download the bank's. That however **still** requires the - user to send the public keys to the bank via post, in order - to start operating. - -.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup - - Make a passphrase-encrypted backup of this connection. - -.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts - - Update accounts that are accessible via this bank connection. - After this operation, Nexus has stored the names of each bank - account, under ``connId``, that the bank communicated. - - Note: after this operation, Nexus **still** needs to - `assign each bank account a local name <import-account_>`_ , - in order to start operating. - -.. _import-account: - -.. http:post:: {nexusBase}/bank-connections/{connId}/import-account - - Import a bank account provided by the connection into the Nexus. - This operation assigns a local name to one bank account that was - downloaded from the bank. - - If no Nexus bank account with the ID ``nexusBankAccountId`` exists, - a new one will be created, and it will have ``connId`` as the - default bank connection. - - If an existing local bank account whose ID equals ``nexusBankAccountId`` - already exists, this call fails if ``offeredAccountId`` and ``nexusBankAccountId`` - have different IBANs. If instead the IBAN is the same, this call merely - associates ``offeredAccountId`` to ``nexusBankAccountId`` internally - in the database without changing ``nexusBankAccountId`` default connection. - - .. ts:def:: ImportBankAccount - - interface ImportBankAccount { - - // Identifier for the bank account, as returned by /accounts - // of the bank connection. - offeredAccountId: string; - - // Nexus-local identifier for the bank account. - nexusBankAccountId: string; - } - - **Response:** - - :http:statuscode:`409 Conflict`: ``nexusBankAccountId`` exists already but - its IBAN is different from the one carried by ``offeredAccountId``. - -.. http:get:: {nexusBase}/bank-connections/{connId}/accounts - - List the bank accounts that this bank connection provides access to. - - **Response:** - - The response is a JSON object whose ``accounts`` field is a list of the - following type. - - .. ts:def:: OfferedBankAccount - - interface OfferedBankAccount { - - // Unique identifier for the offered account - offeredAccountId: string; - - // IBAN of the offered account - iban: string; - - // BIC of the account's financial institution - bic: string; - - // Account owner name - ownerName: string; - - // If the account has been imported, - // this field contains the ID of the - // Nexus bank account associated with it, - // null otherwise. - nexusBankAccountId: string | null; - } - - -.. http:get:: <nexus>/bank-connections/{connId}/messages - - List *some* details of all the ISO2022 messages gotten from - the bank. - - **Response:** - - The response is a JSON object whose ``bankMessages`` field - is a list of the following type. - - .. code-block:: ts - - interface BankMessageInfo { - - // the message type, typically how the containing layer - // (Ebics, for example) would label this information. For - // Camt.053 types, this value is "C53". - code: string; - - // the unique identifier of the message. - messageId: string; - - // bytes length of the message. - length: number; - } - -.. http:get:: <nexus>/bank-connections/{connId}/messages/{msgId} - - Return the ISO20022 XML corresponding to ``msgId``. - - -Facades -------- - -.. http:get:: <nexus>/facades/{fcid} - - **Response:** A `FacadeShowInfo` whose name is ``fcid``. - -.. http:get:: <nexus>/facades - - List available facades that belong to the requesting user. - - **Response:** A list of the following elements: - -.. ts:def:: FacadeShowInfo - - interface FacadeShowInfo { - - // Name of the facade, same as the "fcid" parameter. - name: string; - - // Type of the facade. - // For example, "taler-wire-gateway". - type: string; - - // Bas URL of the facade. - baseUrl: string; - - // details depending on the facade type. - config: any; - } - - For "taler-wire-gateway" and "anastasis" facades, - ``config`` contains the following type: - - .. ts:def:: TalerAnastasisFacadeState - - interface TalerFacadeState { - // Bank connection this facade relies on. - bankConnection: string; - // (Nexus local) bank account associated to this facade. - bankAccount: string; - // Whether the facade seeks reports or statements from the bank. - reserveTransferLevel?: string; - currency?: string; - } - -.. http:delete:: {nexus}/facades/{fcid} - - Deletes a facade. - -.. http:post:: {nexus}/facades - - Creates a new facade. - - **Request:** - - .. code-block:: ts - - interface FacadeInfo { - // Name of the facade, same as the "fcid" parameter. - name: string; - - // Type of the facade. - // For example, "taler-wire-gateway" or "anastasis". - type: string; - - // Bank accounts that the facade has read/write access to. - bankAccountsRead?: string[]; - bankAccountsWrite?: string[]; - - // Bank connections that the facade has read/write access to. - bankConnectionsRead?: string[]; - bankConnectionsWrite?: string[]; - - // Facade-specific configuration details. Only the - // following type is available. - config: TalerAnastasisFacadeState; - } - -Bank Connection Protocols -------------------------- - -.. http:get:: {nexus}/bank-connection-protocols - - Lists supported bank connection protocols. - -.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host - - Check if Nexus can talk to an EBICS host. - This doesn't create a new connection in the database, - and is useful during setup when the user hasn't entered - the full details for the connection yet. - - .. ts:def:: EbicsHostTestRequest - - interface EbicsHostTestRequest { - ebicsBaseUrl: string; - ebicsHostId: string; - } - - -EBICS-specific APIs -------------------- - -The following endpoints are only available for EBICS bank connections. -They are namespaced under the ``/ebics/`` sub-resource. - -.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/download/{msg} - - .. warning:: - - Use with care. Typically only necessary for testing and debugging. - - Perform an EBICS download transaction of type ``msg``. - This request will not affect any bank account or other state - in Nexus database. It will just make a request to the bank - and return the answer. - -Anastasis API. --------------- - -This is a read-only API offering a view over *only* the incoming -transactions of a bank account. The name comes from the use in -`Anastasis <https://www.anastasis.lu>`_. - -.. http:get:: ${BASE_URL}/history/incoming - - Returns a list of transactions made to the customer. - - Transactions are identified by a numeric identifier, - that reflects the order in which Nexus downloaded each - transaction from the bank. - - The list of returned transactions is determined by a row - ID *starting point* and a signed non-zero integer *delta*: - - * If *delta* is positive, returns a list of up to *delta* - transactions (all matching the filter criteria) strictly - **after** the starting point. The transactions are sorted - in **ascending** order of the row ID. - * If *delta* is negative, return a list of up to *-delta* - transactions (all matching the filter criteria) strictly - **before** the starting point. The transactions are sorted - in **descending** order of the row ID. - - If *starting point* is not explicitly given, it defaults to: - - * A value that is **smaller** than all other row IDs if *delta* - is **positive**. - * A value that is **larger** than all other row IDs if *delta* - is **negative**. - - **Request** - - :query start: *Optional.* - Row identifier to explicitly set the *starting point* of the query. - :query delta: - The *delta* value that determines the range of the query. - :query long_poll_ms: *Optional.* If this parameter is specified and the - result of the query would be empty, Nexus will wait up to ``long_poll_ms`` - milliseconds for new transactions that match the query to arrive and only - then send the HTTP response. A client must never rely on this behavior, as - Nexus may return a response immediately or after waiting only a fraction - of ``long_poll_ms``. - - **Response** - - :http:statuscode:`200 OK`: JSON object of type `IncomingHistory`. - - :http:statuscode:`400 Bad request`: Request malformed. Nexus replies - with an `ErrorDetail` object. - - :http:statuscode:`401 Unauthorized`: Authentication failed, likely - the credentials are wrong. - - :http:statuscode:`404 Not found`: The endpoint is wrong or the user - name is unknown. Nexus replies with an `ErrorDetail` object. - - .. ts:def:: IncomingHistory - - interface IncomingHistory { - - // Array of incoming transactions. - incoming_transactions : IncomingBankTransaction[]; - - } - - .. ts:def:: IncomingBankTransaction - - interface IncomingBankTransaction { - - // Opaque identifier of the returned record. - row_id: SafeUint64; - - // Date of the transaction. - date: Timestamp; - - // Amount transferred. - amount: Amount; - - // Payto URI to identify the receiver of funds. - // Typically an exchange's bank accounts. - credit_account: string; - - // Payto URI to identify the sender of funds. - debit_account: string; - - // subject of the incoming payment. - subject: string; - } - -Reaching the facade -------------------- - -Once a facade with name ``fcid`` and type ``ftype`` has been -created, all its endpoints become offered by the following base -URL: - -.. code-block:: console - - $NEXUS_URL/facades/$fcid/$ftype - -For example, a ``taler-wire-gateway`` facade named ``foo`` will -offer its endpoints under - -.. code-block:: console - - https://nexus.example.com/facades/foo/taler-wire-gateway/ diff --git a/libeufin/api-sandbox-future.rst b/libeufin/api-sandbox-future.rst deleted file mode 100644 index 06dfc682..00000000 --- a/libeufin/api-sandbox-future.rst +++ /dev/null @@ -1,135 +0,0 @@ -Future Sandbox API -################## - -Resources. -^^^^^^^^^^ - -Sandbox serves the following resources: - - - Demobanks. - - Bank accounts. - - Subscribers. - - Transactions. - - Customers. - - Reports. - -The resources are subject to all CRUD operations, via by two -types of users: the 'admin' and the customers. The admin has -rights on all of them. - -One of the main differences with the previous versions is the -removal of the "/admin" initial component. If the administrator -authenticates for one operation, then this one is of type ``admin``: -no need for a dedicated and extra URI path component. - -For example, mocking transactions in the system was a typical -/admin-operation, but since transactions themselves are resources -and any resource is subject to CRUD operations, then mocking one -becomes just a ``C`` operation on the 'transactions' resources. If -a test case wants to simplify the authentication - by hard-coding -the credentials, for example - before mocking one transaction, then -it can impersonate the administrator. - -.. note:: - - ``POST``\ ing to an endpoint with a trailing ``$id`` means - modification of an existing resource. - -Demobanks -^^^^^^^^^ - -Demobanks are the main containers of all the other resources. -They take configuration values, like the currency for example. - -.. http:get:: /admin/demobanks -.. http:get:: /admin/demobanks/$id -.. http:post:: /admin/demobanks -.. http:post:: /admin/demobanks/$id -.. http:delete:: /admin/demobanks/$id - -Bank accounts. -^^^^^^^^^^^^^^ - -Bank accounts collect money of customers and participate -in transactions. - -The ``$base`` is one demobank, in the form ``/demobanks/$id``. -That is due because a bank account must inherit some defaults -from the demobank, like the currency. - -.. http:get:: $base/bankaccounts -.. http:get:: $base/bankaccounts/$id -.. http:post:: $base/bankaccounts -.. http:post:: $base/bankaccounts/$id -.. http:delete:: $base/bankaccounts/$id - -Subscribers. -^^^^^^^^^^^^ - -Subscribers are (optional) customers identities for protocols -other than the native one. - -A subscriber is not required to have a bank account "soon". Therefore, -it can be created, and later be linked to one bank account. For this -reason, the ``$base`` should not mention one bank account. - -.. note:: - - Creating a subscriber is a time-consuming operation that goes often - through slow channels, therefore it should basically never be done - more than once. - -.. http:get:: $base/subscribers -.. http:get:: $base/subscribers/$id -.. http:post:: $base/subscribers -.. http:post:: $base/subscribers/$id -.. http:delete:: $base/subscribers/$id - -Transactions. -^^^^^^^^^^^^^ - -Transactions are money movements between bank accounts. - -For convenience, ``$base`` **could** mention one bank account -to let customers see their transactions without defining "history" -query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``. - -At the same time, transactions should be easy to query regardless -of whose bank account they involve -- for administrative reasons, for -example. Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX`` -should be offered as well. - -.. http:get:: $base/transactions -.. http:get:: $base/transactions/$id -.. http:post:: $base/transactions -.. http:post:: $base/transactions/$id -.. http:delete:: $base/transactions/$id - -Customers. -^^^^^^^^^^ - -Customers are persons that **can** have one bank account. As -with subscribers, ``$base`` should not mention any bank account -so as to leave more flexibility to assign new bank accounts to -the same customer. - -.. http:get:: $base/customers -.. http:get:: $base/customers/$id -.. http:post:: $base/customers -.. http:post:: $base/customers/$id -.. http:delete:: $base/customers/$id - -Reports. -^^^^^^^^ - -Reports are persistent documents witnessing transactions. -A typical example is a Camt.053 statement. A report lives -even after a bank account gets deleted or a customer leaves -the bank, therefore ``$base`` should only mention a demobank -instance. - -.. http:get:: $base/reports -.. http:get:: $base/reports/$id -.. http:post:: $base/reports -.. http:post:: $base/reports/$id -.. http:delete:: $base/reports/$id diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst deleted file mode 100644 index c5372e5e..00000000 --- a/libeufin/api-sandbox.rst +++ /dev/null @@ -1,1077 +0,0 @@ -.. target audience: developer, core developer - -.. _sandbox-api: - -Sandbox API -########### - -Sandbox emulates a minimal bank, to provide EBICS access to test -`Taler <https://taler.net>`_. The top-level API defines two main -groups: `demobanks <Demobanks_>`_ and `legacy <Legacy API_>`_. -Currently, `error types <error-types_>`_ are common to both groups. - -Demobanks -========= - -Sandbox is designed to allow multiple *demobanks* being hosted, -where every demobank can have its own configuration (including -a different currency). A demobank has a name, although currently -only one demobank, named ``default``, is supported. Such demobank -activates the API segment ``/demobanks/default``, under which several -APIs are then served. The following sections describe all such APIs. - - -.. _circuit-api: - -Circuit API -^^^^^^^^^^^ - -This API offers to manage a selected group of users who act as businesses -for a local currency. Policies to disincentivize cashout operations may -also apply, making therefore this setup a *circuit* within a wider traditional -currency. - -For brevity, the list of response statuses for each endpoint may not be exhaustive. - -.. note:: - This API requires to **disable** ordinary registrations in the - configuration, to avoid other APIs from circumventing this registration - policy. See ``libeufin-sandbox config --help``. - -The following endpoints are served under ``/demobanks/default/circuit-api``. - -The client side of this API is offered both along the -:doc:`CLI <circuit-cli-commands>` and the SPA. The SPA is generally served -along Sandbox ``/`` path. - -Accounts --------- - -.. _circuit-register: - -.. http:post:: /accounts - - Create a new bank account. Only the administrator is allowed. - - **Request:** - - .. ts:def:: CircuitAccountRequest - - interface CircuitAccountRequest { - // Username - username: string; - - // Password. - password: string; - - // Addresses where to send the TAN. If - // this field is missing, then the cashout - // won't succeed. - contact_data: CircuitContactData; - - // Legal subject owning the account. - name: string; - - // 'payto' address pointing the bank account - // where to send payments, in case the user - // wants to convert the local currency back - // to fiat. - cashout_address: string; - - // IBAN of this bank account, which is therefore - // internal to the circuit. Randomly generated, - // when it is not given. - internal_iban?: string; - } - - .. ts:def:: CircuitContactData - - interface CircuitContactData { - - // E-Mail address - email?: EmailAddress; - - // Phone number. - phone?: PhoneNumber; - } - - - **Response:** - - :http:statuscode:`204 No content`: - The account was successfully created. - :http:statuscode:`400 Bad request`: - Input data was invalid. For example, the client specified a invalid - phone number or e-mail address. - :http:statuscode:`403 Forbidden`: - The response should indicate one of the following reasons. - - * A institutional username was attempted, like ``admin`` or ``bank``. - * A non admin user tried the operation. - - :http:statuscode:`409 Conflict`: - At least one registration detail was not available, - the error message should inform about it. - - -.. _circuit-delete-account: - -.. http:delete:: /accounts/$username - - Delete the account whose username is ``$username``. The deletion - succeeds only if the balance is *zero*. Only the administrator is - allowed. - - **Response:** - - :http:statuscode:`204 No content`: - The account was successfully deleted. - :http:statuscode:`403 Forbidden`: - The administrator specified a institutional username, like - ``admin`` or ``bank``. - :http:statuscode:`404 Not found`: - The username was not found. - :http:statuscode:`412 Precondition failed`: - The balance was not zero. - - -.. _circuit-reconfig: - -.. http:patch:: /accounts/$username - - Allows the administrator and the user to reconfigure - the account data of ``$username``. - - .. note:: - - Only the administrator has the rights to change the - user legal name. - - **Request:** - - .. ts:def:: CircuitAccountReconfiguration - - interface CircuitAccountReconfiguration { - - // Addresses where to send the TAN. - contact_data: CircuitContactData; - - // 'payto' address pointing the bank account - // where to send payments, in case the user - // wants to convert the local currency back - // to fiat. - cashout_address: string; - - // Legal name associated with $username. NOTE: - // only the administrator can change this value. - name?: string; - } - - **Response:** - - :http:statuscode:`204 No content`: - Operation successful. - - :http:statuscode:`403 Forbidden`: - The rights to change ``$username`` are not sufficient. - That includes the case where a correctly authenticated - user tries to change their legal name. It also - includes the case where 'admin' tries to change its - own account. - - :http:statuscode:`404 Not found`: - The account pointed by ``$username`` - was not found. - - -.. _circuit-password-reconfig: - -.. http:patch:: /accounts/$username/auth - - Allows administrators *and* ordinary users to - change the account's password. - - **Request:** - - .. ts:def:: AccountPasswordChange - - interface AccountPasswordChange { - - // New password. - new_password: string; - } - - **Response:** - - :http:statuscode:`204 No content`: - Operation successful. - - -.. _circuit-account-list: - -.. http:get:: /accounts - - Obtains a list of the accounts registered at the bank. - It returns only the information that this API handles, without - any balance or transactions list. The :doc:`Access API </core/api-bank-access>` - offers that. This request is only available to the administrator. - - **Request:** - - :query filter: *Optional.* - Pattern to filter on the account legal name. Given - the filter 'foo', all the results will **contain** - 'foo' in their legal name. Without this option, - all the existing accounts are returned. - - **Response:** - - `CircuitAccounts <circuit-accounts_>`_ - - .. _circuit-accounts: - - .. ts:def:: CircuitAccounts - - interfaces CircuitAccounts { - customers: CircuitAccountMinimalData[]; - } - - .. ts:def:: CircuitAccountMinimalData - - interface Balance { - amount: Amount; - credit_debit_indicator: "credit" | "debit"; - } - interface CircuitAccountMinimalData { - // Username - username: string; - - // Legal subject owning the account. - name: string; - - // current balance of the account - balance: Balance; - - // Number indicating the max debit allowed for the requesting user. - debitThreshold: String; - } - - :http:statuscode:`200 OK`: - At least one account was found. - - :http:statuscode:`204 No Content`: - No accounts were found for the given request. - - :http:statuscode:`403 Forbidden`: - A ordinary user invoked this call. - - -.. _circuit-account-info: - -.. http:get:: /accounts/$username - - Obtains information relative to the account owned by - ``$username``. The request is available to the administrator - and ``$username`` itself. - - **Response:** - - .. ts:def:: CircuitAccountData - - interface CircuitAccountData { - // Username - username: string; - - // IBAN hosted at Libeufin Sandbox - iban: string; - - contact_data: CircuitContactData; - - // Legal subject owning the account. - name: string; - - // 'payto' address pointing the bank account - // where to send cashouts. - cashout_address: string; - } - - :http:statuscode:`403 Forbidden`: - The user is not allowed. - -Cashouts --------- - -.. _circuit-cashout: - -.. http:post:: /cashouts - - Initiates a conversion to fiat currency. The account to be - credited is the one specified at registration time via the - *cashout_address* parameter. The account to be - debited is extracted from the authentication credentials. - The bank sends a TAN to the customer to let them confirm the - operation. The request is only available to ordinary users, not - to the administrator. - - .. note:: - - Consult the `cashout rates call <cashout-rates_>`_ to learn - about any applicable fee or exchange rate. - - To test this operation without relying on any SMS/E-mail provider, - Libeufin offers two methods: defining an environment variable called - ``LIBEUFIN_CASHOUT_TEST_TAN`` or specifying the value ``file`` to - the ``tan_channel`` field of the `request object <cashout-request_>`_. - Assuming ``LIBEUFIN_CASHOUT_TEST_TAN`` is set to *T*, every */confirm* - operation can use *T* as the TAN. Setting instead the ``tan_channel`` - field to ``file`` will cause the server to (over)write every TAN to - ``/tmp/libeufin-cashout-tan.txt``. If both are used, the environment - variable takes the precedence. - - - **Request:** - - `CashoutRequest <cashout-request_>`_ - - .. ts:def:: TanChannel - - enum TanChannel { - SMS = "sms", - EMAIL = "email", - FILE = "file" - } - - .. _cashout-request: - - .. ts:def:: CashoutRequest - - interface CashoutRequest { - - // Optional subject to associate to the - // cashout operation. This data will appear - // as the incoming wire transfer subject in - // the user's external bank account. - subject?: string; - - // That is the plain amount that the user specified - // to cashout. Its $currency is the circuit currency. - amount_debit: Amount; - - // That is the amount that will effectively be - // transferred by the bank to the user's bank - // account, that is external to the circuit. - // It is expressed in the fiat currency and - // is calculated after the cashout fee and the - // exchange rate. See the /cashout-rates call. - amount_credit: Amount; - - // Which channel the TAN should be sent to. If - // this field is missing, it defaults to SMS. - // The default choice prefers to change the communication - // channel respect to the one used to issue this request. - tan_channel?: TanChannel; - } - - **Response:** - - .. ts:def:: CashoutPending - - interface CashoutPending { - // UUID identifying the operation being created - // and now waiting for the TAN confirmation. - uuid: string; - } - - :http:statuscode:`202 Accepted`: - The cashout request was correctly created and - the TAN authentication now is pending. - :http:statuscode:`400 Bad request`: - The exchange rate was incorrectly applied. - :http:statuscode:`403 Forbidden`: - A institutional user (``admin`` or ``bank``) tried the operation. - :http:statuscode:`409 Conflict`: - The user did not share any contact data where to send the TAN. - :http:statuscode:`412 Precondition failed`: - The account does not have sufficient funds. - :http:statuscode:`503 Service unavailable`: - The bank does not support the TAN channel for this operation. - - -.. _circuit-cashout-abort: - -.. http:post:: /cashouts/$cashoutId/abort - - Aborts the ``$cashoutId`` operation. Original author - *and* admin are both allowed. - - **Response:** - - :http:statuscode:`204 No content`: - ``$cashoutId`` was found in the *pending* state - and got successfully aborted. - :http:statuscode:`404 Not found`: - ``$cashoutId`` is not found. Note: that happens - also when ``$cashoutId`` got aborted before this request. - :http:statuscode:`412 Precondition failed`: - ``$cashoutId`` was already confirmed. - - -.. _circuit-cashout-confirm: - -.. http:post:: /cashouts/$cashoutId/confirm - - Confirms the ``$cashoutId`` operation by accepting its - TAN. The request should still be authenticated with - the users credentials. Only the original author is allowed. - - **Request:** - - .. ts:def:: CashoutConfirm - - interface CashoutConfirm { - - // the TAN that confirms $cashoutId. - tan: string; - } - - **Response:** - - :http:statuscode:`204 No content`: - ``$cashoutId`` was found in the *pending* state and - got successfully confirmed. - :http:statuscode:`403 Forbidden`: - wrong TAN. - :http:statuscode:`404 Not found`: - ``$cashoutId`` is not found. Note: that happens - also when ``$cashoutId`` got aborted before this request. - :http:statuscode:`409 Conflict`: - At least the following two cases are possible - * an institutional user (``admin`` or ``bank``) tried the operation - * the user changed their cash-out address between the creation and the confirmation of ``$cashoutId``. - :http:statuscode:`412 Precondition failed`: - ``$cashoutId`` was already confirmed. - - -.. http:get:: /cashouts/estimates - - This endpoint shows how the bank would apply the cash-out - ratio and fee to one input amount. Typically, frontends - ask this endpoint before creating cash-out operations. There - is **no** financial consequence to this endpoint and only - registered users are allowed to request. At least one of - the two query parameters should be provided. If both are - given, then the server checks their correctness. Amounts - must include the currency. - - **Request:** - - :query amount_debit: this is the amount that the user will get - deducted from their regional bank account. - - :query amount_credit: this is the amount that the user will receive - in their fiat bank account. - - **Response:** - - .. ts:def:: CashoutEstimate - - interface CashoutEstimate { - // Amount that the user will get deducted from their regional - // bank account, according to the 'amount_credit' value. - amount_debit: Amount; - // Amount that the user will receive in their fiat - // bank account, according to 'amount_debit'. - amount_credit: Amount; - } - - - :http:statuscode:`200 Ok`: - Response contains the calculated values - :http:statuscode:`400 Bad request`: - Both parameters have been provided and the calculation is not correct, - or none of them has been provided. - -.. _cashout-rates: - -.. http:get:: /config - - **Response:** - - .. ts:def:: Config - - interface Config { - // Name of this API, always "circuit". - name: string; - // API version in the form $n:$n:$n - version: string; - // Contains ratios and fees related to buying - // and selling the circuit currency. - ratios_and_fees: RatiosAndFees; - // Fiat currency. That is the currency in which - // cash-out operations ultimately wire money. - fiat_currency: string; - } - - .. ts:def:: RatiosAndFees - - interface RatiosAndFees { - // Exchange rate to buy the circuit currency from fiat. - buy_at_ratio: LibeufinNumber; - // Exchange rate to sell the circuit currency for fiat. - sell_at_ratio: LibeufinNumber; - // Fee to subtract after applying the buy ratio. - buy_in_fee: LibeufinNumber; - // Fee to subtract after applying the sell ratio. - sell_out_fee: LibeufinNumber; - } - - - Example. Given a circuit currency CC, a fiat currency FC, - a *sell_at_ratio* = 0.9 and *sell_out_fee* = 0.03, selling - 10 CC would result in the following FC: (10 * 0.9) - 0.03 - = 8.97 FC. On the other hand, given *buy_at_ratio* = 1.1 - and *buy_in_fee* = 0.01, a user wanting to spend 10 FC to - buy the CC would result in the following CC: (10 * 1.1) - - 0.01 = 10.99 CC. - - .. note:: - - the terms 'sell out' and 'cashout' may be used interchangeably. - - -.. _circuit-cashouts: - -.. http:get:: /cashouts - - Returns the list of all the (pending and confirmed) cash-out operations. - Ordinary users can only use this endpoint to learn their *own* cash-out - operations. - - **Request:** - - :query account: *Optional.* - Filters the request to only get the cash-out operations related to - the account specified in this parameter. Ordinary users must use - this option and pass their own username as the value. - - **Response:** - - .. ts:def:: Cashouts - - interface Cashouts { - // Every string represents a cash-out operation UUID. - cashouts: string[]; - } - - :http:statuscode:`200 OK`: - At least one cash-out operation was found. - - :http:statuscode:`204 No Content`: - No cash-out operations were found at the bank - - :http:statuscode:`403 Forbidden`: - A ordinary user invoked this call either without - the ``account`` parameter or by passing to it someone - else's username. - - -.. _circuit-cashout-details: - -.. http:get:: /cashouts/$cashoutId - - Informs about the status of the ``$cashoutId`` operation. - The request is available to the administrator and the original author. - - **Response:** - - `CashoutStatusResponse <cashout-status_>`_ - - .. _cashout-status: - - .. ts:def:: CashoutStatus - - interface CashoutStatusResponse { - - status: CashoutStatus; - // Amount debited to the circuit bank account. - amount_debit: Amount; - // Amount credited to the external bank account. - amount_credit: Amount; - // Transaction subject. - subject: string; - // Circuit bank account that created the cash-out. - account: string; - // Fiat bank account that will receive the cashed out amount. - cashout_address: string; - // Ratios and fees related to this cash-out at the time - // when the operation was created. - ratios_and_fees: RatiosAndFees; - // Time when the cash-out was created. - creation_time: number; // milliseconds since the Unix epoch - // Time when the cash-out was confirmed via its TAN. - // Missing or null, when the operation wasn't confirmed yet. - confirmation_time?: number | null; // milliseconds since the Unix epoch - } - - .. ts:def:: CashoutStatus - - enum CashoutStatus { - - // The payment was initiated after a valid - // TAN was received by the bank. - CONFIRMED = "confirmed", - - // The cashout was created and now waits - // for the TAN by the author. - PENDING = "pending", - } - - **Response:** - - :http:statuscode:`404 Not found`: - The cashout operation was not found. That is - *also* the case of ``$cashoutId`` being an aborted - operation. - -Access API -^^^^^^^^^^ - -Every endpoint is served under ``/demobanks/default/access-api``. -See :doc:`/core/api-bank-access`. This API allows users to access -their bank accounts and trigger Taler withdrawals. - -Integration API -^^^^^^^^^^^^^^^ - -Every endpoint is served under ``/demobanks/default/integration-api``. -See :doc:`/core/api-bank-integration`. This API handles the communication -with Taler wallets. - -Taler Wire Gateway API -^^^^^^^^^^^^^^^^^^^^^^ - -Served under ``/demobanks/default/taler-wire-gateway``. Currently, -only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint -is implemented. This endpoint allows testing, but the rest of -this API does never involve the Sandbox. - -EBICS API -^^^^^^^^^ - -.. _demobank-create-ebics-subscriber: - -.. http:post:: /demobanks/default/ebics/subscribers - - Allows (only) the *admin* user to associate a bank account - to a EBICS subscriber. If the latter does not exist, it is - created. - - **Request:** - - .. ts:def:: SubscriberRequest - - interface SubscriberRequest { - - // hostID - hostID: string; - - // userID - userID: string; - - // partnerID - partnerID: string; - - // systemID, optional. - systemID: string; - - // Label of the bank account to associate with - // this subscriber. - demobankAccountLabel: string; - } - -.. note:: - - The following endpoints are **not** served under the ``/demobank/default`` segment. - -Legacy API -========== - -This was the first API offered by Sandbox. It is used in -some test cases. One is hosted at the Wallet repository; other -MAY as well exist. - -Except of the main EBICS handler located at "/ebicsweb", all -the EBICS calls have to authenticate the 'admin' user via -the HTTP basic auth scheme. - -EBICS Hosts -^^^^^^^^^^^ - -.. http:post:: /admin/ebics/hosts - - Create a new EBICS host. - - **Request:** - - .. ts:def:: EbicsHostRequest - - interface EbicsHostRequest { - - // Ebics version. - hostID: string; - - // Name of the host. - ebicsVersion: string; - } - - -.. http:get:: /admin/ebics/hosts - - Shows the list of all the hosts in the system. - - **Response:** - - .. ts:def:: EbicsHostResponse - - interface EbicsHostResponse { - - // shows the host IDs that are active in the system. - // The Ebics version *is* missing, but it's still available - // via the HEV message. - ebicsHosts: string[]; - } - -.. http:post:: /admin/ebics/hosts/$hostID/rotate-keys - - Overwrite the bank's Ebics keys with random ones. This is entirely - meant for tests (as the Sandbox itself is) and no backup will be - produced along this operation. - -EBICS Subscribers -^^^^^^^^^^^^^^^^^ - -.. http:post:: /admin/ebics/bank-accounts - - Associates a new bank account to an existing subscriber. - - .. note:: - - This call allows to create a bank account without - any associated user profile! That makes the basic auth - access to the financial data **only** possible for the - admin. - - **Request:** - - .. ts:def:: BankAccountRequest - - interface BankAccountRequest { - - // Ebics subscriber - subscriber: { - userID: string; - partnerID: string; - systemID: string; - }; - - // IBAN - iban: string; - - // BIC - bic: string; - - // human name - name: string; - - // bank account label - label: string; - } - -.. http:get:: /admin/ebics/subscribers - - Shows the list of all the subscribers in the system. - - **Response:** - - .. ts:def:: SubscribersResponse - - interface SubscribersResponse { - - subscribers: Subscriber[] - } - - .. ts:def:: Subscriber - - interface Subscriber { - - // userID - userID: string; - - // partnerID - partnerID: string; - - // hostID - hostID: string; - - // Label of the bank account - // associated with this Ebics subscriber. - demobankAccountLabel: string; - } - -.. http:post:: /admin/ebics/subscribers - - Create a new EBICS subscriber without associating - a bank account to it. This call is **deprecated**. - Follow `this page <https://bugs.gnunet.org/view.php?id=7507>`_ - for updates over the EBICS management REST design. - - **Request:** - - .. ts:def:: SubscriberRequestDeprecated - - interface SubscriberRequestDeprecated { - - // hostID - hostID: string; - - // userID - userID: string; - - // partnerID - partnerID: string; - - // systemID, optional. - systemID: string; - - } - -Bank accounts -^^^^^^^^^^^^^ - -The access to a particular bank account is granted either to the -owner or to admin, via the HTTP basic auth scheme. A 'owner' is -a registered customer, who is identified by a username. The -registration of customers is offered via the :doc:`/core/api-bank-access`. - -.. note:: - - The current version allows only one bank account per - customer, where the bank account name (also called 'label') - equals the owner's username. - -.. http:get:: /admin/bank-accounts - - Give summary of all the bank accounts. Only admin allowed. - - **Response:** - - .. ts:def:: AdminBankAccount - - interface AdminBankAccount { - - // IBAN - iban: string; - - // BIC - bic: string; - - // human name - name: string; - - // bank account label - label: string; - } - - -.. http:get:: /admin/bank-accounts/$accountLabel - - Give information about a bank account. - - **Response:** - - .. ts:def:: AdminBankAccountBalance - - interface AdminBankAccountBalance { - // Balance in the $currency:$amount format. - balance: string; - // IBAN of the bank account identified by $accountLabel - iban: string; - // BIC of the bank account identified by $accountLabel - bic: string; - // Mentions $accountLabel - label: string; - } - -.. http:post:: /admin/bank-accounts/$accountLabel - - Create bank account. Existing users without a bank account - can request too. - - **Request:** :ts:type:`AdminBankAccount` - -Transactions -^^^^^^^^^^^^ - -.. http:get:: /admin/bank-accounts/$accountLabel/transactions - - Inform about all the transactions of one bank account. - - **Response:** - - .. ts:def:: AdminTransactions - - interface AdminTransactions { - payments: AdminTransaction[]; - } - - .. ts:def:: AdminTransaction - - interface AdminTransaction { - - // Label of the bank account involved in this payment. - accountLabel: string; - - // Creditor IBAN - creditorIban: string; - - // Debtor IBAN - debtorIban: string; - - // UID given by one financial institute to this payment. - // FIXME: clarify whether that can be also assigned by - // the other party's institution. - accountServicerReference: string; - - // ID of the Pain.001 that initiated this payment. - paymentInformationId: string; - - // Unstructured remittance information. - subject: string; - - // Date of the payment in the HTTP header format. - date: string; - - // The number amount as a string. - amount: string; - - // BIC of the creditor IBAN. - creditorBic: string; - - // Legal name of the creditor. - creditorName: string; - - // BIC of the debtor IBAN. - debtorBic: string; - - // Legal name of the debtor. - debtorName: string; - - // Payment's currency - currency: string; - - // Have values 'credit' or 'debit' relative - // to the requesting user. - creditDebitIndicator: string; - } - -.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions - - Generate one incoming and one outgoing transaction for the bank account - identified by ``$accountLabel``. Only admin allowed. - -.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction - - Book one incoming transaction for $accountLabel. - The debtor (not required to be in the same bank) - information is taken from the request. Only admin allowed. - - **Request:** - - .. ts:def:: AdminSimulateTransaction - - interface AdminSimulateTransaction { - - // Debtor IBAN. - debtorIban: string; - - // Debtor BIC. - debtorBic: string; - - // Debtor name. - debtorName: string; - - // Amount number (without currency) as a string. - amount: string; - - // Payment subject. - subject: string; - } - - -.. http:post:: /admin/payments/camt - - Return the last camt.053 document from the requesting account. - - **Request** - - .. code-block:: tsref - - interface CamtParams { - - // label of the bank account being queried. - bankaccount: string; - - // The Camt type to return. Only '53' is allowed - // at this moment. - type: number; - } - - **Response** - - The last Camt.053 document related to the bank account - mentioned in the request body. - - -.. _error-types: - -====== -Errors -====== - -The JSON type coming along a non 2xx response is the following: - -.. ts:def:: SandboxError - - interface SandboxError { - error: SandboxErrorDetail; - } - -.. ts:def:: SandboxErrorDetail - - interface SandboxErrorDetail { - - // String enum classifying the error. - type: ErrorType; - - // Human-readable error description. - description: string; - } - -.. ts:def:: ErrorType - - enum ErrorType { - /** - * This error can be related to a business operation, - * a non-existent object requested by the client, or - * even when the bank itself fails. - */ - SandboxError = "sandbox-error", - - /** - * It is the error type thrown by helper functions - * from the Util library. Those are used by both - * Sandbox and Nexus, therefore the actual meaning - * must be carried by the error 'message' field. - */ - UtilError = "util-error" - } diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst new file mode 100644 index 00000000..ab793b2b --- /dev/null +++ b/libeufin/bank-manual.rst @@ -0,0 +1,307 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + +.. target audience: operator, developer + +.. _libeufin-bank: + +Bank Setup Manual +################# + +libeufin-bank implements a simple core banking system with +account and REST APIs, including REST APIs for a Web interface +and REST APIs to interact with GNU Taler components. + +In this manual, we explain how to setup a bank. + +.. contents:: Table of Contents + :local: + + +Installing LibEuFin Bank +======================== + +The following section was tested on an *OpenJDK 17* environment. + +Installing the libeufin-bank binary packages on Debian +------------------------------------------------------ + +.. include:: ../frags/installing-debian.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + +Installing the libeufin-bank binary packages on Ubuntu +------------------------------------------------------ + +.. include:: ../frags/installing-ubuntu.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + +Building from source +-------------------- + +Bank belongs to the LibEuFin project, and can be downloaded via Git: + +.. code-block:: console + + $ git clone git://git.taler.net/libeufin + +Note that Kotlin and Gradle should already work on the host system. + +Navigate into the *libeufin* local repository, and from top-level run: + +.. code-block:: console + + $ ./bootstrap + $ ./configure --prefix=$PREFIX + $ make install + +If the previous steps succeeded, the ``libeufin-bank`` command should +be found in the $PATH. + + +Minimal Configuration for LibEuFin Bank +======================================= + +The following snippet shows the mandatory configuration values: + +.. code-block:: ini + + [libeufin-bank] + CURRENCY = KUDOS + + # Supported payment target type + WIRE_TYPE = iban or x-taler-bank + # If WIRE_TYPE = iban + IBAN_PAYTO_BIC = SANDBOXX + # If WIRE_TYPE = x-taler-bank + X_TALER_BANK_PAYTO_HOSTNAME = https://bank.taler.net + +.. note:: + Refer to the manpage ``libeufin-man.conf(5)`` + for the full array of configuration values. + +.. _libeufin-mfa: + +Configuring multi-factor authentication +--------------------------------------- + +libeufin-bank supports two-factor authentication. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. We provide two default helper scripts: ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two-factor authentication you need to configure at least one TAN channel. + +SMS TAN channel ++++++++++++++++ + +The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ SMS provider. It requires an additional ``AUTH_TOKEN`` environment variable for `Telesign Basic authentication <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. + +To test your setup run: + +.. code-block:: console + + $ AUTH_TOKEN=$TELESIGN_TOKEN + $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE + +If you received an SMS containing "Test 1234" you can enable this channel in the config: + +.. code-block:: ini + + [libeufin-bank] + TAN_SMS = libeufin-tan-sms.sh + TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN" + +Mail TAN channel +++++++++++++++++ + +The default ``libeufin-tan-email.sh`` script is based on the ``mail`` Linux command. It requires a working local mail transfer agent. + +To test your setup run: + +.. code-block:: console + + $ echo "Test 1234" | libeufin-tan-email.sh $EMAIL + +If you received an email containing "Test 1234" you can enable this channel in the config: + +.. code-block:: ini + + [libeufin-bank] + TAN_EMAIL = libeufin-tan-email.sh + +Custom TAN channel scripts +++++++++++++++++++++++++++ + +It is possible to replace these scripts with use custom scripts to send +the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge and non-zero on failure. + +To change the scripts used for multi-factor authentication, change the following +options in the configuration file: + +.. code-block:: ini + + [libeufin-bank] + TAN_SMS = custom-tan-sms.sh + TAN_SMS_ENV = + TAN_EMAIL = custom-tan-email.sh + TAN_EMAIL_ENV = + +Launching libeufin-bank +======================= + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command initializes (or upgrades) the database schema: + +.. code-block:: console + + $ libeufin-bank-dbinit -c "$CONFIG_FILE" + +Once this is done, you can start the libeufin-bank HTTP server: + +.. code-block:: console + + $ libeufin-bank serve -c "$CONFIG_FILE" + + + +Using the bank Web interface +============================ + +To be able to use the Web interface, you must set a password for the "admin" +account. You can set (or reset) the account password to ``$PASSWORD`` using +the following command: + +.. code-block:: console + + $ libeufin-bank passwd -c "$CONFIG_FILE admin "$PASSWORD" + +You can also use the same command to reset the passwords of other accounts by +replacing "admin" with the respective login. + + +Setting up accounts +------------------- + +Using the above "$PASSWORD", log into the Web interface as "admin". To setup +regular accounts, search for the button "Create account" near the list of all +existing bank accounts in the Web interface of libeufin-bank. + +You will be asked to specify: + +Username + A unique account name the user will use to access the bank account. + +Name + Legal name of the user or business owning the account. + +Email + E-mail address of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled). + +Phone + Mobile phone number of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled). + +Max debt + Maximum amount the account is allowed to go into debt. Non-zero settings **must** be used for the "admin" account where this setting effectively creates a limit on the amount of money managed by the bank. + +Is this a Taler Exchange? + Should be disabled except if you are setting up an account for a GNU Taler exchange. If enabled, transactions that are not compatible with a GNU Taler exchange will be automatically refused by the bank. + +XXX Cashout channel + Used in a regional currency setup to specify the external account number of a bank account in fiat currency that belongs the merchant. Allows the merchant to exchange its regional currency money for wire transfers in fiat currency into this account. Optional. Not available unless the bank is configured for regional currencies. + +Is this account public? + Public accounts can be viewed without access control, their balance and transaction history becomes public. + +After submitting the form, a randomly created password for the new account +will be shown in a notification. The administrator can also change passwords +for any account in the system using the "change password" link in the account +list. To change other details about an account, select the "Username" in the +account list. + + +Account introspection +--------------------- + +Users can see (and possibly change) the settings of their bank account and +also their IBAN by clicking on the "Welcome, $USERNAME" text after logging +into their bank account using their username and password. + +The IBAN field has a convenient "copy to clipboard" button next to it. + + +Making transfers between accounts +--------------------------------- + +First, you need to know the IBAN of the account to credit, and log in as the +user of the account to be debited. Then select "Using a form", enter the IBAN +under "Recipient" and specify a wire transfer subject and the total amount to +be wired. After pressing "Send", you may have to pass a 2-FA check. + + +Integration with the Taler Exchange +=================================== + +.. note:: + + This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`. + +You must have an exchange account with username ``exchange`` for conversion to work. +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command would create one: + +.. code-block:: console + + $ libeufin-bank create-account '{"username":"exchange","password":"$EXCHANGE_PASSWORD","name":"Cashout Exchange","is_taler_exchange":true}' -c "$CONFIG_FILE" + +.. note:: + + You can also set up the exchange account as "admin" using the Web interface of libeufin-bank. + +Having done so, take note of two key pieces of information, namely the ``$EXCHANGE_PASSWORD`` and the "payto://"-URI of the exchange bank account. This information must then be used to configure the exchange as described in +:ref:`exchange bank account configuration <exchange-account-signing>`. When using the libeufin-bank in the context +of a regional currency with conversion, you must +additionally specify a "conversion-url" when setting +up the exchange account. See the section on :ref:`conversion setup <regional-conversion-setup>` in the regional currency setup chapter for details. + + +Withdrawing e-cash to a Taler wallet +==================================== + +.. note:: + + This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`. + +Users can withdraw digital cash from their bank account starting from their +online banking as implemented by the libeufin-bank. However, in this scenario, +the Taler wallet may not already know about an exchange that works with the +respective currency. Thus, the protocol includes the possibility of the bank +*recommending* an exchange service to the wallet, thus providing a sane +default for the wallet to suggest to the user. To do so, the base URL of the +exchange API must be specified in the libeufin-bank configuration: + +.. code-block:: ini + + [libeufin-bank] + DEFAULT_EXCHANGE=${PROTO}://exchange.${DOMAIN_NAME} + +After changing this value, the libeufin-bank service needs to be restarted +to make the change effective. + +.. note:: + + The user may change the default exchange from within the wallet, assuming they know of an alternative exchanges for the currency. diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst deleted file mode 100644 index 7d26cbc3..00000000 --- a/libeufin/bank-transport-ebics.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. target audience: core developer - -The EBICS Bank Transport -======================== - -An EBICS bank transport in LibEuFin conceptually corresponds -to the "EBICS Subscriber" in EBICS terminology. - - -Bank Transport Setup --------------------- - -The following steps are required to set up an EBICS bank transport: - -1. The bank must set up the EBICS access for the user. - The bank will notify the user of the following parameters: - - * the URL of the EBICS server used by the bank - * the HostID of the bank within the EBICS server (sometimes one EBICS server hosts multiple banks) - * the PartnerID (typically identifies the owner of the bank account within the banking system) - * the UserID (typically identifies the person that accesses the bank account, can be different from the owner) - * the SystemID (optional and rarely used, basically a "sub-identity" of a subscriber when multiple technical - systems have access to the account via EBICS) - -2. The user enters the information from the list above in the setup dialog in the LibEuFin nexus (UI/CLI). - -3. The LibEuFin nexus generates cryptographic key material (3 RSA key pairs). - -4. The nexus sends the public keys electronically to the bank's EBICS server, together with the information - identifying the subscriber (PartnerID, UserID, SystemID). - -5. The user prints a document that contains the public key and hashes for all three key pairs. - The user then signs this document and sends it to the bank (physically/scanned). - -6. The bank receives the letter and verifies that the keys from the letter correspond - to the electronically sent keys. If they match, the bank sets the state of the - subscriber to "ready". - -7. The user now has to wait until the bank has set the EBICS subscriber state to "ready". - There is no in-band notification for this, but the Nexus can try downloading the bank's - cryptographic parameters. This will only succeed once the EBICS subscriber is set to "ready" - by the bank. - -8. The user should confirm the public keys of the bank received in the previous step. - Typically the bank gives the value of these public keys in an out-of-band channel. - -9. Now the user can finally use the EBICS bank transport. The first step after finishing - the setup should be to import the bank accounts accessible for this EBICS subscriber. - - -Alternative ways of setting up the EBICS bank transport are: - -* Importing from a backup. The backup contains metadata (EBICS URL, HostID, - UserId, ...) and the three passphrase-protected subscriber keys. -* Certificate-based setup (currently not supported by LibEuFin, only used in France) diff --git a/libeufin/banking-protocols.rst b/libeufin/banking-protocols.rst deleted file mode 100644 index 2eaffb3d..00000000 --- a/libeufin/banking-protocols.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. target audience: core developer - -Banking Protocols -################# - -This page collects information we have about banking protocols available around -the world. - - -Open Financial Exchange (OFX) Direct Connect -============================================ - -`OFX <https://www.ofx.net/>`__ is widely used in the US. It defines a completely -custom protocol (based on HTTP) and data formats (**not** based on ISO20022) for banking. - - -Electronic Banking Internet Communication Standard (EBICS) -========================================================== - -EBICS is used primarily in Germany, France and Switzerland. Some banks (such as BNPParibas -with their `Global Ebics <https://cashmanagement.bnpparibas.com/our-solutions/solution/global-ebics>`__) -also allow EBICS access to accounts in other countries. - -EBICS is just a transfer layer for communicating with banks. Banks define what -messages they support. In practice, EBICS is very often used to transfer -ISO20022 messages. - -German banks that are part of the German Banking Industry Committee all must offer EBICS access. -Thus this protocol is a good choice for the German market. - - -FinTS / HBCI -============ - -German home-banking standard. FinTS is the successor of the Home Banking -Computer Interface (HBCI), but older versions of FinTS are often still called -HBCI. - -The current version, FinTS 4.0, is not widely supported by banks yet. Starting with FinTS, -XML is used as a data format. Previous versions used a custom text/binary format. - -Only some banks allow authentication based on key pairs. -Due to different interpretation of PSD2, other banks now only allow authentication -methods that require interaction from the customer (SCA / Strong Customer Authentication). - -Payloads these days can be ISO20022 messages. - -Examples: - * `GLS <https://www.gls.de/geschaefts-firmenkunden/zahlungsverkehr/onlinebankingverfahren-und-programme/daten-zum-onlinebanking/>`__ - - -PSD2 -==== - -PSD2 is not a technical standard, but high-level legal requirements on (amongst other things) APIs -that banks have to offer. - -There are many implementations of PSD2 APIs. The `Berlin Group <https://www.berlin-group.org/>`__ -provides a framework that somewhat standardizes technical details, but the use of this standard -is by no means necessary. - -Unfortunately, it focuses on *other* parties accessing *your* bank account. It -does not give customers access to their own bank account. Customers can manage -third party access they give to their bank account in their online banking -system. That mechanism is conceptually similar to OAuth2. In fact, some -implementations of PSD2 even use OAuth2 directly. - -PSD2 APIs usually use JSON as a data format. Often the schema and terminology is "inspired" by ISO20022 -messages, but no actual ISO20022 XML message formats are used. - -PSD2 requires two main services to be available via an API: - -* AIS (Account Information Service). -* PIS (Payment Initiation Service). - -Together, they're often called XS2A ("access to account"). - -An entity that wants to use AIS has to be registered with the financial -oversight authority in its country (BAFIN in Germany). PIS has even stronger -legal prerequisites. - -On a technical level, using PSD2 APIs usually requires having an `EIDAS <https://en.wikipedia.org/wiki/EIDAS>`__ certificate. - -Examples (bank offerings): - * `Sparkasse <https://xs2a.sparkassen-hub.com/home>`__ (Berlin Group based) - * `Deutsche Bank <https://developer.db.com/products/psd2>`__ - -Examples (standards): - * `STET PSD2 API <https://www.stet.eu/en/psd2/>`__ - * `Berlin Group NextGenPSD2 <https://www.berlin-group.org/nextgenpsd2-downloads>`__ - - - -Bank-Proprietary APIs -===================== - -Some banks offer completely custom APIs to access services of the bank. These often include services -not available via more standardized APIs, such as account creation. - -Often banks frame PSD2 as just another API available in their portfolio of API offerings. - -Examples: - -* `Deutsche Bank <https://developer.db.com/products>`__ -* `ING Group <https://developer.ing.com/api-marketplace/marketplace>`__ -* `Revolut <https://revolut-engineering.github.io/api-docs/business-api/>`__ -* `PayPal <https://developer.paypal.com/classic-home/>`__ - - -Open Bank Project -================= - -The `Open Bank Project <https://www.openbankproject.com/>`__ provides a free software implementation of -banking middleware that supports various APIs, including PSD2-compatible APIs (based on Berlin Group). - -API Docs: `<https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture>`__ - - -UK Open Banking -=============== - -Open Banking is the (quite confusing!) name of a UK-based open banking initiative. - -What's nice about Open Banking is that their APIs are really close to ISO 20022, unlike many -similar HTTP+JSON APIs. - -`<https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications>`__ diff --git a/libeufin/camt.054-style-0.png b/libeufin/camt.054-style-0.png Binary files differnew file mode 100644 index 00000000..05ca6365 --- /dev/null +++ b/libeufin/camt.054-style-0.png diff --git a/libeufin/camt.054-style-1.png b/libeufin/camt.054-style-1.png Binary files differnew file mode 100644 index 00000000..30f7d535 --- /dev/null +++ b/libeufin/camt.054-style-1.png diff --git a/libeufin/check-payment-subject-0.png b/libeufin/check-payment-subject-0.png Binary files differnew file mode 100644 index 00000000..eb8c8ca5 --- /dev/null +++ b/libeufin/check-payment-subject-0.png diff --git a/libeufin/check-payment-subject-1.png b/libeufin/check-payment-subject-1.png Binary files differnew file mode 100644 index 00000000..eb99cf20 --- /dev/null +++ b/libeufin/check-payment-subject-1.png diff --git a/libeufin/circuit-cli-commands.rst b/libeufin/circuit-cli-commands.rst deleted file mode 100644 index 7ce5e467..00000000 --- a/libeufin/circuit-cli-commands.rst +++ /dev/null @@ -1,149 +0,0 @@ -The following list shows all the CLI subcommands -acting as the Circuit API's client side. Each section -name is one subcommand available in this pattern: -``libeufin-cli sandbox demobank $subcommand``. - -Finally, each section name links to the related API -documentation of the endpoint being addressed. - -:ref:`circuit-account-info <circuit-account-info>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Retrieve Circuit information about one account. Useful to get cash-out - address and contact details. - -Options: - --username TEXT Username of the account to retrieve. It defaults to - LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin'. - --help Show this message and exit. - -:ref:`circuit-accounts <circuit-account-list>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Gets the list of all the accounts managed by the Circuit. Only 'admin' - allowed - -Options: - --help Show this message and exit. - -:ref:`circuit-cashout <circuit-cashout>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Create a cash-out operation. If successful, the user gets a TAN. - -Options: - --subject TEXT Payment subject to associate to the outgoing and - incoming payments that are associated with this cash- - out operation. - --amount-debit TEXT Amount that will debited to the local currency - account, in the <currency>:X.Y format. [required] - --amount-credit TEXT Amount that will credited to the fiat currency - account, in the <currency>:X.Y format. [required] - --tan-channel TEXT Indicates how to send the TAN to the user: 'sms', - 'email' and 'file' are valid values. If missing, the - bank defaults to SMS. 'file' makes the server write - the TAN to /tmp/libeufin-cashout-tan.txt, normally - used for testing. - --help Show this message and exit. - - -:ref:`circuit-cashout-abort <circuit-cashout-abort>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Abort a cash-out operation. Admin and author are allowed to request. - -Options: - --uuid TEXT UUID of the cash-out operation to abort. [required] - --help Show this message and exit. - - -:ref:`circuit-cashout-confirm <circuit-cashout-confirm>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Confirm a cash-out operation. Only the author is allowed (no admin). - -Options: - --tan TEXT TAN that authorizes the cash-out operaion. [required] - --uuid TEXT UUID of the cash-out operation to confirm. [required] - --help Show this message and exit. - - -:ref:`circuit-cashout-details <circuit-cashout-details>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Retrieve status information about one cash-out operation. Admin and author - are allowed to request. - -Options: - --uuid TEXT UUID of the cash-out operation to retrieve. [required] - --help Show this message and exit. - - -:ref:`circuit-cashouts <circuit-cashouts>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Gets the list of all the pending and confirmed cash-out operations. - -Options: - --help Show this message and exit. - - -:ref:`circuit-delete-account <circuit-delete-account>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Delete one account. Only available to the administrator and for accounts - with zero balance. - -Options: - --username TEXT account to delete [required] - --help Show this message and exit. - - -:ref:`circuit-password-reconfig <circuit-password-reconfig>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Ask interactively to change the password. It needs administrator or owner - credentials - -Options: - --username TEXT Username whose password will change. Defaults to - LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin' as a - value. - --help Show this message and exit. - - -:ref:`circuit-reconfig <circuit-reconfig>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Reconfigure an account with cash-out capabilities. It needs administrator - or owner credentials - -Options: - --phone TEXT Phone number for the SMS TAN - --email TEXT E-mail address for receiving the TAN - --cashout-address TEXT Payto address where to send fiat payments on cash- - outs [required] - --username TEXT Username associated with the account to reconfigure. - It defaults to LIBEUFIN_SANDBOX_USERNAME and doesn't - accept 'admin'. - --help Show this message and exit. - - -:ref:`circuit-register <circuit-register>` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Register a new account with cash-out capabilities. It needs administrator - credentials, and the new account password exported in - LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD. - -Options: - --username TEXT new account username [required] - --cashout-address TEXT Payto address where to send fiat payments on cash- - outs [required] - --name TEXT Legal name associated to the account. [required] - --phone TEXT SMS where to send the cash-out TAN. - --email TEXT E-mail address where to send the cash-out TAN. - --internal-iban TEXT Which IBAN to associate to this account. The IBAN - participates only in the local currency circuit. If - missing, the bank generates one. - --help Show this message and exit. diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst deleted file mode 100644 index 6a251991..00000000 --- a/libeufin/concepts.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. target audience: operator, developer - -################### -Conceptual Overview -################### - - -What is LibEuFin -================ - -The goal of LibEuFin is to make the development and testing of -FinTech applications easier. It hides implementation details -of complex legacy banking APIs behind a simple interface. - -LibEuFin Nexus and Sandbox --------------------------- - -LibEuFin has two main components: - -1. The LibEuFin nexus receives banking-related requests in a LibEuFin-specific - format via an HTTP API. It then translates those requests into interactions - with other banking APIs, abstracting away different underlying protocols and - hiding the complexity of the legacy protocols used by some banks. - -2. The LibEuFin sandbox implements the server side of protocols - that banks speak. It also emulates a *very*, *very* simple - core banking system to manage accounts and their balance. - The main use case for the sandbox is testing LibEuFin itself, - as well as applications developed with LibEuFin. - The sandbox has a JSON API to set it up for tests (creating bank - hosts, bank accounts, fake transactions). - - -High-Level Concepts -=================== - -Nexus Users ------------ - -The concept of a *nexus user* is used to implement access control to the -operations that the nexus provides. - -A user has a login name and a (salted, hashed) password. -This is the `HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_ method. -(Other authentication methods could be added in the future.) - -A nexus user can be marked as *superuser*. All permission checks are skipped -for superusers. Only superusers are allowed to create/modify other users. - -Bank Accounts -------------- - -A *bank account* is the local representation of some bank account. -The information stored about it includes: - -* Local alias ("nickname") of the bank account -* Account identification (IBAN / BIC / account holder) -* A local mirror of the bank transaction history -* Payment requests, i.e. payments that have been locally requested, together - with their state (sent or not sent, acknowledged in bank statement or not) -* Error reports (e.g. failed payment requests, bank statement items that were not understood - by LibEuFin) -* A default bank connection (if configured) that is used by default - for operations on the account -* Other enabled "bank connections" (see definition below) - -Examples: - -.. code-block:: console - - # Download latest transactions via the default bank connection and store them locally - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-accounts/my-acct/fetch-transactions - -Bank Connections ----------------- - -Bank connections connect the local LibEuFin bank account to the real bank. -The *bank connection* includes the following data: - -* Local alias ("nickname") of the bank connection -* The type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox) -* Protocol configuration (hostname, port, protocol sub-version/flags) -* Credentials to use the connection (e.g. password, EBICS subscriber keys) - -Bank connections provide the following actions: - -* Initial setup of the connection - -* Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ) - - * These actions do not have any effect on the LibEuFin local bank account. - To persist changes to the local bank account (transaction history, payment request status), - the bank connection must be invoked via the bank account. - -* Import bank accounts - - * Some bank connection protocols allow LibEuFin to query a list of bank - accounts that the connection has access to. This makes setup easier, - as the user doesn't have to create the local bank account manually. - -Examples: - -.. code-block:: console - - # Manually request the inter-day account report via the EBICS C52 order - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connections/my-ebics-testacct/ebics/download/C52 - - # Download available bank accounts that can be accessed through this connection, - # according to the bank server (with EBICS, does a HTD request). - # For each of them, create a bank account resource in LibEuFin. - $ http -a $USER:$PASSWORD POST \ - https://example1.libeufin.tech/bank-connection/my-ebics-testacct/fetch-accounts - -Facades -------- - -Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts -and bank connections. A *facade* stores the following information: - -* Local name of the facade -* Facade type and options specific to the type -* Associated bank accounts and bank connections that can be accessed by the facade -* Internal tables used by the facade (i.e. facades are stateful) - -The only facade currently supported by LibEuFin is the "Taler Wire Gateway API" layer. -It provides a filtered view on the transaction history, a more restricted API to create payment -requests, and a mechanism to create a counter-transaction for incoming transactions that do -not conform to a certain format. - -Examples: - -.. code-block:: console - - # Request the Taler-specific history through the facade - $ http -a $USER:$PASSWORD \ - https://example1.libeufin.tech/facades/my-taler-wire-gw/taler/history/incoming - -Access Control -============== - -The goal of *access control* in LibEuFin is to allow the following scenarios: - -* The Nexus can be used by multiple clients for different bank accounts/connections - and these users can't access each other's bank accounts -* For monitoring / dashboard (e.g. Taler rejected transactions, blacklists), - some users should only be able to have read-only access. - -It is currently not planned to have more fine-grained permissions, such as -spending limits or more fine-grained read/write permissions. - -Users can be normal users or superusers. Permission checks do not apply to superusers, -and only superusers can create other users. - -Each top-level object (bank account, bank connection, facade) has a list of -nexus users with write access, and a list of users with read access. - -When using a bank connection through a bank account, permission checks must -succeed for both the bank account and the bank connection. - -This works differently for facades: A facade has a set of associated bank connections -and bank accounts it can access. Permissions on these associated objects -are checked when the facade is *created*. When invoking operations on the facade, -the nexus only checks if the current nexus user can access the facade and *not* the -underlying objects abstracted by the facade. diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst deleted file mode 100644 index 7c1fa2ae..00000000 --- a/libeufin/ebics.rst +++ /dev/null @@ -1,598 +0,0 @@ -.. target audience: core developer - -EBICS Implementation Notes -########################## - -.. warning:: - - This document summarizes and clarifies some aspects of the EBICS protocol - that are important to LibEuFin. Both version 3.0 and 2.5 are discussed here. - - It is not a specification, and it does not replace the official EBICS specification. - -.. contents:: Table of Contents - -EBICS Glossary -============== - -.. glossary:: - :sorted: - - A004 - Electronic signature process, used in :term:`H004`, deprecated in :term:`H005` with EBICS 3.0. - - A005 - Electronic signature process. Used in :term:`H004` and :term:`H005`. - - A006 - Electronic signature process. Used in :term:`H004` and :term:`H005`. - - BTF - *Business Transaction Formats.* Before EBICS 3.0, many different order types were - used for business-related messages. With EBICS 3.0, the more generic BTU and BTD - order types are used for all business-related messages. - - EBICS - The *Electronic Banking Internet Communication Standard*. - - ES - Electronic Signature. This abbreviation is commonly used in the context of EBICS. - - The following signature classes are defined (in descending order from - strongest to weakest): - - E - Single signature (German "Einzeln"). - A - First signature. - B - Second signature. - T - Transport signature. Only used to verify authorized submission, - but not to verify the bank-technical authorization. - - In H004 and H005, the ES of the bank is specified as a "planned feature" that - is not actually implemented yet. Thus banks in practice only use their - encryption key pair and authentication/identity key pair. - - EDS - Distributed Electronic Signature. Allows multiple subscribers to authorize an existing order. - - FTAM - Historical predecessor protocol to EBICS (*file transfer, access and management*). - - HEV - The *Host EBICS Version*. Queried by the client with an HEV request message. - - Human Subscriber - - See :term:`Subscriber`. - - H004 - Host protocol version 4. Refers to the XML Schema defined in *EBICS 2.5*. - - H005 - Host protocol version 5. Refers to the XML Schema defined in *EBICS 3.0*. - - Host ID - Alphanumeric identifier for the EBICS Host. One EBICS server can - host multiple banks, and each bank is identified by the Host ID. - This concept is similar to Taler's merchant backend instance identifiers. - - Order Number - Interchangeably called "Order ID". - - Each upload transaction gets a unique order number assigned by the bank server. - The Order Number is used to match VEUs in a second upload to the original order. - An Order Number matches the format ``[A-Z][A-Z0-9]{3}`` (and is not really a number!). - - Must be unique per customer ID and per order type. - - Transaction ID - A transaction ID is a 128-bit cryptographically strong random number. - It is assigned by the bank server for every transaction, i.e. upload or download - of an order. - - The transaction ID must not be guessable, as it would allow a potential - attacker to upload segments of an upload that do not match the whole message's digest. - - Transaction key - Symmetric encryption key for the data uploaded/downloaded in a transaction. - - Partner ID - In German, this is called "Kunden ID" (= Customer ID). - One partner can have multiple "participants", which are identified by user IDs. - - Practical example: A company has one Partner ID. Each person at the company - that can access the company's bank accounts gets their own User ID. - When the person is indirectly accessing the bank server (for example via - a client server application), an additional "System ID" is created for this - "technical subscriber". When there is no technical subscriber, the System ID - must be the same as the User ID. Usually the System ID is optional though. - - The ``(partner, user, system)`` triple uniquely identifies a subscriber. - - User ID - See :term:`Partner ID`. - - System ID - See :term:`Partner ID`. - - ISO 20022 - *ISO 20022: Financial Services - Universal financial industry message scheme*. Rather important - standard for financial industry **business-related** messages. In contrast, EBICS takes - care of message transmission, segmentation, authentication, key management, etc. - - The full catalogue of messages is `available gratis <https://www.iso20022.org/full_catalogue.page>`_. - - UNIFI - UNIversal Financial Industry message scheme. Sometimes used to refer to - :term:`ISO 20022`. - - Segmentation - EBICS implements its own protocol-level segmentation of business-related messages. - The segmentation can be seen as an alternative to the HTTP facilities of ``Accept-Ranges``. - - The order data of an EBICS message may not exceed 1 MB. The segmentation applies both - to requests and responses. - - Subscriber - Entity that wishes to communicate with the financial institution via EBICS. - - Subscribers can be *technical* or *human*. Technical subscribers are typically - a server in client-server applications, where the server talks to a financial institution - via EBICS. - - Requests from technical subscribers have a ``SystemID`` in addition to a ``PartnerID`` - and ``UserId``. A technical subscriber cannot sign a bank-technical request. - - Technical Subscriber - See :term:`Subscriber`. - - TLS - *Transport Layer Security*. All messages in EBICS are sent over HTTP with TLS. - In the current version of the standard, only server certificates are required. - - VEU - Distributed Electronic Signature (from German "Verteilte Elektronische Unterschrift"). - - V001 - FTAM encryption algorithm ("Verschlüsselung"), superseded in EBICS by E002. - - E002 - EBICS encryption process, used to encrypt the order payload. - - X002 - Identification and authentication signature in H004 and H005. - - -Order Types -=========== - -By convention, order types beginning with "H" are administrative order types, and other ones are -bank-technical order types. This convention isn't always followed consistently by EBICS. - -Relevant Order Types --------------------- - -.. ebics:orders:: - :sorted: - - BTD - **Only EBICS3.0+**. Business Transaction Format Download. - Administrative order type to download a file, described in more detail by the BTF structure. - - BTU - **Only EBICS3.0+**. Business Transaction Format Upload. - Administrative order type to upload a file, described in more detail by the BTF structure. - - C52 - **Before EBICS 3.0**. Download bank-to-customer account report (intra-day information). - - C53 - **Before EBICS 3.0**. Download bank-to-customer statement report (prior day bank statement). - - CRZ - Type: Download. - - Fetch payment status report (pain.002). - - CCC - Type: Upload. - - Send SEPA Credit Transfer Initiation (pain.001) via XML container. - This is the DFÜ variant (Appendix 3 DFÜ-Agreement). - - CCT - Type: Upload. - - Send SEPA Credit Transfer Initiation (pain.001) directly. - This is the DFÜ variant (Appendix 3 DFÜ-Agreement). - - CIZ - Type: Download. - - Payment Status Report for Credit Transfer Instant. - - FUL - **Before EBICS 3.0, France**. File Upload. Mainly used by France-style EBICS. - - FDL - **Before EBICS 3.0, France**. File Download. Mainly used by France-style EBICS. - - HAA - Type: Download, Optional. - - Download order types for which there is new data available. - - HTD - Type: Download. - - Download information about a subscriber. From German "Teilnehmerdaten". - - HKD - Type: Download, Optional. - - Download information about a customer (=partner). From German "Kundendaten". - - HIA - Transmission of the subscriber keys for (1) identification and authentication and (2) - encryption within the framework of subscriber initialisation. - - HPB - Query the three RSA keys of the financial institute. - - HPD - Host Parameter Data. Used to query the capabilities of the financial institution. - - INI - Transmission of the subscriber keys for bank-technical electronic signatures. - - HAC - Customer acknowledgement. Allows downloading a detailed "log" of the activities - done via EBICS, in the pain.002 XML format. - - HCS - Change keys without having to send a new INI/HIA letter. - - SPR - From German "sperren". Suspend a subscriber. Used when a key compromise is - suspected. - - HCS - Change the subscribers keys (``K_SIG``, ``K_IA`` and ``K_ENC``). - -Other Order Types ------------------ - -The following order types are, for now, not relevant for LibEuFin: - - -.. ebics:orders:: - :sorted: - - AZV - Type: Upload. - - From German "Auslandszahlungsverkehr". Used to submit - cross-border payments in a legacy format. - - CDZ - Type: Download. - - Download payment status report for direct debit. - - CCU - Type: Upload. - - German "Eilüberweisung". - - H3K - Type: Upload. - - Send all three RSA key pairs for initialization at once, accompanied - by a CA certificate for the keys. This is (as far as we know) used in France, - but not used by any German banks. When initializing a subscriber with H3K, - no INI and HIA letters are required. - - HVE - Type: Upload. - - Host Verification of Electronic Signature. Used to submit an electronic signature separately - from a previously uploaded order. - - HVD - Type: Download. - - Retrieve VEU state. - - HVU - Type: Download. - - Retrieve VEU overview. - - HVU - Type: Download. - - Retrieve VEU extra information. From German "Zusatzinformationen". - - HVS - Type: Upload. - - Cancel Previous Order (from German "Storno"). Used to submit an electronic signature separately - from a previously uploaded order. - - HSA - Type: Optional - - Order to migrate from FTAM to EBICS. **Removed in EBICS 3.0**. - - PUB - Type: Upload. - - Change of the bank-technical key (``K_SIG``). - Superseded by HSA. - - HCA - Type: Upload. - - Change the identification and authentication key as well as the encryption key (``K_IA`` and ``K_ENC``). - Superseded by HCS. - - PTK - Type: Download. - - Download a human-readable protocol of operations done via EBICS. - Mandatory for German banks. Superseded by the machine-readable - HAC order type. - - -EBICS Message Format -==================== - -The following elements are the allowed root elements of EBICS request/response messages: - -* ``ebicsHEVRequest`` / ``ebicsHEVResponse``: Always unauthenticated and unencrypted. Used - **only** for query/response of the host's EBICS version. -* ``ebicsUnsecuredRequest``: Request without signature or encryption (beyond TLS). Used for INI and HIA. -* ``ebicsKeyManagementResponse``: Unauthenticated response. Used for key management responses and - sometimes **also** to deliver error messages that are not signed by the bank (such as "invalid request"). -* ``ebicsNoPubKeyDigestsRequest``: Signed request that *does not* contain the hash of the bank's - public key that the client expects. Used for key management, specifically only the HPB order type. -* ``ebicsRequest`` / ``ebicsResponse`` -* ``ebicsUnsignedRequest``: Not used anymore. Was used in FTAM migration with the HSA order type. - - -Order ID Allocation -=================== - -In practice, the Order ID seems to be allocated via number of counters at the level of the **PartnerID**. - - -EBICS Transaction -================= - -A transaction in EBICS simply refers to the process of uploading or downloading -a file. Whether it is an upload or download transaction depends on the order -type. Each transaction is either an upload transaction or a download -transaction, neither both. - -Uploads and downloads must proceed in segments of at most ``1 MB``. The -segmentation happens after (1) encryption, (2) zipping, and (3) base64-encoding -of the order data. - -The number of segments is always fixed starting from the first message sent -(for uploads) or received (for downloads) by the subscriber. The digest of the -whole message is also sent/received with the first message of a transaction. -The EBICS host generates a 128-bit transaction ID. This ID is used to -correlate uploads/downloads of segments for the same transaction. - -If an attacker would be able to guess the transaction ID, they could upload a -bogus segment. This would only be detected after the whole file has been -transmitted. - -An upload transaction is finished when the subscriber has sent the last -segment. A download transaction is only finished when the subscriber has sent -an additional acknowledgement message to the EBICS host. - -When upload/download of a segment fails, the client can always re-try. There -are some conditions for that: - -* Segment ``n`` can only be downloaded/uploaded when segments ``[0..n-1]`` have - been downloaded/uploaded. -* The (implementation-defined) retry limit may not be exceeded. - - -Formats -======= - -ISO 20022 ---------- - -`ISO 20022 <https://www.iso20022.org/>`_ -is XML-based and defines the message format for many finance-related activities. - -ISO 20022 messages are identified by a message identifier in the following format: - - <business area> . <message identifier> . <variant> . <version> - -Some financial instututions (such as the Deutsche Kreditwirtschaft) have decided to use -a subset of elements/attributes in a message, this is what the ``<variant>`` part is for. -"Standard" ISO20022 have variant ``001``. - -The most important message types for LibEuFin are: - -camt - Cash Management - Particularly camt.053 (BankToCustomerStatement) - -pain - Payment Initiation - Particularly pain.001 (CustomerCreditTransferInitiation) to initiate a payment and - pain.002 (CustomerPaymentStatus) to get the status of a payment. - - -SWIFT Proprietary -================= - -SWIFT Proprietary messages are in a custom textual format. -The relevant messages are MT940 and MT942. - -* MT940 contains *pre-advice*, in the sense that transactions in it might still - change or be reversed. -* MT942 contains the settled transactions by the end of the day. - -SWIFT will eventually transition from MT messages to ISO20022, -but some banks might still only give us account statements in the old -SWIFT format. - - - -Key Management -============== - -RSA key pairs are used for three purposes: - -1. Authorization of requests by signing the order data. Called the *bank-technical key pair*, - abbreviated here as ``K_SIG``. -2. Identification/authentication of the subscriber. Called the *identification and authentication key pair*, - abbreviated here as ``K_IA``. -3. Decryption of the symmetric key used to decrypt the bank's response. Called the *encryption key pair*, - abbreviated here as ``K_ENC``. - -One subscriber *may* use three different key pairs for these purposes. -The identification and authentication key pair may be the same as the encryption key pair. -The bank-technical key pair may not be used for any other purpose. - - -Real-time Transactions -====================== - -Real-time transactions will be supported with EBICS starting November 2019. -That's the earliest date, some banks may offer it later or not at all. - -For us, :ebics:order:`CIZ` is the relevant order type that we need to ask banks -for. - - -Payment Reversal -================ - -It looks like there is no way to "reject" payments, unless you are the bank. - -There is a concept of payment reversal (with ``pain.007`` for direct debit and ``camt.055`` for SEPA Credit Transfer), -but they are a way for the *payer / sender* to reverse a payment before it is finalized. - - -Bank Support -============ - -All German banks that are part of the Deutsche Kreditwirtschaft *must* support EBICS. - -The exact subset of EBICS order types must be agreed on contractually by the bank and customer. -The following subsections list the message types that we know are supported by particular banks. - -GLS Bank --------- - -According to publicly available `forms -<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_, GLS Bank -supports the following order types: - -* :ebics:order:`AZV` -* :ebics:order:`PTK` -* :ebics:order:`CDZ` -* :ebics:order:`CRZ` -* :ebics:order:`CCC` -* :ebics:order:`CCT` -* :ebics:order:`CCU` -* :ebics:order:`HVE` -* :ebics:order:`HVS` -* ... and mandatory administrative messages - -Sparkasse München ------------------ - -See `this document <https://www.sskm.de/content/dam/myif/ssk-muenchen/work/dokumente/pdf/allgemein/ebics-default-geschaeftsvorfaelle.pdf>`__. - - -HypoVereinsbank ---------------- - -See `this document <https://www.hypovereinsbank.de/content/dam/hypovereinsbank/shared/pdf/Auftragsarten_Internet_Nov2018_181118.pdf>`__. - - -Cryptography -============ - -EBICS uses the XML Signature standard for signatures. It does *not* use XML encryption. - -The EBICS specification doesn't directly reference the standardized URIs for the various -signing algorithms. Some of these URIs are defined -in `RFC 6931 <https://tools.ietf.org/html/rfc6931>`__. - -* A005 is `<http://www.w3.org/2001/04/xmldsig-more#rsa-sha256>`__. - - * The ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme - mentioned in the EBICS spec. - -* A006 is `<http://www.w3.org/2007/05/xmldsig-more#rsa-pss>`__ as defined in RFC 6931. - -XML Signatures --------------- - -XML Signatures can be a combination of: - -* detached (referencing another document) -* enveloping (signs over ``Object`` tags *within* the ``Signature`` elements) -* enveloped (signs over arbitrary data (via XPath expression) in other parts of the document - that contains the signature). - -In EBICS, only **enveloped** signatures are used. - -In the XML Signature standard, the element for a signature is ``Signature``. EBICS violates this -standard by always mandating ``AuthSignature`` as the name. ``AuthSignature`` is an alias to -the ``SignatureType`` XSD type in the XML Schema. - -Canonicalization vs transforms: - * Canonicalization refers to the processing of the ``SignedInfo`` element. - * Transformations apply to the data that ``Reference`` elements reference. Canonicalization - algorithms can be used as a transformation on referenced data. - -Standards and Resources -======================= - -EBICS ------ - -The EBICS standard documents are available at `<http://www.ebics.org>`_. - -EBICS 3.0: - -* The main EBICS 3.0 specification - (``2017-03-29-EBICS_V_3.0-FinalVersion.pdf``). -* Annex 1 specifies EBICS return codes, as EBICS doesn't use HTTP status codes directly - (``2017-03-29-EBICS_V_3.0_Annex1_ReturnCodes-FinalVersion.pdf``) . -* Annex BTF contains the registry of BTF codes. - -DFÜ Agreement -------------- - -The DFÜ Agreement is the set of standards used by the German Banking Industry Committee (Deutsche Kreditwirtschaft). - -The following Annexes (also see the `DK Website <https://die-dk.de/zahlungsverkehr/electronic-banking/dfu-verfahren-ebics/>`_) are -relevant for implementing EBICS: - -* Annex 1 is the EBICS specification -* (Annex 2 is deprecated) -* Annex 3 describes the data formats used by German banks within EBICS. - -EBICS Compendium ----------------- - -The `EBICS Compendium <https://www.ppi.de/en/payments/ebics/ebics-compendium/>`_ has some additional info on EBICS. -It is published by a company that sells a proprietary EBICS server implementation. - -Others ------- - -* `<https://wiki.windata.de/index.php?title=EBICS-Auftragsarten>`_ -* `<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_ diff --git a/libeufin/enable-EBICS.png b/libeufin/enable-EBICS.png Binary files differnew file mode 100644 index 00000000..db2f3f03 --- /dev/null +++ b/libeufin/enable-EBICS.png diff --git a/libeufin/frontend.rst b/libeufin/frontend.rst deleted file mode 100644 index 1fe1c83f..00000000 --- a/libeufin/frontend.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. target audience: core developer - -################### -LibEuFin Frontend -################### - -Introduction -================ - -LibEuFin Frontend is a Single Page Application (SPA) built using React that facilitates setting up access to bank accounts, querying/displaying the transaction history of bank accounts and initiating payments. - -Architecture -=============== - -The frontend code sits in the */frontend* folder. Files in the subfolders are highlighted below. - -/actions, /reducers folder --------------------------- -Contains code that uses Redux to store the login state. Prevents user from relogging in every time they closed the browser or browser tab. - -/routes folder --------------- -Directs the user to the respective pages according to the URL route. Routes are broken down into *UnauthenticatedRoute* and *AuthenticatedRoute*, which corresponds to the user's login state. - -/components/login ------------------ -The login page for the user. - -/components/navbar ------------------- -Reusable navbar component that appears on every page of the project. - -/components/footer ------------------- -Reusable footer component that appears on every page of the project. - -components/home ---------------- -The home page showing general information of the users for e.g. bank accounts set up. - -/components/activity --------------------- -Shows activity of payments and its transaction history (WIP). - -/components/bank-accounts -------------------------- -Shows bank accounts that are imported. A bank account drawer is shown to facilitate setting up of bank accounts. Each bank account is displayed in a card to display extra details for e.g its print document. diff --git a/libeufin/get-EBICS-IDs-0.png b/libeufin/get-EBICS-IDs-0.png Binary files differnew file mode 100644 index 00000000..d64bfba5 --- /dev/null +++ b/libeufin/get-EBICS-IDs-0.png diff --git a/libeufin/get-EBICS-IDs-1.png b/libeufin/get-EBICS-IDs-1.png Binary files differnew file mode 100644 index 00000000..07cc2681 --- /dev/null +++ b/libeufin/get-EBICS-IDs-1.png diff --git a/libeufin/index.rst b/libeufin/index.rst index dd879e52..4fd7668c 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -1,22 +1,35 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2023 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + LibEuFin ######## LibEuFin is a project providing free software tooling for European FinTech. .. toctree:: + :maxdepth: 1 :glob: - concepts - bank-transport-ebics - api-common - api-nexus - api-sandbox - ebics - sepa - iso20022 - banking-protocols - transaction-identification - frontend - nexus-tutorial - local-currencies-tutorial - int-deployment-gv + nexus-manual + bank-manual + regional-automated-manual + regional-custom-manual + regional-manual-use + setup-ebics-at-postfinance diff --git a/libeufin/int-deployment-gv.rst b/libeufin/int-deployment-gv.rst deleted file mode 100644 index b3a12935..00000000 --- a/libeufin/int-deployment-gv.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. target audience: operator, developer - -Deploying Taler with libEufin -############################# - -.. contents:: Table of Contents - -This document shows how to compile and run all -the Taler services (including libEuFin). - -Deployment on Gv ----------------- - -After having pulled the latest code of deployment.git: - -.. code-block:: console - - $ python3 deployment/bin/WIP/taler-local bootstrap - $ python3 deployment/bin/WIP/taler-local build - $ python3 deployment/bin/WIP/taler-local prepare - -The last step offers also a way to specify the database -name -- only the PostgreSQL at this time -- and the hostname -of the reverse proxy. See ``--help`` for more information. - -At this point, the services can be launched, and will be -served at ``$hostname/$service``. The following command -will launch all the services and show what ``$service`` -can be: - -.. code-block:: console - - $ python3 deployment/bin/WIP/taler-local launch - -.. note:: - - In this context, one reverse proxy gets launched - along all the Taler services and will dispatch any request - to ``$service`` to the respective Unix domain socket. - -Withdraw with Taler -------------------- - -The following command withdraws a fixed amount of 5 units of currency -to the CLI wallet: - -.. code-block:: console - - $ python3 deployment/bin/WIP/taler-local withdraw - -The requests will be addressed to the default Sandbox, unless -``--bank-host`` (and ``--bank-proto``) were given; see ``--help`` -for more information. - -.. note:: - - To test phone wallets, the option ``--with-qr-code`` - can be specified. That will print a QR code on screen, and - wait for the user's input before confirming the payment to - the Exchange. - -Taler Internal deployment -------------------------- - -One deployment is currently hosted at ``int.taler.net``. - -Withdraw: - -.. code-block:: console - - $ python3 deployment/bin/WIP/taler-local withdraw --bank-host int.taler.net --bank-proto https diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst deleted file mode 100644 index 7b1fed8c..00000000 --- a/libeufin/iso20022.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. target audience: core developer - -ISO 20022 -######### - -ISO 20022 is the standard that defines many XML messages for FinTech. It is -very general, and often countries/orgs define subsets (TVS, technical -validation subset) of the schema. - -Documentation for message fields can be viewed at `<https://www.iso20022.org/standardsrepository>`__. - -The primary syntax for ISO 20022 messages is XML. To avoid LibEuFin clients -having to deal with XML, we define a mapping from ISO 20022 messages into JSON. - -The specifics of this mapping are: - - * The JSON should be "idiomatic" and easy to process. - * When possible, the highly nested structures of ISO 20022 should be flattened. - * It must be possible round-trip between the LibEuFin JSON and ISO 20022 - XML messages. The mapping of message types is not 1-to-1, as some ISO 20022 messages are - very similar and can be mapped to the same JSON structure. - * JSON-mapped messages are not explicitly versioned. Instead, changes - are made in a backwards-compatible way, possibly preserving old versions - of message elements in the same schema. - - -How does LibEuFin leverage ISO 20022? -===================================== - -While LibEuFin can communicate ISO 20022 messages (camt.05x, pain.001) to -other parties, it does **not** model its own authored API and internal data -after the ISO 20022 standard. - -Objections to ISO20022: - -1. Impedance mismatch. ISO 20022 messages do not map well to query/response - APIs. -2. Cumbersome to use. Even when ISO 20022 messages are directly mapped - to JSON, they are difficult to use due to their verbosity. -3. Underspecification. Messages like camt.05x leave many "degrees of freedom" - when translating the underlying data into a message. -4. No interoperability. As a result of underspecification, different countries/organizations - define their own subset and interpretation rules for ISO 20022 messages. This can - lead to even contradictory usage rules. An example for this is how the Swiss and EPC - interpretations handle transaction amounts in the presence of multiple currencies. -5. Redundancy. ISO 20022 are redundant, and often mix aspects of the "presentation logic" - with the underlying data model. An example of this is the optional "summary" information - in camt.05x messages. - -Instead of using ISO 20022 messages directly, LibEuFin leverages the standard in other ways: - -* As the data exchange format with banks -* As a guideline for naming in data formats -* As a guideline for which concepts need to be understood by LibEuFin - - -Implementation notes for camt.05x -================================= - -Types of amounts in camt messages ---------------------------------- - -* Entry amount - - * ISO 20022: Mandatory, with debit/credit indicator. Indicates money - moving in/out of the account in the account's currency. - * LibEuFin: Same. - -* Entry transaction amount - - * ISO 20022: Optional, direction-less. Amount of money - moving between the debtor and creditor bank, may not be - in the account's currency (but the "native" currency between - the two banks). - * LibEuFin: Same. - -* Entry instructed amount - - * ISO 20022: Optional, direction-less. Amount of money specified in the - payment initiation message. Usually only specified when the amount is in a - different currency than the account currency. - * LibEuFin: Same. - -* Entry counter value amount - - * ISO 20022: Optional, direction-less. Amount in the account's - currency before charges. - * LibEuFin: Same. - -* Entry announced posting amount - - * (not used by LibEuFin) - -* EntryDetails amount - - * ISO 20022: Optional, with debit-credit indicator. Same as "Entry amount" - but for EntryDetails (= logical transactions). - * LibEuFin: Always present. In Swiss camt messages, the element is always - present. In German/Swedish/... camt, we take the "Entry amount" for - non-batch entries, whereas in batch entries we use the "EntryDetails - transaction amount" with the same debit credit indicator as the whole - entry, which by local rules is always in the bank account currency. - -* EntryDetails (transaction / instructed / counter value) amount - - * ISO 20022: Optional, direction-less. Same as "Entry ... amount" - but for EntryDetails (= logical transactions). - * Same. - -* EntryDetails announced posting amount - - * (not used by LibEuFin) - - -LibEuFin schema for account history ------------------------------------ - -FIXME: This is not complete yet. - -.. code-block:: typescript - - interface NexusTransactionsReponse { - entries: NexusAccountEntryItem[]; - } - - interface NexusAccountEntryItem { - nexusEntryId: string; - - // Serial number that will increase with each update - // to the entry. - nexusStatusSequenceId: number; - - entry: AccountEntryItem; - } - - interface AccountEntryItem { - - // At least one of entryId or accountServicerRef - // must be non-null - entryId?: string; - accountServicerRef?: string; - - creditDebitIndicator: "credit" | "debit"; - amount: string; - currency: string; - instructedAmountDetails?: { - amount: string; - currency: string; - currencyExchange?: { - sourceCurrency: string; - targetCurrency: string; - unitCurrency: string; - exchangeRate: string; - contractId: string; - quotationDate: string; - }; - }; - status: "booked" | "pending" | "info"; - valueDate?: string; - bookingDate?: string; - mandateId?: string; - endToEndId?: string; - messageId?: string; - - creditor?: Party - creditorAgent?: FinancialInstitution; - creditorAccount?: FinancialInstitution; - - debtor?: Party - debtorAgent?: FinancialInstitution; - debtorAccount?: FinancialInstitution; - - unstructuredRemittanceInformation?: string; - bankTransactionCode: BankTransactionCode; - } - - interface Party { - name?: string; - partyType: "private" | "organization"; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface Account { - name?: string; - currency?: string; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface FinancialInstitution { - type: "financial-institution"; - name?: string; - bic?: string; - otherId?: { - id: string; - schemeName?: string; - issuer?: string; - }; - } - - interface BankTransactionCode { - domain?: string; - family?: string; - subfamily?: string; - proprietaryIssuer?: string; - proprietaryCode?: string; - } diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst deleted file mode 100644 index 8182b668..00000000 --- a/libeufin/local-currencies-tutorial.rst +++ /dev/null @@ -1,401 +0,0 @@ -Create a local currency (experimental) -###################################### - -This tutorial shows how to setup LibEuFin to act as the -bank of a local currency. The main features include the -registration and removal of user accounts *(only) by the -admin*, and the possibility to convert the local currency -into fiat (a.k.a. cashing out). - -The banking capabilities are offered by a LibEuFin service -called *Sandbox*. In particular, the tutorial relies on the -:ref:`Circuit API <circuit-api>`. More information about libEufin -can be found in the :doc:`How-To page </libeufin/nexus-tutorial>`. - -The following sections show how to install and launch Sandbox -either `from sources <install-from-sources_>`_, or `with Docker <docker-setup_>`_. - - -.. _install-from-sources: - -Install and config from sources -=============================== - -First :ref:`build LibEuFin <building-from-source>`. - -If the installation succeeded, configure *Sandbox* with the -following command. - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufin.sqlite3 - $ libeufin-sandbox config --currency NB --without-registrations default - -.. note:: - - The ``--without-registrations`` option allows *only the administrator* - to add new accounts. Without this option, other APIs may offer - unrestricted registrations. - -If the configuration step succeeded, Sandbox should be ready to serve the -bank for a currency named *NB*. - -In following step, we launch Sandbox by setting the administrator -password as ``secret``. - -.. note:: - - The following command launches Sandbox so that it writes - TANs on the filesystem to ease the cash-out operations without - relying on an `actual e-mail or SMS provider <email-sms-setup_>`_. -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret - $ libeufin-sandbox serve --port 5016 - -If Sandbox is running, jump to `this part <after-installation_>`_. - -.. _docker-setup: - - -Install and config with Docker -============================== - -First, clone the deployment repository: - -.. code-block:: console - - $ git clone git://git.taler.net/deployment - -Then navigate to the Docker image location: - -.. code-block:: console - - $ cd deployment/nlnet/task1 - -Now build the image with the following command. - -.. code-block:: console - - $ docker build -t nlnet . - -If the build step went well, the following command -should suffice to start Sandbox and NGINX, by mapping -the host's 8080 port to the container's 80. - -.. code-block:: console - - $ export LIBEUFIN_EXPOSED_PORT=8080 - $ docker run \ - -e LIBEUFIN_EXPOSED_PORT=$LIBEUFIN_EXPOSED_PORT \ - -p $LIBEUFIN_EXPOSED_PORT:80 \ - -it nlnet - -The previous command uses a default admin password of 'admin'. -Do **CHANGE** the admin password in a production scenario. The -following command shows how to start the services with custom -values. - -.. note:: - - Start the services this way to provide the environment - suitable for this tutorial. - -.. code-block:: console - - $ export MY_ADMIN_PASSWORD=secret - $ export LIBEUFIN_EXPOSED_PORT=8080 - $ docker run \ - -e LIBEUFIN_SANDBOX_ADMIN_PASSWORD=$MY_ADMIN_PASSWORD \ - -e CURRENCY=NB \ - -e LIBEUFIN_EXPOSED_PORT=$LIBEUFIN_EXPOSED_PORT \ - -v libeufin_data:/libeufin-data \ - -v /tmp:/tmp \ - -p $LIBEUFIN_EXPOSED_PORT:80 \ - -p 5016:5016 \ - -it nlnet - -In the example above, Docker: - -0. Sets the admin password to *secret* -1. Sets the currency to *NB* -2. Stores the database in a *volume*. This helps to - share the database between containers. -3. Mounts container's ``/tmp`` to the host's, to let - the reader obtain the file TAN in the same way the - source-based installation does. -4. Maps the host's 8080 to the container's 80 port. -5. Maps the host's 5016 to the container's 5016 port. - That lets the CLI reach Sandbox inside the container, - and therefore run the tutorial. - -By success, Web browsers get the UI by visiting **http://localhost:8080** - -The following command shows how to delete the database, -by deleting its volume. - -.. code-block:: console - - $ docker volume rm libeufin_data - -Note: the removal might fail because the exited containers -are seen as still using the container. Please refer to the Docker -documentation for further information. - -.. _after-installation: - -If Sandbox is running -===================== - -Sandbox should now be reachable on the port 5016. Check it with: - -.. code-block:: console - - $ curl http://localhost:5016 - -If Sandbox is correctly running, it should respond with a greeting message. -At this point, the administrator can add a new merchant to the bank with the -following command. - -.. note:: - - Consult :doc:`this document </libeufin/circuit-cli-commands>`, - to learn all the CLI commands that address the (Circuit) API - used in this tutorial. - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=admin - export LIBEUFIN_SANDBOX_PASSWORD=secret - export LIBEUFIN_SANDBOX_URL=http://localhost:5016/ - export LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD=shop-secret - - libeufin-cli \ - sandbox \ - demobank \ - circuit-register \ - --name "Circuit Shop" \ - --username circuit-shop \ - --cashout-address payto://iban/CH463312 \ - --internal-iban INT940993 - -If the previous step succeeded, the merchant should have -access to their bank account with the *circuit-shop* username -and *shop-secret* password. - -Check it by asking the merchant balance with the following command. -The two environment variables LIBEUFIN_SANDBOX_USERNAME and -LIBEUFIN_SANDBOX_PASSWORD instruct the CLI to authenticate as the -merchant. - - -.. _check-balance: - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=circuit-shop - export LIBEUFIN_SANDBOX_PASSWORD=shop-secret - - libeufin-cli sandbox demobank info --bank-account circuit-shop - -The expected response looks like the following one: - - -.. code-block:: console - - { - "balance" : { - "amount" : "NB:0", - "credit_debit_indicator" : "credit" - }, - "paytoUri" : "payto://iban/SANDBOXX/INT940993?receiver-name=Circuit+Shop", - "iban" : "INT940993" - } - -In the following example, the merchant creates a cash-out operation, -trying to convert 1 NB back to the fiat currency. The ``--amount-debit`` -option takes the amount that the merchant wants to be debited -in their local currency bank account, whereas the ``--amount-credit`` -option is the calculation of the conversion rates as expected -by the merchant. The two values will be checked by the bank along -this request, to make sure that both parties agree. - -.. note:: - - The current version has a fixed **0.95** conversion rate for cashing - out. Future version will make this value configurable. - -.. code-block:: console - - libeufin-cli \ - sandbox \ - demobank \ - circuit-cashout \ - --amount-debit=NB:1 \ - --amount-credit=CHF:0.95 \ - --tan-channel=file - -If the previous command succeeded, it returned a JSON looking -like the following, although most likely having a **different** -UUID. - -.. code-block:: console - - { - "uuid" : "de12389b-e477-4a0c-829e-f779c1cfb3a0" - } - -The *uuid* represents the cash-out operation being just created -and waiting to be confirmed with a TAN. - -.. note:: - - The current version provides **only** the local currency - side of such operation. In other words, the merchant can - now only see a deduction on their local currency bank account - but no incoming payment in their fiat bank account. Future - versions will implement this. - -Confirm now the cash-out operation by sending to the -bank the TAN found in the file ``/tmp/libeufin-cashout-tan.txt``. -Assuming that the TAN for it is ``WXYZ``, the next command will confirm -it to the bank (please, use **your** UUID). - -.. code-block:: console - - libeufin-cli \ - sandbox demobank circuit-cashout-confirm \ - --uuid de12389b-e477-4a0c-829e-f779c1cfb3a0 \ - --tan WXYZ - -Check now that the cash-out operation appears as a outgoing -transaction for the merchant: - -.. code-block:: console - - libeufin-cli \ - sandbox demobank list-transactions \ - --bank-account circuit-shop - -The expected output should contain one line like the -following. That witnesses that the cash-out was correctly -confirmed and scheduled to be transferred to the fiat -account. - -.. code-block:: console - - "subject" : "Cash-out of NB:1 to CHF:0.95" - -The next commands show how to delete one account from -the local currency circuit. For the deletion to succeed, -the account must have a balance of zero NB. Because -of the cash-out operation, the merchant has now -1 NB -to their account, therefore the deletion will fail. Check -it, as the administrator, with the following command - - -.. _delete-account: - -.. code-block:: console - - export LIBEUFIN_SANDBOX_USERNAME=admin - export LIBEUFIN_SANDBOX_PASSWORD=secret - - libeufin-cli \ - sandbox demobank \ - circuit-delete-account --username circuit-shop - -The expected output is: - -.. code-block:: console - - Unexpected response status: 412 - Response: { - "error" : { - "type" : "sandbox-error", - "description" : "Account circuit-shop doesn't have zero balance. Won't delete it" - } - } - - -The bank may now award 1 NB to the merchant to bring their -balance to zero and finally delete the account. With the following -command, the administrator awards 1 NB to the merchant. - -.. code-block:: console - - libeufin-cli \ - sandbox demobank new-transaction \ - --bank-account admin \ - --payto-with-subject "payto://iban/SANDBOXX/INT940993?message=bring-to-zero" \ - --amount NB:1 - -Check if the balance returned to zero with `this command <check-balance_>`_, -and try again to delete the account `like already done <delete-account_>`_ - -Now the deletion command should have succeeded! -Try to `ask the balance <check-balance_>`_ again, and expect one -error like the following: - - -.. code-block:: console - - { - "error" : { - "type" : "util-error", - "description" : "Customer 'circuit-shop' not found" - } - } - - -.. note:: - - Every Circuit API endpoint is addressed by a CLI subcommand - whose name starts with ``circuit-``. The following command - shows them. - - .. code-block:: console - - libeufin-cli sandbox demobank | grep circuit - -.. _email-sms-setup: - -E-mail or SMS TAN setup ------------------------ - -SMS and E-mail TANs get sent via commands that -are invoked by the Sandbox. Sandbox learns about those commands -via optional parameters to the ``serve`` command. - -.. note:: - - Future versions will allow setting the external commands - via the configuration; follow `#7527 <https://bugs.gnunet.org/view.php?id=7527>`_. - -Hence, starting Sandbox as shown in the following commands is -the **only** requirement to use the aforementioned TAN channels. - -For the SMS TAN: - -.. code-block:: console - - libeufin-sandbox serve --sms-tan sms_provider_command - -Alternatively, for the e-mail TAN: - -.. code-block:: console - - libeufin-sandbox serve --email-tan email_provider_command - -Both commands will be passed the TAN to STDIN and the target -phone number / e-mail address as their first command line argument. - -.. note:: - - The way the invoked commands interact with their providers - is out of the Sandbox scope. - -Finally, Libeufin ships two TAN commands as example. The e-mail -command relies on `GNU mail <mailutils.org>`_ and the SMS command -on the service offered by `<telesign.com>`_. Check ``contrib/libeufin-tan-sms.sh`` -and ``contrib/libeufin-tan-email.sh`` in the Libeufin repository. diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst new file mode 100644 index 00000000..de2f4bae --- /dev/null +++ b/libeufin/nexus-manual.rst @@ -0,0 +1,277 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + +.. target audience: operator, developer + +.. _libeufin-nexus: + +Nexus Manual +############ + +LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to +setup EBICS access, download banking records, and submit payments. Today, the +LibEuFin implementation supports EBICS 2.5 and 3.0 and has been tested with +the Postfinance (CHF). Please note that banks tend to have their own dialects +of finance messages and thus other retail banks may or may not work. Contact +us if you need support for another bank or core banking protocol. + +Future versions will offer a Web API to allow Taler exchanges to talk to their +banks. + +In this manual, we explain how to setup an EBICS subscriber. We assume that +the bank has already granted EBICS access to the subscriber. + +.. contents:: Table of Contents + :local: + + +Installing Nexus +================ + +The following section was tested on an *OpenJDK 17* environment. + + +Installing the libeufin-nexus binary packages on Debian +------------------------------------------------------- + +.. include:: ../frags/installing-debian.rst + +.. include:: ../frags/apt-install-libeufin-nexus.rst + + +Installing the libeufin-nexus binary packages on Ubuntu +------------------------------------------------------- + +.. include:: ../frags/installing-ubuntu.rst + +.. include:: ../frags/apt-install-libeufin-nexus.rst + + +Building from source +-------------------- + +Nexus belongs to the LibEuFin project, and can be downloaded via Git: + +.. code-block:: console + + $ git clone git://git.taler.net/libeufin + +Note that Kotlin and Gradle should already work on the host system. + +Navigate into the *libeufin* local repository, and from top-level run: + +.. code-block:: console + + $ ./bootstrap + $ ./configure --prefix=$PREFIX + $ make install + +If the previous steps succeeded, the ``libeufin-nexus`` command should +be found in the $PATH. + +.. _ebics-setup: + +Setting up the EBICS subscriber +=============================== + +.. include:: ../frags/nexus-ebics-setup.rst + +Database setup +============== + +The configuration file must include a connection string that +tells Nexus how it should connect to the database. The default +is: + +.. code-block:: ini + + [nexus-postgres] + config = postgres:///nexus + +You must make sure that this database exists and is accessible to the user +running Nexus before continuing. Then, the Nexus database schema must be +created (or updated) to the current Nexus version using the following command: + +.. code-block:: console + + $ libeufin-nexus-dbinit -c "$CONFIG_FILE" + +where ``$CONFIG_FILE`` is again the path to a configuration that contains at +least the above ``[nexus-postgres]`` section. + +.. _sending-payments: + +Sending payments +================ + +Sending payments must follow a successful `EBICS subscriber setup +<ebics-setup>`_, where the bank obtained the subscriber keys, and the +subscriber accepted the bank keys. Furthermore, the database has to +be set up. Right now, some other process must queue payments to be +submitted to the database, so this section only discusses how such +queued payments will be executed. + +The responsible subcommand for sending payments is ``ebics-submit``, and its +configuration is a **superset** of core-config_. On top of that, it expects +the database connection string and *optionally* a frequency at which it will +check for submittable payments in the database. + +The frequency **may** be specified as + +.. code-block:: ini + + [nexus-submit] + FREQUENCY = 5m + +The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). + + +For testing +----------- + +The ``ebics-submit`` subcommand is **not** suitable to send arbitrary +payments, but rather to submit initiated payments that are already queued for +submission in the Nexus database. + +Such queued payments may originate from bounces of incoming payments with a +subject that would be invalid for a Taler withdrawal, or from a Taler exchange +that needs to send a payment to a merchant. + +For testing purposes it is possible to manually initiate a payment using the +``initiate-payment`` subcommand. +The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!" +subject: + +.. code-block:: console + + $ libeufin-nexus initiate-payment -c "$CONFIG_FILE" --subject "Hello, Nexus!" "payto://iban/CH987654321?receiver-name=Name&amount=CHF:1" + +``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need +the FREQUENCY value. If the previous command worked, now the database should +contain a new row in the ``initiated_outgoing_transactions`` table, with an +``unsubmitted`` submission state. + +The following command would now pick such an unsubmitted initiated payment and +send it to the bank. + + +.. code-block:: console + + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient + +The ``--transient`` flag instructs the software to perform only one pass on +the database, submit what is submittable, and return. + +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/submit`` where ``$YYYY-MM-DD`` represents the +date when the upload took place. This is mostly useful for debugging. + +For production +-------------- + +The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode. + +The fixed frequency mode causes the command to check the database every time the +frequency period expires. To activate this mode, and -- for example -- set a frequency +of five minutes, set the configuration value ``FREQUENCY`` to ``5m``. Assuming that +``FREQUENCY`` is set as described above, the following invocation would +make ``ebics-submit`` check the database every five minutes, and submit any initiated +payment according to their submission state. + +.. code-block:: console + + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" + +Transient mode causes ``ebics-submit`` to check the database only once, submit any +initiated payment according to their submission state, and return. + +.. code-block:: console + + $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" + + +.. _receive-transaction-data: + +Downloading payment records +=========================== + +Downloading payments must follow a successful `EBICS subscriber setup +<ebics-setup>`_, where the bank obtained the subscriber keys, and the +subscriber accepted the bank keys. Furthermore, the database has to +be set up. + +The responsible subcommand for sending payments is ``ebics-fetch``, and its +configuration is a **superset** of core-config_. On top of that, it expects +the database connection string and *optionally* a frequency at which it will +downloads any new EBICS files and ingest them in the database. + +The frequency **may** be specified as + +.. code-block:: ini + + [nexus-fetch] + FREQUENCY = 5m + +The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours). + +Assuming that ``$CONFIG_FILE`` contains all required options, the following +command would download any unseen EBICS files: + +.. code-block:: console + + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient + +The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download +then parse EBICS files and ingest their content statements into its local +database. + +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: + +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. + +The ``--transient`` flag makes the command download and import EBICS files only +once and return immediately afterwards. Without the flag, Nexus +will download at the frequency specified in the configuration. + +The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in +``$SAVEDIR/$YYYY-MM-DD/fetch`` where ``$YYYY-MM-DD`` represents the +date when the download took place. This is mostly useful for debugging. + + +For Testing +----------- + +If the bank account history has transactions that are useful for testing, it is +possible to re-download them via the ``--pinned-start`` argument. + +The following command redownloads transactions *from* the pinned start until +the present: + +.. code-block:: console + + $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-11-01 + +.. note:: + + If the Nexus database already contains the bank account history, you might need + to **reset** the database in order to have the re-downloaded transactions be + properly ingested. Be careful when resetting the database: resetting the wrong + database might cause DATA LOSS! diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst deleted file mode 100644 index fc7b9f0a..00000000 --- a/libeufin/nexus-tutorial.rst +++ /dev/null @@ -1,868 +0,0 @@ -.. target audience: operator, developer - -LibEuFin How-To -############### - -.. contents:: Table of Contents - -The LibEuFin Nexus is a Web service that provides a JSON abstraction layer to -access bank accounts. It does **not** itself offer banking services, but is a -translator between JSON requests and other banking protocols (such as EBICS), -that are offered by banks. - -This document explains how to set up Nexus to access a bank account -via the EBICS protocol. - -In order to follow all the steps below, the reader should either -have access to a bank account with EBICS support or follow the -steps in :ref:`Configuring the Sandbox <configuring-the-sandbox>`. - - -Installing LibEuFin -=================== - -Installation on Debian ----------------------- - -.. include:: ../frags/installing-debian.rst - -To install LibEuFin, you can now simply run: - -.. code-block:: console - - # apt install libeufin-nexus libeufin-sandbox - -Administration via SystemD --------------------------- - -After the Debian installation, the installed unit files -should be listed by the following command: - -.. code-block:: console - - # systemctl list-unit-files | egrep '(nexus|sandbox)' - -Both ``nexus.service`` and ``sandbox.service`` should appear. - -At this point, the services can be started on boot: - -.. code-block:: console - - # systemctl enable libeufin-nexus # use 'disable' to rollback - # systemctl enable libeufin-sandbox # only if you want the sandbox - -Or just manually: - -.. code-block:: console - - # systemctl start libeufin-nexus # use 'stop' to terminate. - # systemctl start libeufin-sandbox # only if you want the sandbox - -The following command should inform the user about the status -of the running / terminated service: - -.. code-block:: console - - # systemctl status libeufin-nexus - -For more diagnostics, use: - -.. code-block:: console - - # journalctl -u libeufin-nexus - -Run-time dependencies ---------------------- - -LibEuFin has the following run-time dependencies: - -* OpenJDK 11 -* Python 3.8 -* python3-click (can be installed via ``pip3 install click``) -* python3-requests (can be installed via ``pip3 install requests``) - -These dependencies only need to be installed manually when building from source -or using the prebuilt binaries. - -Downloading prebuilt binaries ------------------------------ - -Pre-built packages can be obtained from the `taler.net website -<https://taler.net/files/libeufin>`__. - -Unpack the ``libeufin-$version.zip`` file to -your desired location (typically ``/opt`` or ``~/opt``) and make sure that your ``PATH`` -environment variable contains the ``bin/`` directory of the unpacked archive. - - -.. _building-from-source: - -Building from source --------------------- - -Nexus belongs to the LibEuFin project, and can be downloaded via Git: - -.. code-block:: console - - $ git clone git://git.taler.net/libeufin - -It is recommended to run the ``v0.9.1`` version, hence -the following command may now be given. - -.. code-block:: console - - $ git checkout v0.9.1 - -Note that Kotlin and Gradle should already work on the host system. - -Navigate into the *libeufin* local repository, and from top-level run: - -.. code-block:: console - - $ ./bootstrap - $ ./configure --prefix=$PREFIX - $ make install # Note: This may require Java=18; Java=17 had errors, Java>=19 is unsupported by Gradle - -Verifying your installation ---------------------------- - -In case of success, the three following commands should be found: - -.. code-block:: console - - $ which libeufin-nexus - $ which libeufin-sandbox - $ which libeufin-cli - - -.. _configuring-the-sandbox: - -Configuring the Sandbox (Optional) -================================== - -If you don't have access to a real bank account with an EBICS API, you can set -up the sandbox. The sandbox is a simplistic and incomplete implementation of a -core banking system with EBICS access to bank accounts. - -The sandbox uses HTTP Basic auth, with username ``admin``. -Choose a password and set env var ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` to it. - -The sandbox relies on a database, which you must specify using a JDBC -connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment -variable, before invoking any commands. -If this variable is not set, ``libeufin-sandbox`` complains and exits: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret - $ libeufin-sandbox serve - DB connection string not found/valid in the env variable LIBEUFIN_SANDBOX_DB_CONNECTION. - The following two examples are valid connection strings: - jdbc:sqlite:/tmp/libeufindb.sqlite3 - jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret - -Only *SQLite* and *PostgreSQL (via TCP)* are supported right now. - -Before being usable, a Sandbox needs to be configured. This is done -by creating the ``default`` demobank. A demobank is a set of configuration -values associated to one name; in the example below, we'll create one -named ``default``, that is mandatory to have. - -.. note:: - - By design, many demobanks can be hosted by one running Sandbox, - although at the time of writing only the ``default`` one is supported. - -A default demobank having the EUR currency is created with the following command: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb - $ libeufin-sandbox config --currency EUR default - -In order to use Taler, a default exchange needs to be configured. - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb - $ libeufin-sandbox default-exchange --demobank default $exchange_base_url $exchange_payto_address - -The sandbox service can now be started with the following command: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret - $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufintestdb - $ libeufin-sandbox serve --port 5016 - -The instructions below hook Nginx to the Sandbox: - -.. code-block:: nginx - - redirect / to /demobanks/default; - rewrite ^/$ https://$host/demobanks/default; - location / { - proxy_set_header Host $host; - proxy_set_header X-Forwarded-Host $host; - proxy_set_header X-Forwarded-Proto "https"; - proxy_set_header X-Forwarded-Prefix "/"; - proxy_pass http://localhost:5016/; - } - -To reset the state of the sandbox, delete the database. - -For invocations of the LibEuFin command-line interface tool (``libeufin-cli``), -the following environment variables must be set to the authentication -information, and the URL of the sandbox service: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=admin - $ export LIBEUFIN_SANDBOX_PASSWORD=secret - $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016 - -Note that the password is the same as for ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD``. -Verify that the sandbox is running: - -.. code-block:: console - - $ libeufin-cli sandbox check - Hello, this is the Sandbox - -Now an EBICS host can be created: - -.. code-block:: console - - $ libeufin-cli sandbox ebicshost create --host-id testhost - $ libeufin-cli sandbox ebicshost list - { - "ebicsHosts" : [ "testhost" ] - } - -Note that most ``libeufin-cli`` subcommands will ask for input interactively if -the respective value is not specified on the command line. - -Next, register a user. For the ``libeufin-cli sandbox demobank register`` -command, the ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` -are assumed to be ``jrluser`` and ``easy``, respectively. - -.. note:: - - All the following commands address the ``default`` demobank, see ``libeufin-cli sandbox demobank --help``. - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=jrluser - $ export LIBEUFIN_SANDBOX_PASSWORD=easy - $ libeufin-cli sandbox demobank register - -Check the balance of the user just created: - -.. code-block:: console - - $ libeufin-cli sandbox \ - demobank info --bank-account jrluser - -With a user registered, we can now create an EBICS subscriber (identified by -the partner ID and user ID) for the host. This command requires admin -privileges, so ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` -are reset back to ``admin`` and ``secret``, respectively. - -.. The plan is to replace the ‘sandbox ebicssubscriber list’ command - below with a ‘sandbox demobank show-ebicssubscriber’ command. - Need to implement it first! - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=admin - $ export LIBEUFIN_SANDBOX_PASSWORD=secret - $ libeufin-cli sandbox \ - demobank new-ebicssubscriber \ - --host-id testhost \ - --partner-id partner01 \ - --user-id user02 \ - --bank-account jrluser - $ libeufin-cli sandbox ebicssubscriber list - { - "subscribers" : [ { - "hostID" : "testhost", - "partnerID" : "partner01", - "userID" : "user02", - "systemID" : null, - "demobankAccountLabel" : "jrluser" - } ] - } - -The ``libeufin-cli sandbox demobank new-ebicssubscriber`` command -also creates an associated bank account. You can see it with command: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount list - [ { - "label" : "bank", - "name" : "Bank account owner's name", - "iban" : "DE895351", - "bic" : "SANDBOXX" - }, { - "label" : "jrluser", - "name" : "Bank account owner's name", - "iban" : "DE724881", - "bic" : "SANDBOXX" - } ] - -The account name ``jrluser`` is the unique identifier of the account within -the sandbox. The EBICS parameters identify the subscriber that should have -access to the bank account via EBICS. - -The account already has one transaction, the "Sign-up bonus" from the bank. -Note that in the following examples we transition to using the ``bankaccount`` -subcommand, because there is no need to rely on EBICS: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount transactions jrluser - { - "payments" : [ { - "accountLabel" : "jrluser", - "creditorIban" : "DE724881", - "creditorBic" : "SANDBOXX", - "creditorName" : "Unknown", - "debtorIban" : "DE895351", - "debtorBic" : "SANDBOXX", - "debtorName" : "The Bank", - "amount" : "100", - "currency" : "EUR", - "subject" : "Sign-up bonus", - "date" : "Tue, 22 Feb 2022 00:04:15 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "2NG75I0O", - "paymentInformationId" : null - } ] - } - -To populate the account with some more transactions, run the following command: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount generate-transactions jrluser - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction jrluser \ - --debtor-iban DE06500105174526623718 \ - --debtor-bic INGDDEFFXXX \ - --debtor-name "Joe Foo" \ - --subject "Hello World" \ - --amount 10.50 - -Now the list of transactions has grown by several entries: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount transactions jrluser - { - "payments" : [ { - "accountLabel" : "jrluser", - "creditorIban" : "DE724881", - "creditorBic" : "SANDBOXX", - "creditorName" : "Unknown", - "debtorIban" : "DE895351", - "debtorBic" : "SANDBOXX", - "debtorName" : "The Bank", - "amount" : "100", - "currency" : "EUR", - "subject" : "Sign-up bonus", - "date" : "Tue, 22 Feb 2022 00:04:15 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "2NG75I0O", - "paymentInformationId" : null - }, { - "accountLabel" : "jrluser", - "creditorIban" : "DE724881", - "creditorBic" : "SANDBOXX", - "creditorName" : "Creditor Name", - "debtorIban" : "DE64500105178797276788", - "debtorBic" : "DEUTDEBB101", - "debtorName" : "Max Mustermann", - "amount" : "22", - "currency" : "EUR", - "subject" : "sample transaction GSF7S5LC", - "date" : "Tue, 22 Feb 2022 01:26:18 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "GSF7S5LC", - "paymentInformationId" : null - }, { - "accountLabel" : "jrluser", - "creditorIban" : "DE64500105178797276788", - "creditorBic" : "DEUTDEBB101", - "creditorName" : "Max Mustermann", - "debtorIban" : "DE724881", - "debtorBic" : "SANDBOXX", - "debtorName" : "Debitor Name", - "amount" : "10", - "currency" : "EUR", - "subject" : "sample transaction 1WUP303Q", - "date" : "Tue, 22 Feb 2022 01:26:18 GMT", - "creditDebitIndicator" : "debit", - "accountServicerReference" : "1WUP303Q", - "paymentInformationId" : null - }, { - "accountLabel" : "jrluser", - "creditorIban" : "DE724881", - "creditorBic" : "SANDBOXX", - "creditorName" : "Creditor Name", - "debtorIban" : "DE06500105174526623718", - "debtorBic" : "INGDDEFFXXX", - "debtorName" : "Joe Foo", - "amount" : "10.50", - "currency" : "EUR", - "subject" : "Hello World", - "date" : "Tue, 22 Feb 2022 01:26:41 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "sandbox-ALQP8TXKJWRVKMAH", - "paymentInformationId" : null - } ] - } - -Lastly, you will want to schedule some tasks to run -periodically in the background. -This enables the Nexus to interact in (almost) real-time with the bank. - -.. code-block:: console - - $ libeufin-cli accounts task-schedule jrluser \ - --task-type submit \ - --task-name submit-payments-each-second \ - --task-cronspec "* * *" - $ libeufin-cli accounts task-schedule jrluser \ - --task-type fetch \ - --task-name fetch-reports-each-second \ - --task-cronspec "* * *" \ - --task-param-level report \ - --task-param-range-type latest - -The first task submits payments and the second fetches reports. -Both are specified to run every second (cronspec ``"* * *"``). -To reduce the frequency to every five seconds, use the cronspec ``"*/5 * *"`` -(remember to quote, to protect from shell filename expansion). - -.. note:: - - The sandbox is intended as a testing tool and thus not stable. - -.. _disable-registrations: - -Disable registrations (experimental) ------------------------------------- - -Demobanks can disable/enable registrations for new users. -The responsible options are -``--with-registrations`` / ``--without-registrations``. - -For more information on the available commands, use the built-in ``--help`` flag. -The full functionality of the sandbox is available via -the :ref:`Sandbox API <sandbox-api>`. - -Connect Nexus with an EBICS account -=================================== - -Nexus relies on a database, which you must specify using a JDBC -connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment -variable, before invoking any commands. -(If this variable is not set, ``libeufin-nexus`` complains and exits.) - -Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)* -(e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``) -are supported right now. - -Use the following command to run the Nexus service: - - Neuxs defaults to *not* storing the messages that it downloads - from the bank. To revert this behaviour, export also the environment - variable ``LIBEUFIN_NEXUS_KEEP_BANK_MESSAGES`` to ``yes`` before - running the following command. - -.. code-block:: console - - $ export LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:postgresql://localhost:5433/libeufindb?user=foo&password=secret - $ libeufin-nexus serve --port 5017 - -This assumes that the PostgreSQL service with a database -called ``libeufindb`` listens on port 5433 -for requests from the Nexus service. -The Nexus service itself listens on port 5017. -Note that you must have the ``LIBEUFIN_NEXUS_DB_CONNECTION`` -environment variable set for most uses of the libeufin-nexus -command. - -At this point a superuser account needs to be created: - -.. code-block:: console - - $ libeufin-nexus superuser foo --password secret - -If you omit ``--password secret``, you will interactively be asked for a password. -For simplicity, a superuser can as well act as a normal user, but an API -to create less privileged users is offered. - -.. note:: - - User and permissions management in LibEuFin is still under development. - In particular, permissions for non-superusers are very limited at the moment. - -The command line interface needs the following three values -to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``, -and ``LIBEUFIN_NEXUS_PASSWORD``. In this example, ``LIBEUFIN_NEXUS_USERNAME`` should be -set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its password -in the previous step (with the ``libeufin-nexus superuser`` command). The -``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017``. - -Next, we create a EBICS *bank connection* that Nexus can use to communicate with the bank. - -.. note:: - - For the sandbox setup in this guide, the ``EBICS_BASE_URL`` - should be ``http://localhost:5016/ebicsweb``. - This is the value of environment variable - ``LIBEUFIN_SANDBOX_URL`` suffixed with ``/ebicsweb``, - since the sandbox will be providing EBICS services. - - Similarly, ``EBICS_HOST_ID`` should be ``testhost``, - and ``EBICS_PARTNER_ID`` should be ``partner01``. - For ``EBICS_USER_ID`` we will use ``user02`` (for account ``jrluser``), - and for ``CONNECTION_NAME``, we will use ``conn01``. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - new-ebics-connection \ - --ebics-url $EBICS_BASE_URL \ - --host-id $EBICS_HOST_ID \ - --partner-id $EBICS_PARTNER_ID \ - --ebics-user-id $EBICS_USER_ID \ - $CONNECTION_NAME - -If this step executes correctly -(use ``libeufin-cli connections list-connections`` -and ``libeufin-cli connections show-connection`` to check), -Nexus will have created all the cryptographic -material that is needed on the client side; in this EBICS example, it created -the signature and identification keys. It is therefore advisable to *make -a backup copy* of such keys. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - export-backup \ - --passphrase $SECRET \ - --output-file $BACKUP_FILE \ - $CONNECTION_NAME - -At this point, Nexus needs to both communicate its keys to the bank, and -download the bank's keys. This synchronization happens through the INI, HIA, and -finally, HPB message types. - -After the electronic synchronization, the subscriber must confirm their keys -by sending a physical mail to the bank. The following command helps generating -such letter: - -.. code-block:: console - - $ libeufin-cli connections get-key-letter $CONNECTION_NAME out.pdf - -.. note:: - - When using the LibEuFin sandbox, subscribers are automatically - activated after keys are received electronically. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - connect \ - $CONNECTION_NAME - -Once the connection is synchronized, Nexus needs to import locally the data -corresponding to the bank accounts offered by the bank connection just made. -The command below downloads the list of the bank accounts offered by ``$CONNECTION_NAME``. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - download-bank-accounts \ - $CONNECTION_NAME - -It is now possible to list the accounts offered by the connection. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - list-offered-bank-accounts \ - $CONNECTION_NAME - -.. note:: - - The ``nexusBankAccountId`` field should at this step be ``null``, - as we have not yet imported the bank account and thus the account - does not yet have a local name. - -Nexus now needs an explicit import of the accounts it should manage. This -step is needed to let the user pick a custom name for such accounts. - -.. code-block:: console - - $ libeufin-cli \ - connections \ - import-bank-account \ - --offered-account-id testacct01 \ - --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \ - $CONNECTION_NAME - -Once a Nexus user imported a bank account (``$LOCAL_ACCOUNT_NAME``) -under a certain connection (``$CONNECTION_NAME``), it is possible -to accomplish the usual operations for any bank account: asking for the -list of transactions, and making a payment. - -Request history of transactions -=============================== - -The LibEuFin Nexus keeps a local copy of the bank account's transaction -history. Before querying transactions locally, it is necessary -to request transactions for the bank account via the bank connection. - -This command asks Nexus to download the latest transaction reports/statements -through the bank connection: - -.. code-block:: console - - $ libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME - -.. note:: - - By default, the latest available transactions are fetched. It is also - possible to specify a custom date range (or even all available transactions) - and the type of transactions to fetch (inter-day statements or intra-day - reports). - -Once Nexus has stored all the information in the database, the -client can ask to actually see the transactions: - -.. code-block:: console - - $ libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME - -Make a payment -============== - -Payments pass through two phases: preparation and submission. The preparation -phase assigns the payment initiation a unique ID, which prevents accidental -double submissions of payments in case of network failures or other -disruptions. - - -The following command prepares a payment: - -.. code-block:: console - - $ libeufin-cli accounts prepare-payment \ - --creditor-iban=$IBAN_TO_SEND_MONEY_TO \ - --creditor-bic=$BIC_TO_SEND_MONEY_TO \ - --creditor-name=$CREDITOR_NAME \ - --payment-amount=$AMOUNT \ - --payment-subject=$SUBJECT \ - $LOCAL_ACCOUNT_NAME - -Note: the ``$AMOUNT`` value needs the format ``CURRENCY:X.Y``; for example -``EUR:10``, or ``EUR:1.01``. - -The previous command should return a value (``$UUID``) that uniquely -identifies the prepared payment in the Nexus system. That is needed -in the next step, to **send the payment instructions to the bank**: - -.. code-block:: console - - $ libeufin-cli accounts submit-payments \ - --payment-uuid $UUID \ - $LOCAL_ACCOUNT_NAME - -Automatic scheduling -==================== - -With an EBICS bank connection, the LibEuFin Nexus needs to regularly query for -new transactions and (re-)submit prepared payments. - -It is possible to schedule these tasks via an external task scheduler such as -cron(8). However, the Nexus also has an internal task scheduling mechanism for -accounts. - - -The following three commands create a schedule for submitting payments hourly, -fetching transactions (intra-day reports) every 5 minutes, and (inter-day statements) -once at 11pm every day : - -.. code-block:: console - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="submit" \ - --task-name='submit-payments-hourly' \ - --task-cronspec='0 0 *' - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="fetch" \ - --task-name='fetch-5min' \ - --task-cronspec='0 */5 *' \ - --task-param-level=report \ - --task-param-range-type=latest - - $ libeufin-cli accounts task-schedule myacct \ - --task-type="fetch" \ - --task-name='fetch-daily' \ - --task-cronspec='0 0 23' \ - --task-param-level=statement \ - --task-param-range-type=latest - -The cronspec has the following format, which is slightly non-standard due to -the ``SECONDS`` field - -.. code-block:: none - - SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] DAY-OF-WEEK[optional] - - -Restore the backup -================== - -The following command restores all the details associated with -one bank connection subscription. For EBICS, this means that the -INI and HIA secret keys will be restored for the requesting user. - -.. code-block:: console - - $ libeufin-cli connections \ - restore-backup \ - --passphrase=$SECRET \ - --backup-file=$BACKUP_FILE \ - $CONNECTION_NAME - -.. - FIXME: - On a bad password given, Nexus responds - "bad backup given" instead of "authentication failed". - - -Creating a Taler facade -======================= - -Facades are additional abstraction layers that can serve -specific purposes. For example, one application might need -a filtered version of the transaction history, or it might -want to refuse payments that do not conform to certain rules. - -At this moment, only the *Taler facade type* is implemented -in the Nexus, and the command below instantiates one under a -existing bank account / connection pair. You can freely -assign an identifier for the ``$FACADE_NAME`` below: - -.. code-block:: console - - $ libeufin-cli facades new-taler-wire-gateway-facade \ - --currency EUR \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $LOCAL_ACCOUNT_NAME - -At this point, the additional *taler-wire-gateway* (FIXME: link -here to API here) API becomes offered by the Nexus. The purpose -is to let a Taler exchange rely on Nexus to manage its bank account. - -The base URL of the facade that can be used by the Taler exchange -as the Taler Wire Gateway base URL located when listing the facades: - -.. code-block:: console - - $ libeufin-cli facades list - -Creating a Anastasis facade -=========================== - -The following command creates a Anastasis facade. At this point, *only* -the superuser is able to create facades; please set the environment variables -``LIBEUFIN_NEXUS_USERNAME`` and ``LIBEUFIN_NEXUS_PASSWORD`` accordingly. - -.. code-block:: console - - $ libeufin-cli facades new-anastasis-facade \ - --currency EUR \ - --facade-name $FACADE_NAME \ - $CONNECTION_NAME \ - $LOCAL_ACCOUNT_NAME - -If the previous command succeeded, it is possible to see the -facade's base URL with: - -.. code-block:: console - - $ libeufin-cli facades list - -At this point, to allow a non superuser to use the facade, a history -permission needs to be set: - -.. code-block:: console - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.anastasis.history - -.. note:: - - There is no need to set/unset a transfer permission on the facade - since this one does not offer any endpoint to issue wire transfers. - -Managing Permissions and Users -============================== - -This guide has so far assumed that a superuser is accessing the LibEuFin Nexus. -However, it is advisable that the Nexus is accessed with users that only have a -minimal set of permissions. - -The Nexus currently only has support for giving non-superusers access to Taler -wire gateway facades. - -To create a new user, use the ``users`` subcommand of the CLI: - -.. code-block:: console - - $ libeufin-cli users list - # [ ... shows available users ... ] - - $ libeufin-cli users create $USERNAME - # [ ... will prompt for password ... ] - -Permissions are managed with the ``permissions`` subcommand. -The following commands grant permissions to view the transaction history -and create payment initiations with a Taler wire gateway facade: - - -.. code-block:: console - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerWireGateway.history - - $ libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerWireGateway.transfer - -The list of all granted permissions can be reviewed: - -.. code-block:: console - - $ libeufin-cli permissions list diff --git a/libeufin/no-accounts.png b/libeufin/no-accounts.png Binary files differnew file mode 100644 index 00000000..a180f7a1 --- /dev/null +++ b/libeufin/no-accounts.png diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst new file mode 100644 index 00000000..39dfd3f6 --- /dev/null +++ b/libeufin/regional-automated-manual.rst @@ -0,0 +1,260 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + +.. target audience: operator + +Regional Currency Automated Setup Manual +######################################## + +This manual describes how to setup a regional currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual<regional-custom-manual>`. + + +.. contents:: Table of Contents + :local: + +.. include:: ../frags/regional-manual-architecture.rst + +Guided Automated Setup +====================== + +Prerequisites ++++++++++++++ + +For this manual, we assume that the system is deployed on a contemporary +Debian GNU/Linux Bookworm or Ubuntu Mantic system using the binary packages provided. +Furthermore, you should run the process on a system with one or more globally +reachable IP address(es) *and* with various DNS names already pointing to +these IPs. + +Preparing the required subdomain names +++++++++++++++++++++++++++++++++++++++ + +The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component. +These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name, +where you can create type (A) entries, as subdomains pointing to your own server public IP address. +A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is +to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly. + +Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have +propagated over the Internet correctly, and they are currently publicly available. + +You can check this from your terminal very easily with the "ping" command, as this: + +.. code-block:: console + + $ ping -c1 bank.$DOMAIN_NAME + $ ping -c1 exchange.$DOMAIN_NAME + $ ping -c1 backend.$DOMAIN_NAME + +You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for the same purpose, and to check the propagation status. + +.. warning:: + Take into account some hosting providers providing virtualized servers (VPS or VDS) can enable by default the firewall program "UFW", blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https. + +Now you are ready to go with the next step. + +Obtaining the Scripts ++++++++++++++++++++++ + +First, download the deployment scripts via Git: + +.. code-block:: console + + # apt update && apt install git + $ git clone git://git.taler.net/deployment + +Running the Guided Configuration +++++++++++++++++++++++++++++++++ + +Navigate into the *regional-currency/* directory and run *main.sh* as **root**: + +.. code-block:: console + + $ cd deployment/regional-currency/ + # ./main.sh + +The script will start by installing the required packages and then asking you fundamental questions about the desired setup, in particular: + +#. Wether to encrypt, when stored on disk, sensible configurations such as the admin password. +#. The name of the regional currency. It must have 3 to 11 letters. +#. Whether to setup the regional currency to be backed by a fiat currency. You'll need a bank account at a fiat currency bank offering an online banking protocol supported by LibEuFin Nexus. If you answer ``y``, you will also need to provide the following information: + + #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'. + #. The IBAN of the fiat bank account. + #. The BIC of the fiat bank account. + #. The legal name of the fiat bank account. + +#. The name of the regional currency bank. It will be shown to business users when they interact with the system. +#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN_NAME``, ``exchange.$DOMAIN_NAME`` and ``backend.$DOMAIN_NAME``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer). +#. Whether to use TLS or not. You should answer ``y`` in most cases. +#. Whether to setup SMS two-factor authentication using `Telesign <https://www.telesign.com>`_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. You should answer ``y`` in most cases. +#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one. +#. Whether to generate terms of service (ToS) for the exchange from default templates. +#. Whether to generate a privacy policy for the exchange from default templates. + +The information you entered as well as the generated bank admin password will +be stored in a file called ``config/user.conf``. If you run the script in +the future again (for example, to upgrade the installation), you will not be asked +these questions a second time. + +After answering all of the questions, the actual installation will start. The +scripts will download and configure various packages, which may take some time. +Grab a coffee. + +.. note:: + + At this point, the setup is NOT connected to any fiat bank account! The next + steps must always be done manually! + +Running the script again from scratch ++++++++++++++++++++++++++++++++++++++ + +If for some reason your installation doesn't work because you have answered erroneously +some of the interactive questions, or you just want to reset the current installation and to re-deploy +the script again for having its latest changes, you will have to proceed as follows: + +In brief, you need to wipe completely the "content" of the file config/user.conf, this doesn't mean +to remove the file itself, but only its content. Even though you can do this manually by editing the file manually +with your preferred text editor, you can also do this in one single command. + +.. code-block:: console + + # rm config/user.conf + +.. note:: + + In future versions of the program when executed for the second time, the program itself will + show an option to offer wiping the content of this config/user.conf file, automatically. + +Multi-factor authentication ++++++++++++++++++++++++++++ + +The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication <libeufin-mfa>`. + +If you choose not to back your regional currency with a fiat currency, you can stop here. + +Web-based Configuration ++++++++++++++++++++++++ + +By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. + +Connecting to a Fiat Bank: the EBICS setup +++++++++++++++++++++++++++++++++++++++++++ + +To complete the conversion setup, you have to set up an EBICS subscriber using the fiat bank account you specified during the automated setup. + +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file. + +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + If this is not possible, use the ``IGNORE_TRANSACTIONS_BEFORE`` configuration to ignore old transactions. + +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + # Bank + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 + +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + +Reuse existing client keys +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have client keys from a previous EBICS setup you can copy the JSON file to ``/var/lib/libeufin-nexus/client-ebics-keys.json``. + +Make sure this file is accessible to the user running ``libeufin-nexus``, you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json + +Create new client keys +^^^^^^^^^^^^^^^^^^^^^^ + +Run the following command to start the EBICS setup process: + +.. code-block:: console + + $ sudo -u libeufin-nexus libeufin-nexus ebics-setup + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document you can continue. + +Get bank keys +^^^^^^^^^^^^^ + +Run the following command to finish the EBICS setup process: + +.. code-block:: console + + $ sudo -u libeufin-nexus libeufin-nexus ebics-setup + +The EBICS setup is finished once the bank keys have been accepted. + + +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ + +In our automated setup the second account is automatically set up correctly +without fees or special restrictions. However, various additional +*restrictions* and *options* could be configured. Details are explained in +the :ref:`regional conversion setup <regional-conversion-setup>` section for the +manual setup and in the the manpage of ``taler-exchange-offline``. + + +.. include:: ../frags/regional-system-on.rst +.. include:: ../frags/deploying-tos.rst + + +Installing Updates +++++++++++++++++++ + +The standard procedure for installing updates is to: + +* First, make a backup (!) +* Stop Taler services +* Install new version +* Upgrade databases +* Start Taler services + +The "upgrade.sh" script in the "regional-currency/" folder of "deployment.git" +shows how to do the above steps *except* for the backup. For the backup, all +critical bits of data will be in the Postgresql databases. Thus, we recommend +following the database manual on making backups. diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst new file mode 100644 index 00000000..4a347791 --- /dev/null +++ b/libeufin/regional-custom-manual.rst @@ -0,0 +1,180 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + + +.. target audience: operator + +Regional Currency Custom Setup Manual +##################################### + +This manual describes how to setup a regional currency manually. If you want a guided setup you can follow the :doc:`automated setup manual<regional-automated-manual>`. + +.. contents:: Table of Contents + :local: + +.. include:: ../frags/regional-manual-architecture.rst + +Custom Manual Setup +=================== + +You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate it with a Taler exchange. + +If you don't want your regional currency to be backed by a fiat currency, you can stop here. + +Enabling Currency Conversion +++++++++++++++++++++++++++++ + +You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account at a bank dealing in fiat currency that +offers an online banking protocol supported by LibEuFin Nexus. + +Next, you have to enable conversion and should ensure that at least one TAN +channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured. + +The following snippet shows how to enable conversion in ``libeufin-bank`` configuration: + +.. code-block:: ini + + [libeufin-bank] + ALLOW_CONVERSION = YES + FIAT_CURRENCY = EUR + +Make sure to (re)start the libeufin-bank after changing +these configuration options: + +.. code-block:: console + + # systemctl restart libeufin-bank + + +Web-based Configuration ++++++++++++++++++++++++ + +Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. + +.. _regional-conversion-setup: + +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ + +An exchange that supports currency conversion needs to advertise two bank +accounts, one in the regional currency and a second in the fiat currency. The +conversion logic ensures that wire transfers in either account are +immediately reflected in the other account. + +This section explains how to enable currency conversion at the exchange, +which is critical for wallets to know how to wire fiat currency to an +exchange to obtain regional currency. + +You will need to use the ``taler-exchange-offline`` tool to inform the +exchange about the **fiat** bank account that can be used for cash in +operations and also specify the URL for currency conversion. Additionally, +you may also configure restrictions on the bank accounts that may originate +the funds, for example, to prevent international wire transfers that may expose +you to additional compliance risks. + +Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as +the (URL-encoded) name of the exchange-account owner, the following +``taler-exchange-offline`` invocation can be used to notify wallets about +the possibility of currency conversion (cash in): + +.. code-block:: console + + # source config/user.conf + # sudo -u taler-exchange-offline \ + taler-exchange-offline \ + wire-fee now iban "${CURRENCY}":0 "${CURRENCY}":0 \ + enable-account \ + "${CONVERSION_PAYTO}" \ + conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \ + display-hint 10 "CHF" \ + debit-restriction deny \ + credit-restriction \ + regex \ + 'payto://iban/.*/CH.*?receiver-name=.*' \ + 'Swiss only' \ + '{"de":"nur Schweiz","fr":"Suisse uniquement"}' \ + upload + +Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion +endpoint of the bank, which should be +``https://bank.$DOMAIN/conversion-info/`` in our setup. + +The above commands set up the exchange to perform conversion with a +restriction to only accept credit transfers from Swiss bank accounts. You may +want to configure such restrictions on the bank accounts that may originate +funds to prevent international wire transfers that may expose you to +additional compliance risks. + +You can leave out the "credit-restriction" if you want to allow international +inbound wire transfers. + +The "debit-restriction" is largely mandatory as in this setup the +``taler-exchange-transfer`` is only configured to deal with the regional +currency bank. Crediting fiat bank accounts must thus be done via the +cash-out functionality of the regional currency bank account. + +The "display-hint" gives priority (10) for the fiat cash-in account over the +regional currency account in the withdraw dialog of the wallets and labels the +account with "CHF". + +.. note:: + + The above command adds a **second** bank account to the exchange. + You (or the guided setup script) should have already enabled the + regional currency bank account (without any "conversion-url"). + +.. include:: ../frags/regional-system-on.rst +.. include:: ../frags/deploying-tos.rst + + +Maintenance ++++++++++++ + +The ``taler-exchange-offline`` commands given above set fees only for the +current year (``now``). Thus, before January 1st of each year, you must to set +up new fees for the new calendar year. In a regional currency setup, this +typically requires up to three annual settings: + +.. code-block:: console + + # YEAR=2025 # edit if necessary + # FIAT_CURRENCY=CHF # edit if necessary + # REGIO_CURRENCY=NETZBON # edit if necessary + # sudo -u taler-exchange-offline \ + taler-exchange-offline \ + wire-fee "$YEAR" \ + iban "${FIAT_CURRENCY}":0 "${FIAT_CURRENCY}":0 \ + wire-fee "$YEAR" \ + x-taler-bank "${REGIO_CURRENCY}":0 "${REGIO_CURRENCY}":0 \ + global-fee $YEAR \ + "${REGIO_CURRENCY}:0" \ + "${REGIO_CURRENCY}:0" \ + "${REGIO_CURRENCY}:0" \ + 4w 6y 4 \ + upload + +If the fees are not all zero, simply change the respective place to specify +a non-zero fee. + +.. note:: + + Additionally, the denomination signing keys will only have been + pre-generated for some time, depending on your ``LOOKAHEAD_SIGN`` + configuration option. Thus, you may need to periodically run + the "taler-exchange-offline download sign upload" sequence as well! diff --git a/libeufin/regional-manual-use.rst b/libeufin/regional-manual-use.rst new file mode 100644 index 00000000..ff9f38f8 --- /dev/null +++ b/libeufin/regional-manual-use.rst @@ -0,0 +1,129 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + +.. _regional-use: + +Using the Regional Currency +=========================== + +The very first step you should check after the installation process has been +completed successfully, is to make sure all three URLs (bank, backend and exchange), +are available (this means to see a Website, and not any NGINX error). + + +Bank backend walkthrough ++++++++++++++++++++++++++ + +- As stated above, please visit before "https://bank.$DOMAIN_NAME", to make sure it is available. + +- Now login with the username "admin" and the password you have choosen during the installation process, or use the one which might + have been generated automatically (and shown on your terminal screen), during the installation process. + Once inside the Bank Administrator area, please create the "very first" customer account. + +- Transfer some funds from the "admin" bank account to this new customer account. + +- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make sure the funds you have transfered from admin, have arrived correctly. + +- Now, please choose the option "Send Money to a Taler Wallet", and try to send for example 100 units of your regional currency to the + wallet installed on your browser or mobile phone. + +- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital currency you have choosen, during your installation process, let's say Netzbon. + +- Lastly, you can also try to transfer funds to another "bank account",for that you will need to know the recipient's username or the bank account ID. + +If you have successfully accomplished all the previous steps, for the bank administrator +backend and your installed Wallet, you can move now to test other components such +as the Merchant backend (https://backend.$DOMAIN_NAME). + +Wallet Setup +++++++++++++ + +This section describes the interaction between the Taler graphical wallet (Android, +iOS, WebExtensions) and the regional currency system. + +You need to add your regional currency exchange to the wallet. This can +be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN_NAME/$MASTER_PUBLIC_KEY`` +URL or by manually entering the URL into the respective ``Add exchange`` +dialogue. + +.. _regional-use-cashin: + +Cash-In ++++++++ + +Next, start the withdraw process in the Taler wallet for the respective +currency and specify the desired amount. The wallet will then show you the +details of the fiat wire transfer that must be made for the cash-in to be +completed. Once the money has arrived at the fiat bank account, Nexus will +obtain the transaction data and the regional currency bank will create the +corresponding amount in regional currency, crediting the GNU Taler exchange +account. In turn, the exchange will issue the respective amount to your +wallet. + +.. note:: + + Cash-in operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + +.. warning:: + + Cash-in operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed. + +Making payments ++++++++++++++++ + +For testing, you should be able to *deposit* regional currency directly into +your regional currency libeufin-bank account directly from the Taler wallet. +For this, you primarily need to know your bank account details (which should +be accessible by clicking on your name in the bank Web site after logging in). + +.. note:: + + There may be a short delay between the wallet making the deposit and + the exchange crediting your bank account. This is because the wallet + uses a small wire transfer delay by default when initiating a deposit + into a bank account. + +For production, it is more common for a shop to configure a :ref:`Taler +merchant backend <taler-merchant-backend-operator-manual>` or at least use an +instance within such a setup. To configure an instance, you primarily need +again the bank account details to :ref:`setup instance bank accounts +<instance-bank-account>`. + +.. _regional-use-cashout: + +Cash-Out +++++++++ + +Regional currency accounts that have a positive balance could be eligible for +cash-out. Cash-out operations may again be restricted by the regional +currency operator and will *only* be made to the respective pre-configured +fiat currency bank account. To cash-out, simply log into your regional +currency account, select cash-out, specify the desired amount and pass the +second-factor authorization challenge by entering the TAN you receive at the +registered e-mail address or mobile phone number. + +.. note:: + + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + +.. warning:: + + Cash-out operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed. diff --git a/libeufin/sepa.rst b/libeufin/sepa.rst deleted file mode 100644 index 29baca00..00000000 --- a/libeufin/sepa.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. target audience: core developer - -SEPA Payments -############# - -This page collects reference materials and details for specifics of SEPA payments. - -SEPA Credit Transfer (SCT) -========================== - -SCT is a "normal" bank transfer. Details (terminology, data definitions, flow diagrams) can be found in the EPC's -`SCT rulebook <https://www.europeanpaymentscouncil.eu/document-library/rulebooks/sepa-credit-transfer-rulebook>`__. - - -Reject vs Return vs Recall --------------------------- - -* A **rejected** payment is refused by the originator bank or the - clearing and settlement layer. -* A **returned** payment is refused by the beneficiary's bank via a - counter-transaction over the settlement layer. -* A payment is **recalled** when the originator's bank (potentially - requested by the originator) wants to "undo" a SCT. - -SEPA currently does **not** directly support a mechanism for the **beneficiary** to return -a payment. diff --git a/libeufin/set-EBICS-keys.png b/libeufin/set-EBICS-keys.png Binary files differnew file mode 100644 index 00000000..71ecfa86 --- /dev/null +++ b/libeufin/set-EBICS-keys.png diff --git a/libeufin/set-IBAN.png b/libeufin/set-IBAN.png Binary files differnew file mode 100644 index 00000000..277019e5 --- /dev/null +++ b/libeufin/set-IBAN.png diff --git a/libeufin/set-ISO-2019-0.png b/libeufin/set-ISO-2019-0.png Binary files differnew file mode 100644 index 00000000..34bfe8dc --- /dev/null +++ b/libeufin/set-ISO-2019-0.png diff --git a/libeufin/set-ISO-2019-1.png b/libeufin/set-ISO-2019-1.png Binary files differnew file mode 100644 index 00000000..8f45922e --- /dev/null +++ b/libeufin/set-ISO-2019-1.png diff --git a/libeufin/set-english-and-register.png b/libeufin/set-english-and-register.png Binary files differnew file mode 100644 index 00000000..5e88c1d7 --- /dev/null +++ b/libeufin/set-english-and-register.png diff --git a/libeufin/setup-ebics-at-postfinance.rst b/libeufin/setup-ebics-at-postfinance.rst new file mode 100644 index 00000000..161bc6d3 --- /dev/null +++ b/libeufin/setup-ebics-at-postfinance.rst @@ -0,0 +1,90 @@ +Setup EBICS at PostFinance test platform +######################################## + +In this tutorial, we will set up one EBICS 3 account at the PostFinance +test platform, in order to test the ``postfinance`` dialect from ``libeufin-nexus``. + +The first requirement is to create one account `there <https://isotest.postfinance.ch>`_. +It is advised to set the language as English, as this tutorial is meant +for the international audience. + +Set the language in the drop-down menu and navigate to the registration +section as it is shown below: + +.. image:: set-english-and-register.png + +Even if the above page doesn't welcome you in English, the two boxes in the +screenshot will still hold their position, so please look for box #1 to +set the language and for box #2 to get the page that offers to register. + +After a successful registration, an IBAN needs to be associated with +the user just created. Likely after the first login, the following +page should appear. Click then on box #2. + +.. note:: + + The navigation bar in the screenshot below is ubiquitous, + so click on box #1 if the depicted page did not show up automatically. + +.. image:: no-accounts.png + +If the following page appears, please obtain a checksum-valid but fictitious +Swiss IBAN and enter it as indicated by box #1 and then save it (box #2). + +.. _my-iban: + +.. image:: set-IBAN.png + +If the bank responds with a successful message, the next step is to enable +EBICS 3 and set the format of the ISO20022 documents. + +.. note:: + + There is no "use EBICS 3" setting since EBICS 3 is a "side effect" + of choosing one particular ISO format for banking records. + +To use EBICS 3, click the navigation bar item highlighted in the +following screenshot. + +.. image:: set-ISO-2019-0.png + +The following page should appear, where the ISO format can be specified +as it is depicted in the following screenshot. + +.. image:: set-ISO-2019-1.png + +After having saved the setting, proceed now to set the flavor +of payment confirmations. This setting instructs the bank to define +particular XML nodes when it releases the payment confirmations. Even +if each document is ISO20022, this step is essential because ISO20022 +has many optional fields and client and bank must agree on which fields +appear in the documents. + +Hover on box #1 and then click on box #2. + +.. image:: camt.054-style-0.png + +If the following page appears, please set everything as it is shown below: + +.. image:: camt.054-style-1.png + +.. _get-ebics-ids: + +The last step is to retrieve the user's EBICS identifiers, namely the +EBICS user and partner IDs. Hover on box #1 and then click on box #2. + +.. image:: get-EBICS-IDs-0.png + +At the first access, the following page should appear. Simply create +EBICS access and continue to the next step. + +.. image:: enable-EBICS.png + +After having obtained the following page, finally the EBICS identifiers +are shown in box #1. + +.. image:: get-EBICS-IDs-1.png + +Finally, box #2 contains the bank keys fingerprints. These are +important to check that the client, along the keying process, has obtained +the right bank keys. diff --git a/libeufin/transaction-identification.rst b/libeufin/transaction-identification.rst deleted file mode 100644 index 6c88a727..00000000 --- a/libeufin/transaction-identification.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. target audience: developer, core developer - -Transaction Identification -########################## - -This page describes how bank transactions are **identified** in various banking protocols and -data formats. - -**Why is transaction identification necessary?** -When a client downloads the transaction history from some data source, it has to know -whether a transaction is new, or whether the transaction is already part of the -client's local records. - -Protocol-specific Details -========================= - -ISO 20022 camt.05X ------------------- - -The camt52/53/54 messages defined by ISO 20022 do not have a mandatory transaction -identifier. Instead it defines a handful of optional references. - -Two identifiers seem to be used in practice: The *Account Servicer Reference* and the -*Entry Reference*. Of these, only the *Account Servicer Reference* seems to be useful -for transaction identification. - -The Account Servicer Reference is assigned by the bank to a transaction. In -practice, all banks assign the **same** Account Servicer Reference to the same -transaction showing up in camt52 (the account report), camt53 (the account -statement) and camt53 (credit notifications). - -The Account Servicer Reference is assigned by the bank that reports the transaction, -and does **not** serve as a globally unique identifier for the transaction. - -However, in rare cases, a transaction can be reported that does not yet have an -Account Servicer Reference assigned to it by the bank yet. This can happen -when the bank only received a (SWIFT) pre-notification for the transaction, but decides -to already pass on this information to the customer. In this case, banks seem to -assign an *Entry Reference* to the corresponding entry. - -Most other transactions, however, do **not** have an *Entry Reference* assigned to it. -Some banks document that the *Entry Reference* is only unique within one report for one account. - -OFX ---- - -OFX assigns a transaction identifier to each reported transactions, allowing the client -to know which transactions it has already seen. - -Problems and Possible Solutions -=============================== - -Sometimes the same bank can offer **multiple** ways to download transactions. -In Germany, most banks offer EBICS and FinTS access, which delivers transactions -in the camt.52/53 format. However, some also offer access via PSD2 APIs and completely custom APIs. - -Two APIs from the same bank do not necessarily need to support the same transaction identification scheme. -This could lead to the same transaction showing up multiple times in the account transaction history, which -is clearly bad! - -LibEuFin intends to solve this problem in the following ways: - -1. Each local account has a single "transaction identification scheme". - Importing transactions via a bank connection that has a different transaction - identifier scheme will fail. -2. When a bank connection reports a transaction that is missing the expected transaction identifier, - the status (booked, pending, info) is examined: - - 1. When the status is booked, an error is reported, and corresponding bank message - will be made available for review. - 2. When the status is "pending" or "info", the entry will simply be ignored. - -In the future, this might be extended to be less restrictive: - -* An account could be configured to do transaction identification based on a "core attributes hash", - i.e. a cryptographic hash of core attributes of the transactions that are expected to not change. - This should only apply to booked transactions. -* Un-identifiable pending/info transactions could be managed in a separate - "informational" transactions table that is purged as soon as a *booked statement closing transaction* - is reported with a higher booking date. - -Others -====== - -* `UETR <https://www.swift.com/your-needs/industry-themes/unique-end-to-end-transaction-reference-uetr>`__ is - a unique identifier used on the SWIFT level. It doesn't help for transaction identification - as not every transaction goes over SWIFT, even for SEPA accounts. |
