summaryrefslogtreecommitdiff
path: root/libeufin
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-12-05 19:47:03 +0100
committerChristian Grothoff <christian@grothoff.org>2020-12-05 19:47:03 +0100
commit6da702cb839b682d80d87fdcd88eb9ff16c189ae (patch)
tree24ef34da4c1c8f6da4ac782961479ad9bf422f0a /libeufin
parentdf9eb5452325255dfa77030eb539d0b8c88a6c9e (diff)
parent085d99420a7aa23b04bd4ce1e256eec9e182c166 (diff)
downloaddocs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.tar.gz
docs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.tar.bz2
docs-6da702cb839b682d80d87fdcd88eb9ff16c189ae.zip
Merge branch 'master' of git+ssh://git.taler.net/docs
Diffstat (limited to 'libeufin')
-rw-r--r--libeufin/api-nexus.rst92
-rw-r--r--libeufin/api-sandbox.rst59
-rw-r--r--libeufin/nexus-tutorial.rst166
3 files changed, 215 insertions, 102 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 01e8e92..f47101f 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -103,6 +103,22 @@ User Management
Return list of users.
+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 a empty JSON body.
+
+
Bank Accounts
-------------
@@ -281,33 +297,75 @@ manages payment initiations of the account and tracks the initiations of payment
Optional, defaults to "earliest possible" date.
- **Response:** A list of `Transaction` objects.
+ **Response:** A object with a unique field named ``transactions``
+ that contains a list of `Transaction` objects.
.. ts:def:: Transaction
interface Transaction {
- // local bank account involved in the transaction.
- account: string;
- // counterpart IBAN
- counterpartIban: string;
+ // money moved by the transaction
+ amount: string;
- // counterpart BIC
- counterpartBic: string;
+ // CRDT or DBIT
+ creditDebitIndicator: string
- // counterpart holder name
- counterpartName: string;
+ // Two of the most used values are BOOK, or PENDING
+ status: string;
- // amount, in the format [-]CURRENCY:XX.YY,
- // where the minus sign as prefix indicates
- // a debit for the user's bank account.
- amount: string;
+ // FIXME
+ bankTransactionCode: string;
- // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction.
- date: string;
+ // FIXME
+ valueDate: string;
+
+ // When this payment got booked. In the form YYYY-MM-DD
+ bookingDate: string;
- // Payment subject.
- subject: 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;
+ }
}
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index d848ba4..d1214d5 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -9,28 +9,83 @@ HTTP API
..
Payments.
+
+.. http:post:: /admin/payments/camt
+
+ Return the history of one IBAN in Camt.053 format.
+
+ **Request**
+
+ .. code-block:: tsref
+
+ interface CamtParams {
+
+ // IBAN managed by the running Sandbox, for which
+ // the Camt.053 response is going to be generated.
+ iban: string;
+
+ // The Camt type to return. Only '53' is allowed
+ // at this moment.
+ type: number;
+ }
+
+ **Response**
+
+ The expected Camt.053 document.
+
+
+.. http:get:: /admin/payments
+
+ Return the list of *all* the payments known by the sandbox.
+
+ **Response**
+
+ .. code-block:: tsref
+
+ interface SandboxPayments {
+
+ // The list of all known payments, regardless
+ // of any IBAN involved in them.
+ payments: SandboxPayment[];
+ }
+
.. http:post:: /admin/payments
Adds a new payment to the book. Mainly used for testing
purposes.
**Request:**
+
+ One object of type `SandboxPayment`
- .. ts:def:: PaymentRequest
+ .. ts:def:: SandboxPayment
- interface PaymentRequest {
+ interface SandboxPayment {
// IBAN that will receive the payment.
creditorIban: string;
+ // FIXME
+ creditorBic: string;
+ // FIXME
+ creditorName: string;
// IBAN that will send the payment.
debitorIban: string;
+ // FIXME
+ debitorBic: string;
+ // FIXME
+ debitorName: string;
amount: string;
currency: string;
// subject of the payment.
subject: string;
+
+ // Whether the payment is credit or debit *for* the
+ // account being managed *by* the running sandbox.
+ // Can take the values: "CRDT" or "DBIT".
+ direction: string;
}
..
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index 82f1ba4..e919ed8 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -16,7 +16,7 @@ Obtain Nexus
============
Nexus belongs to the LibEuFin project, and can be downloaded via Git:
-.. code-block:: shell
+.. code-block:: console
$ git clone git://git.taler.net/libeufin
@@ -26,14 +26,14 @@ Install Nexus
=============
Navigate into the `libeufin` local repository, and from top-level run:
-.. code-block:: shell
+.. code-block:: console
$ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix
$ ./gradlew -Pprefix=$PREFIX cli:installToPrefix
In case of success, the two following commands should be found:
-.. code-block:: shell
+.. code-block:: console
$ which libeufin-nexus
$ which libeufin-cli
@@ -43,7 +43,7 @@ Connect Nexus with a EBICS account
Use the following command to *(1) run the nexus service*:
-.. code-block:: shell
+.. code-block:: console
$ libeufin-nexus
@@ -55,7 +55,7 @@ for PostgreSQL will be provided.
At this point a *(2) superuser account needs to be activated
into the system*:
-.. code-block:: shell
+.. code-block:: console
$ libeufin-nexus superuser foo # Will interactively ask for password
@@ -75,74 +75,74 @@ creating a EBICS connection*.
set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password
in step (2).
-.. code-block:: shell
+.. 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
+ $ 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 the step above executed correctly, Nexus 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 *(4) make
a backup copy* of such keys.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- connections \
- export-backup \
- --passphrase $SECRET \
- --outputfile $BACKUP_FILE \
- $CONNECTION_NAME
+ $ libeufin-cli \
+ connections \
+ export-backup \
+ --passphrase $SECRET \
+ --outputfile $BACKUP_FILE \
+ $CONNECTION_NAME
At this point, Nexus must communicate all the details to the bank. Therefore,
it will *(5) synchronize the connection*. In this EBICS example, Nexus will send
the *INI* and *HIA* messages to the bank.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- connections \
- sync \
- $CONNECTION_NAME
+ $ libeufin-cli \
+ connections \
+ sync \
+ $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 *(6) downloads the list of the bank accounts offered by the*
``$CONNECTION_NAME``.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- connections \
- download-bank-accounts \
- $CONNECTION_NAME
+ $ libeufin-cli \
+ connections \
+ download-bank-accounts \
+ $CONNECTION_NAME
It is now possible to *(7) list the accounts offered by the connection*.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- connections \
- list-offered-bank-accounts \
- $CONNECTION_NAME
+ $ libeufin-cli \
+ connections \
+ list-offered-bank-accounts \
+ $CONNECTION_NAME
Nexus now needs an explicit *(8) import of the accounts it needs to manage*.
This step is needed to let the user pick a custom name for such accounts.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli
- connections \
- import-bank-account \
- --offered-account-id $ACCOUNT_NATIVE_NAME \
- --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \
- $CONNECTION_NAME
+ $ libeufin-cli
+ connections \
+ import-bank-account \
+ --offered-account-id $ACCOUNT_NATIVE_NAME \
+ --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \
+ $CONNECTION_NAME
Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``)
under a certain connection (``$CONNECTION_NAME``), it is possible
@@ -161,22 +161,22 @@ from the bank, and then ask it again to return the results.
This command asks Nexus to *download the latest bank statements*:
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- accounts \
- fetch-transactions \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli \
+ accounts \
+ fetch-transactions \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
Once Nexus stored all the information in the database, the
client can ask to actually **see** the transactions:
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli
- accounts \
- transactions \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli
+ accounts \
+ transactions \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
Make a payment
==============
@@ -188,17 +188,17 @@ Payments pass through two phases: preparation and submission.
The following command prepares a payment:
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- accounts \
- prepare-payment \
- --credit-iban $IBAN_TO_SEND_MONEY_TO \
- --credit-bic $BIC_TO_SEND_MONEY_TO \
- --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \
- --payment-amount $AMOUNT \
- --payment-subject $SUBJECT \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli \
+ accounts \
+ prepare-payment \
+ --credit-iban $IBAN_TO_SEND_MONEY_TO \
+ --credit-bic $BIC_TO_SEND_MONEY_TO \
+ --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \
+ --payment-amount $AMOUNT \
+ --payment-subject $SUBJECT \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
Note: the ``$AMOUNT`` value needs the format ``X.Y:CURRENCY``; for example
``10:EUR``, or ``1.01:EUR``.
@@ -207,13 +207,13 @@ The previous command should return a value (``$UUID``) that uniquely
identifies the prepared payment in the Nexus system. It'll be needed
in the next step, to **send the payment instructions to the bank**:
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- accounts \
- submit-payment \
- --payment-uuid $UUID \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli \
+ accounts \
+ submit-payment \
+ --payment-uuid $UUID \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
Restore the backup
@@ -224,14 +224,14 @@ 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:: shell
+.. code-block:: console
- libeufin-cli \
- connection \
- restore-backup \
- --passphrase $SECRET \
- --outputfile $BACKUP_FILE \
- $CONNECTION_NAME
+ $ libeufin-cli \
+ connection \
+ restore-backup \
+ --passphrase $SECRET \
+ --outputfile $BACKUP_FILE \
+ $CONNECTION_NAME
Creating a Taler facade
=======================
@@ -245,14 +245,14 @@ At this moment, only the *Taler facade type* is implemented
in the Nexus, and the command below will show how to instantiate
one under an existing bank account.
-.. code-block:: shell
+.. code-block:: console
- libeufin-cli \
- taler-facade \
- new-facade \
- --facade-name $FACADE_NAME \
- $CONNECTION_NAME \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli \
+ taler-facade \
+ new-facade \
+ --facade-name $FACADE_NAME \
+ $CONNECTION_NAME \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
At this point, the additional *taler-wire-gateway* (link here) API
becomes offered by the Nexus. The purpose is to let a Taler exchange