transaction identification

1 files changed, 85 insertions, 0 deletions

diff --git a/libeufin/transaction-identification.rst b/libeufin/transaction-identification.rst
new file mode 100644
index 00000000..7c737fc2
--- /dev/null
+++ b/libeufin/transaction-identification.rst
@@ -0,0 +1,85 @@
+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 if 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.