diff options
Diffstat (limited to 'libeufin')
-rw-r--r-- | libeufin/api-nexus.rst | 92 | ||||
-rw-r--r-- | libeufin/api-sandbox.rst | 59 | ||||
-rw-r--r-- | libeufin/nexus-tutorial.rst | 166 |
3 files changed, 215 insertions, 102 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 01e8e926..f47101fd 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 d848ba40..d1214d52 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 82f1ba43..e919ed8c 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 |