diff options
Diffstat (limited to 'design-documents/050-libeufin-nexus.rst')
| -rw-r--r-- | design-documents/050-libeufin-nexus.rst | 79 |
1 files changed, 58 insertions, 21 deletions
diff --git a/design-documents/050-libeufin-nexus.rst b/design-documents/050-libeufin-nexus.rst index 779e0b58..6049bda6 100644 --- a/design-documents/050-libeufin-nexus.rst +++ b/design-documents/050-libeufin-nexus.rst @@ -59,11 +59,11 @@ Configuration file HOST_ID = mybank USER_ID = myuser PARTNER_ID = myorg - SYSTEM_ID = banksys - ACCOUNT_NUMBER = DE1234567890 # This value must identify with how the bank calls the bank account + IBAN = MY-IBAN + BIC = MY-BIC + NAME = MY NAME BANK_PUBLIC_KEYS_FILE = enc-auth-keys.json CLIENT_PRIVATE_KEYS_FILE = my-private-keys.json - ACCOUNT_META_DATA_FILE = ebics-meta.json BANK_DIALECT = postfinance # EBICS+ISO20022 style used by the bank. [nexus-postgres] @@ -112,15 +112,6 @@ JSON with: * submitted_ini (boolean) * submitted_hia (boolean) -File contents: ACCOUNT_META_DATA_FILE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -JSON with: - - * account_holder_iban - * bank_code - * account_holder_name - Database schema --------------- @@ -194,15 +185,6 @@ The ebics-setup tool performs the following: accept them (or auto-accept via --auto-accept-keys). If the user accepted the public key, update the flag to "accepted". - * If all of the above has happened and we have accepted public keys from the - bank, try to download the list of bank accounts associated with the - connection and check that the configured account number is among them. On - success, store the associated meta data in the account meta data file. On - failure, show an error message with the list of available accounts (also - show this list via --show-associated-accounts). If the configured account - number is available, show a brief "setup ready" message. - - nexus-ebics-fetch ----------------- @@ -214,6 +196,23 @@ nexus-ebics-fetch over (before committing any transactions with the next day!) also fetches a final statement of the previous day, thus ensuring we get a statement every day plus intra-day reports. + + .. note:: + + (1) "from that day forward (inclusive)" must **not** rely on EBICS returning + the unseen messages: that's because they might **already** be downloaded but + never made it to the database. + + (2) "and when the day rolls over". When does a day roll over? => A day rolls + over when the current time is at least on the day after the transaction with the + most recent timestamp that's stored in the database. + + (3) "Afterwards, fetches reports". This must happen **only after** any possible + previous statement got downloaded. + + To summarize: at any point in time the database must contain (the content of) any + possible statement up to the current time, plus any possible report up to the current + time (in case that's not covered by any statement so far). * Bounces transactions with mal-formed wire transfer subjects. @@ -315,3 +314,41 @@ Discussion / Q&A the bank response, may lead double-submission even if the HTTP talk ended well: it suffices to crash after having received a "200 OK" response but before setting the submitted flag to the database. + +* the ebics-submit section mentions the EBICS order ID. The following excerpt + was found however at page 88 of the EBICS 3 specifications: + + ``OrderID is only present if a file is transmitted to the bank relating to an order with an + already existing order number (only allowed for AdminOrderType = HVE or HVS)`` + + Nexus does not support HVE or HVS. + +* As of private communication, the responsibility of submitting idempotent payments + relies on the use of ``request_uid`` (a database column of the initiated payment) + as the ``MsgId`` value of the corresponding pain.001 document. + +* ``submitted`` column of an initiated payment evolved into the following enum: + + .. code-block:: shell-session + + CREATE TYPE submission_state AS ENUM ( + 'unsubmitted' + ,'transient_failure' + ,'permanent_failure' + ,'success' + ,'never_heard_back' + ); + + * ``unsubmitted``: default state when a payment is initiated + * ``transient_failure``: submission failed but can be retried, for example after a network issue. + * ``permanent_failure``: EBICS- or bank-technical error codes were not EBICS_OK (nor any tolerated EBICS code like EBICS_NO_DOWNLOAD_DATA_AVAILABLE), never retry. + * ``never_heard_back``: the payment initiation submission has **been** ``success`` but it was never confirmed by any outgoing transaction (from a camt.5x document) or any pain.002 report. It is responsability of a garbage collector to set this state after a particular time period. + +* the initiated_outgoing_transactions table takes two more columns: + ``last_submission_date``, a timestamp in microseconds, and a + ``submission_counter``. Both of them would serve to decide retry + policies. + +* the ``failure_text`` column at the initiated_outgoing_transactions table + should contain a JSON object that contains any useful detail about the problem. + That *could* be modeled after the Taler `ErrorDetail <https://docs.taler.net/core/api-common.html#tsref-type-ErrorDetail>`_, where at least the error code and the hint fields are provided. |