summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-05-18 19:29:11 +0200
committerChristian Grothoff <christian@grothoff.org>2020-05-18 19:29:11 +0200
commitc6014d72d0db9f199a6462c9841ffa4785985d45 (patch)
treee2ee15e7e372c6bb9dcd7ee306065911563686f0
parent66b09780c1911e90c5b702f0374ef71dfbaa9f8a (diff)
parent16466dd547243332ad1284827f34369442e1bc3c (diff)
downloaddocs-c6014d72d0db9f199a6462c9841ffa4785985d45.tar.gz
docs-c6014d72d0db9f199a6462c9841ffa4785985d45.tar.bz2
docs-c6014d72d0db9f199a6462c9841ffa4785985d45.zip
Merge branch 'master' of git+ssh://git.taler.net/docs
-rw-r--r--anastasis-db.pngbin51727 -> 52516 bytes
-rw-r--r--conf.py8
-rw-r--r--libeufin/api-nexus.rst79
-rw-r--r--libeufin/api-sandbox.rst196
-rw-r--r--libeufin/bank-transport-ebics.rst55
-rw-r--r--libeufin/index.rst5
-rw-r--r--taler-wallet.rst131
7 files changed, 264 insertions, 210 deletions
diff --git a/anastasis-db.png b/anastasis-db.png
index 3681fa4e..4a2fc5c1 100644
--- a/anastasis-db.png
+++ b/anastasis-db.png
Binary files differ
diff --git a/conf.py b/conf.py
index a1a653af..9fd6009b 100644
--- a/conf.py
+++ b/conf.py
@@ -229,6 +229,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
+ ('taler-auditor-manual', 'taler-auditor-manual.tex',
+ 'GNU Taler Auditor Manual', 'GNU Taler team', 'manual'),
('taler-exchange-manual', 'taler-exchange-manual.tex',
'GNU Taler Exchange Manual', 'GNU Taler team', 'manual'),
('taler-merchant-manual', 'taler-merchant-manual.tex',
@@ -239,7 +241,7 @@ latex_documents = [
'GNU Taler team', 'manual'),
('taler-backoffice-manual', 'taler-backoffice-manual.tex',
'GNU Taler Back Office Manual', 'GNU Taler team', 'manual'),
- ('onboarding', 'onboarding.tex', 'GNU Taler Developer Onboarding Manual',
+ ('developers-manual', 'developers-manual.tex', 'GNU Taler Developer Onboarding Manual',
'GNU Taler team', 'manual'),
]
@@ -327,6 +329,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
+ ("taler-auditor-manual", "taler-auditor", "Taler Auditor Manual",
+ "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"),
("taler-exchange-manual", "taler-exchange", "Taler Exchange Manual",
"GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"),
("taler-merchant-manual", "taler-merchant", "Taler Merchant Manual",
@@ -336,7 +340,7 @@ texinfo_documents = [
"DESCRIPTION", "CATEGORY"),
("taler-bank-manual", "taler-bank", "Taler Bank Manual", "GNU Taler team",
"MENU ENTRY", "DESCRIPTION", "CATEGORY"),
- ("onboarding", "onboarding", "Taler Onboarding Manual", "GNU Taler team",
+ ("developers-manual", "developers-manual", "Taler Developer Onboarding Manual", "GNU Taler team",
"MENU ENTRY", "DESCRIPTION", "CATEGORY"),
]
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index bc3dacce..681811aa 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -48,7 +48,7 @@ Users Management
**Details:**
- .. ts:def:: CreateUserRequest
+ .. ts:def:: User
interface User {
@@ -82,7 +82,7 @@ Bank Account Management
holder: string;
}
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments/submit
+.. http:post:: <nexus>/bank-accounts/prepared-payments/submit
Ask nexus to submit one prepare payment at the bank.
@@ -96,7 +96,22 @@ Bank Account Management
uuid: string;
// Specify the bank transport to use for the submission.
- transport?: string;
+ transport?: Transport;
+ }
+
+
+ .. ts:def:: Transport
+
+ interface Transport {
+
+ // Transport type: 'ebics', 'local', 'fints' (forthcoming).
+ // It must match one of the types actually implemented by
+ // nexus.
+ type: string;
+
+ // A mnemonic identifier given by the user to one particular
+ // transport instance.
+ name: string;
}
:status 404 Not Found: the unique identifier **or**
@@ -176,10 +191,9 @@ Bank Account Management
uuid: string;
}
-.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions
+.. http:post:: <nexus>/bank-accounts/collected-transactions
- Ask the default transport to download the latest transactions
- related to ``my-acct`` and store them locally.
+ Nexus will download bank transactions from the given transport.
**Request:**
@@ -188,7 +202,7 @@ Bank Account Management
interface CollectedTransaction {
// Optional field to specify the bank transport to
// use for such operation.
- bankTransport?: string;
+ bankTransport?: Transport;
// dashed date (YYYY-MM-DD) of the earliest payment
// in the result. Optional, defaults to "earliest
// possible" date.
@@ -251,27 +265,37 @@ to the real bank.
Activate a new bank transport for the requesting user.
**Request:**
- Object of the type `BankTransport`
-
- **Response:**
-
- :status 409 Conflict: The ``name`` field exists already for
- the requesting user.
-
- **Details:**
.. ts:def:: BankTransport
interface BankTransport {
- // Mnemonic identifier for the transport bein created.
- name: string;
+ transport: Transport;
- // Restore a previous transport.
+ // Restore a previous transport. Take precedence
+ // over the 'new' field.
backup?: TransportBackup;
+
+ // Data to create a fresh bank transport without
+ // restoring any backup.
+ data?: TransportNew;
+ }
+
+
+ .. ts:def:: TransportNew
+
+ interface TransportNew {
+
+ // This type is strictly dependent on
+ // the transport being created. For Ebics,
+ // it will contain the required fields (as strings):
+ // 'ebicsURL', 'userID', 'partnerID', 'hostID', and
+ // the optional 'systemID'.
+
+ // Other transport types, like 'local' (used for testing
+ // purposes skipping any interaction with the bank service)
+ // and 'fints' are all work in progress!
- // Type of the transport (ebics, fints, native, ..)
- type: string;
}
@@ -279,16 +303,25 @@ to the real bank.
interface TransportBackup {
- // The information needed in this type depend entirely
- // on which transport is being restored.
+ // The information needed in this type depend entirely
+ // on which transport is being restored.
}
-.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
+ **Response:**
+
+ :status 409 Conflict: The ``name`` field exists already for
+ the requesting user.
+
+.. http:post:: <nexus>/bank-transports/sendMSG.
Perform the ``MSG`` operation offered by ``transport-name``
**without** affecting the nexus database.
+ **Request:**
+
+ A `Transport` object.
+
**Response:**
:status 404 Not Found: ``transport-name`` doesn't exist for
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index ee298d85..015b8d59 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -1,189 +1,49 @@
+
Sandbox API
###########
-Entities
-========
-
-Bank Account
- ...
-
-EBICS Host
-
-EBICS Subscriber
- ...
-
-EBICS Partner
- ...
-
-
-
HTTP API
========
+..
+ Payments.
-.. http:post:: /ebicsweb
+.. http:post:: /admin/payments
+
+ Adds a new payment to the book.
- Submit an EBICS request to the sandbox.
+..
+ Host management.
+.. http:post:: /admin/ebics/hosts
+
+ Creates a new Ebics host.
-.. http:post:: /admin/customers
+.. http:get:: /admin/ebics/hosts
+
+ Shows the list of all the hosts existing
+ in the system.
- Create a new customer. A customer identifies a human that
- may own multiple bank accounts.
+..
+ Subscriber management.
- When creating a customer, one EBICS subscriber is automatically
- created for the customer.
+.. http:post:: /admin/ebics/subscribers
- In the future, we might add an API to create multiple additional subscribers for
- a customer.
+ Creates a new subscriber.
- When creating a new customer, an ID will be assigned automatically.
+.. http:get:: /admin/ebics/subscribers
- .. code-block:: tsref
+ Shows the list of all the subscribers existing
+ in the system.
- interface CustomerCreationRequest {
- // human-readable name for the customer
- name: string;
- }
+.. http:post:: /admin/ebics/bank-accounts
-.. http:get:: /admin/customers/:id
+ Associates a new bank account to an existing subscriber.
- Get information about a customer.
+..
+ Main EBICS service.
- .. ts:def:: CustomerInfo
+.. http:post:: /ebicsweb
- interface CustomerInfo {
- ebicsInfo?: CustomerEbicsInfo;
- finTsInfo?: CustomerFinTsInfo;
- }
-
- .. ts:def:: CustomerEbicsInfo
-
- interface CustomerEbicsInfo {
- ebicsHostId: string;
- ebicsParterId: string;
- ebicsUserId: string;
-
- // Info for the customer's "main subscriber"
- subscriberInitializationState: "NEW" | "PARTIALLY_INITIALIZED_INI" | "PARTIALLY_INITIALIZED_HIA" | "READY" | "INITIALIZED";
- }
-
- .. ts:def:: CustomerFinTsInfo
-
- // TODO
-
-.. http:post:: /admin/customers/:id/ebics/keyletter
-
- Accept the information from the customer's ("virtual") INI-Letter and HIA-Letter
- and change the key's state as required.
-
- .. code-block:: tsref
-
- interface KeyLetterRequest {
-
- ini: {
- // The user ID that participates in a EBICS subscriber.
- userId: string;
-
- // The customer ID specific to the bank (therefore not
- // participating in a EBICS subscriber).
- customerId: string;
-
- // Human name of the user
- name: string;
-
- // As per specification, this value is:
- // "Date of processing of the corresponding EBICS order". DD.MM.YYYY format.
- date: string;
-
- // As per specification, this value is:
- // "Time of processing of the corresponding EBICS order". HH:MM:SS format.
- time: string;
-
- // Identification token of the bank. Not required to obey to any particular standard.
- recipient: string;
-
- // Electronic signature version. Admitted values: A005, A006.
- version: string;
-
- // Length in bits of the key exponent.
- public_exponent_length: number;
- // RSA key exponent in hexadecimaml notation.
- public_exponent: string;
-
- // Length in bits of the key modulus.
- public_modulus_length: number;
- // RSA key modulus in hexadecimaml notation.
- public_modulus: string;
-
- // RSA key hash.
- //
- // A005, A005 versions require hash type SHA-256.
- hash: string;
- }
-
- hia: {
- // The user ID that participates in a EBICS subscriber.
- userId: string;
-
- // The customer ID specific to the bank (therefore not
- // participating in a EBICS subscriber).
- customerId: string;
-
- // Human name of the user
- name: string;
-
- // As per specification, this value is:
- // "Date of processing of the corresponding EBICS order". DD.MM.YYYY format.
- date: string;
-
- // As per specification, this value is:
- // "Time of processing of the corresponding EBICS order". HH:MM:SS format.
- time: string;
-
- // Identification token of the bank. Not required to obey to any particular standard.
- recipient: string;
-
- ////////////////////////////////////////////////////
- // Identification and Authentication key details. //
- ////////////////////////////////////////////////////
-
- // Identification and authentication signature version.
- // Admitted value: X002.
- ia_version: string;
-
- // length of the exponent, in bits.
- ia_public_exponent_length: number;
- // RSA key exponent in hexadecimaml notation.
- ia_public_exponent: string;
-
- // length of the modulus, in bits.
- ia_public_modulus_length: number;
- // RSA key modulus in hexadecimaml notation.
- ia_public_modulus: string;
-
- // SHA-256 hash of the identification and authentication key.
- ia_hash: string;
-
- /////////////////////////////
- // Encryption key details. //
- /////////////////////////////
-
- // Encryption version. Admitted value: E002.
- enc_version: string;
-
- // length of the exponent, in bits.
- enc_public_exponent_length: number;
- // RSA key exponent in hexadecimaml notation.
- enc_public_exponent: string;
-
- // length of the modulus, in bits.
- enc_public_modulus_length: number;
- // RSA key modulus in hexadecimaml notation.
- enc_public_modulus: string;
-
- // SHA-256 hash of the encryption key.
- enc_hash: string;
- }
- }
+ Serves all the Ebics requests.
diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst
new file mode 100644
index 00000000..0d06f83b
--- /dev/null
+++ b/libeufin/bank-transport-ebics.rst
@@ -0,0 +1,55 @@
+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)
+
+5. The nexus sends the public keys electronically to the bank's EBICS server, together with the information
+ identifying the subscriber (PartnerID, UserID, SystemID).
+
+6. The user print a document that contains the public key and hashes for all three key pairs.
+ The user then signs this document sends it to the bank (physically/scanned).
+
+7. 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".
+
+8. 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.
+
+9. 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.
+
+10. 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/index.rst b/libeufin/index.rst
index bc00b964..49d44ded 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -7,7 +7,8 @@ LibEuFin is a project providing free software tooling for European FinTech.
:glob:
concepts
- ebics
- api-sandbox
+ bank-transport-ebics
api-nexus
+ api-sandbox
+ ebics
iso20022
diff --git a/taler-wallet.rst b/taler-wallet.rst
index 11167ea9..ce369002 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -81,19 +81,65 @@ APIs and Data Formats
These APIs are still a work in progress and *not* final.
+Balances
+--------
+
+Balances are the amounts of digital cash held by the wallet.
+
+:name: ``"getBalances"``
+:description: Get a list of balances per currency.
+:response:
+ .. ts:def:: BalancesResponse
+
+ interface BalancesResponse {
+ // a list of balances sorted by currency.
+ // (currencies with shorter names first, then lexically ascending).
+ //
+ // Note: Even when a currency has no balance, but pending or past transactions,
+ // it should be included in this list with a balance of zero.
+ balances: Balance[];
+ }
+
+ .. ts:def:: Balance
+
+ interface Balance {
+ currency?: string;
+
+ // The total Amount that is currently available to be spent
+ // including amounts tied up in ongoing refresh operations. These are hidden from the user.
+ // If the user tries to spend coins locked up this way,
+ // the wallet will give an error message different from "insufficient balance".
+ available: Amount;
+
+ // the total incoming amount that will be added to the available balance
+ // when all pending transactions succeed (including internal refreshes)
+ pendingIncoming: Amount;
+
+ // the total outgoing amount that will be subtracted from the available balance
+ // when all pending transactions succeed (including internal refreshes)
+ pendingOutgoing: Amount;
+
+ // true if the balance has pending transactions
+ hasPendingTransactions: boolean;
+
+ // true if the balance requires user-interaction, e.g. accepting a tip
+ // (DEV: can be left out of a first implementation)
+ requiresUserInput: boolean;
+ }
+
Transactions
------------
Transactions are all operations or events that are affecting the balance.
-:name: ``"transactions"``
+:name: ``"getTransactions"``
:description: Get a list of past and pending transactions.
:request:
.. ts:def:: TransactionsRequest
interface TransactionsRequest {
- // return only transactions in the given currency
- currency: string;
+ // return only transactions in the given currency, if present
+ currency?: string;
// if present, results will be limited to transactions related to the given search string
search?: string;
@@ -105,7 +151,8 @@ Transactions are all operations or events that are affecting the balance.
// a list of past and pending transactions sorted by pending, timestamp and transactionId.
// In case two events are both pending and have the same timestamp,
// they are sorted by the transactionId
- // (lexically ascending and locale-independent comparison).
+ // (i.e. pending before non-pending transactions, newer before older
+ // and if all equal transactionId lexically ascending).
transactions: Transaction[];
}
@@ -127,6 +174,9 @@ Transactions are all operations or events that are affecting the balance.
// but its transactionId will remain unchanged
pending: boolean;
+ // if present, the transaction encountered a fatal error that needs to be shown to the user
+ error?: TransactionError;
+
// Raw amount of the transaction (exclusive of fees or other extra costs)
amountRaw: Amount;
@@ -144,6 +194,20 @@ Transactions are all operations or events that are affecting the balance.
TransactionRefresh
)
+ .. ts:def:: TransactionError
+
+ interface TransactionError {
+ // TALER_EC_* unique error code.
+ // The action(s) offered and message displayed on the transaction item depend on this code.
+ ec: number;
+
+ // English-only error hint, if available.
+ hint?: string;
+
+ // Error details specific to "ec", if applicable/available
+ details?: any;
+ }
+
.. ts:def:: TransactionWithdrawal
// This should only be used for actual withdrawals
@@ -166,6 +230,7 @@ Transactions are all operations or events that are affecting the balance.
amountRaw: Amount;
// Amount that actually was (or will be) added to the wallet's balance.
+ // Should always be shown as a positive amount.
amountEffective: Amount;
}
@@ -177,14 +242,14 @@ Transactions are all operations or events that are affecting the balance.
// Additional information about the payment.
info: TransactionInfo;
- // true if the payment failed, false otherwise.
- // Note that failed payments with zero effective amount will not be returned by the API.
- failed: boolean;
+ // The current status of this payment.
+ status: PaymentStatus;
// Amount that must be paid for the contract
amountRaw: Amount;
// Amount that was paid, including deposit, wire and refresh fees.
+ // Should always be shown as a negative amount.
amountEffective: Amount;
}
@@ -210,6 +275,26 @@ Transactions are all operations or events that are affecting the balance.
fulfillmentUrl: string;
}
+ .. ts:def:: PaymentStatus
+
+ enum PaymentStatus {
+ // Explicitly aborted after timeout / failure
+ Aborted = "aborted",
+
+ // Payment failed, wallet will auto-retry.
+ // User should be given the option to retry now / abort.
+ Failed = "failed",
+
+ // Paid successfully
+ Paid = "paid",
+
+ // Only offered, user must accept / decline
+ Offered = "offered",
+
+ // User accepted, payment is processing.
+ Accepted = "accepted",
+ }
+
.. ts:def:: TransactionRefund
interface TransactionRefund extends Transaction {
@@ -227,7 +312,8 @@ Transactions are all operations or events that are affecting the balance.
// Amount that has been refunded by the merchant
amountRaw: Amount;
- // Amount will be added to the wallet's balance after fees and refreshing
+ // Amount will be added to the wallet's balance after fees and refreshing.
+ // Should always be shown as a positive amount.
amountEffective: Amount;
}
@@ -236,11 +322,8 @@ Transactions are all operations or events that are affecting the balance.
interface TransactionTip extends Transaction {
type: string = "tip",
- // true if the user still needs to accept/decline this tip
- waiting: boolean;
-
- // true if the user has accepted this top, false otherwise
- accepted: boolean;
+ // The current status of this tip.
+ status: TipStatus;
// Exchange that the tip will be (or was) withdrawn from
exchangeBaseUrl: string;
@@ -251,10 +334,27 @@ Transactions are all operations or events that are affecting the balance.
// Raw amount of the tip, without extra fees that apply
amountRaw: Amount;
- // Amount will be (or was) added to the wallet's balance after fees and refreshing
+ // Amount will be (or was) added to the wallet's balance after fees and refreshing.
+ // Should always be shown as a positive amount.
amountEffective: Amount;
}
+ .. ts:def:: TipStatus
+
+ enum TipStatus {
+ // Only offered, user must accept / decline
+ Offered = "offered",
+
+ // User accepted, tip is processing.
+ Accepted = "accepted",
+
+ // User declined.
+ Declined = "declined",
+
+ // Received successfully
+ Received = "received",
+ }
+
.. ts:def:: TransactionRefresh
// A transaction shown for refreshes that are not associated to other transactions
@@ -269,7 +369,8 @@ Transactions are all operations or events that are affecting the balance.
// Raw amount that is refreshed
amountRaw: Amount;
- // Amount that will be paid as fees for the refresh
+ // Amount that will be paid as fees for the refresh.
+ // Should always be shown as a negative amount.
amountEffective: Amount;
}