path: root/libeufin/api-nexus.rst

.. target audience: core developer

Nexus HTTP API
##############

.. contents:: Table of Contents

In the current version, the API calls are only available to
the superuser, when no authorization condition is explictly stated.

Configuration
-------------


Returns configuration values currently used by Nexus.
This call is unauthenticated.

.. http:get:: {nexusBase}/config

  **Response:**

  .. ts:def:: ConfigResponse

     interface ConfigResponse {

       // nexus version, X.Y.Z format.
       version: string;
     }


Authentication
--------------

Currently every request made to nexus must be authenticated using the *HTTP
basic auth* mechanism.

Other authentication mechanisms (e.g. OpenID Connect) might
be supported in the future.

User Management
---------------

.. http:get:: {nexusBase}/user

  Get information about the current user.  The username carried
  along the HTTP basic auth points at the user to be shown.

  **Response:**

  .. ts:def:: UserResponse

     interface UserResponse {

       // User name
       username: string;

       // Is this a super user?
       superuser: boolean;
     }

.. http:post:: {nexusBase}/users/{userName}/password

  Change password of the ``{userName}`` user.  The call is
  available to any superuser on any username.

  **Request:**

  .. code-block:: ts

    interface UserChangePassword {
      newPassword: string;
    }

  **Response:**

  :http:statuscode:`200 OK`: The password was successfully changeD.


.. http:post:: {nexusBase}/users

  Create a new user.  Only a superuser can call this API.

  **Request:**

  The body is a `User` object.

  **Response:**

  :http:statuscode:`409 Conflict`: Username is not available.

  **Details:**

  .. ts:def:: User

     interface User {

       // User name
       username: string;

       // Initial password
       password: string;
     }


.. http:get:: {nexusBase}/users

  Return the list of all users.

  **Response:**

  .. ts:def:: UsersResponse

     interface UsersResponse {
       users: UserResponse[];
     }

.. _nexus-permissions-api:

Permissions API
---------------

The permissions API manages authorization of access of subjects
(usually users) to resources.

Permissions are modeled a set of ``(subject, resource, permission)``
triples.  Subjects and resources consist of a type and an identifier.

Superusers are not subject to further permission checks, they are
allowed to do any operation.

The following subject types are currently supported:

* ``user``:  An authenticated user.  The subject ID
  is interpreted as the user ID.

The following permissions are currently defined:

* ``facade.talerWireGateway.history``:  Allows querying the
  transaction history through a Taler wire gateway facade.
* ``facade.talerWireGateway.transfer``: Allows creating payment
  initiations to transfer money via a Taler wire gateway facade.

The following resource IDs are currently supported:

* ``facade``: A LibEuFin facade.  The resource ID is interpreted
  as the facade name.

* ``bank-account``: A Nexus bank account, currently used in
  `scheduled tasks <nexus-task_>`_ of type ``fetch`` and ``submit``.

.. http:get:: {nexusbase}/permissions

   Lists all permissions.

   **Response**

  .. ts:def:: QueryPermissionsResponse

     interface QueryPermissionsResponse {
       permissions: LibeufinPermission[];
     }

.. http:post:: {nexusbase}/permissions

   Modifies permissions.

   **Request**

  .. ts:def:: QueryPermissionsResponse

     interface QueryPermissionsResponse {
       action: "grant" | "revoke";
       permission: LibeufinPermission;
     }

   **Response**

   The response is an empty JSON object.


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 an empty JSON body.

Bank Accounts
-------------

Neuxs maintains a copy of the bank account transaction history and
balance information, manages payment initiations of the account and
tracks the initiations of payments.

.. http:get:: {nexusBase}/bank-accounts

  **Response:**

  A list of `BankAccount` objects that belong to the requester.
  The list is held in the ``accounts`` field.

  .. ts:def:: BankAccount

     interface BankAccount {
       // mnemonic name identifying this bank account.
       nexusBankAccountId: string;
       // IBAN
       iban: string;
       // BIC
       bic: string;
       // Legal subject owning the account.
       ownerName: string;
     }


.. http:get:: {nexusBase}/bank-accounts/{my-acct}

   Get basic information about the bank account named ``my-acct``.

   .. ts:def:: BankAccountInfoWithBalance

     interface BankAccountInfoWithBalance {
       // ID number of the database row being the default bank connection
       // of ``my-acct``.
       defaultBankConnection: number;
       // Payto://-URI of ``my-acct``.
       accountPaytoUri: string;
       // Balance of ``my-acct`` as it was downloaded from the bank
       // along the last Camt document.  A human-readable message
       // will inform the requester, should this value not be found.
       lastSeenBalance: string;
     }

.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit

  Asks nexus to submit one prepare payment at the bank.

  :http:statuscode:`404 Not found`: the unique identifier **or**
  the bank connection could not be found in the system


.. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}

   Asks the status of payment ``$uuid``.

   **Response:**

   .. ts:def:: PaymentStatus

      interface PaymentStatus {
        // Can be "BOOK" or "PDNG" ('pending').
        status: string;

        // Payment unique identifier
        paymentInitiationId: string;

        // True for submitted payments
        submitted: boolean;

        // Creditor IBAN
        creditorIban: string;

        // Creditor BIC
        creditorBic: string;

        // Creditor legal name
        creditorName: string;

        // Amount
        amount: string;

        // Subject
        subject: string;

        // Date of submission (in dashed form YYYY-MM-DD)
        submissionDate: string;

        // Date of preparation (in dashed form YYYY-MM-DD)
        preparationDate: string;
      }

.. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations

  Asks nexus the list of initiated payments.  At this stage of the API,
  **all** is returned: submitted and non-submitted payments.

  **Response**

  .. ts:def:: InitiatedPayments

     interface InitiatedPayments {

       // list of all the initiated payments' UID.
       initiatedPayments: PaymentStatus[];
     }


.. http:post:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations

  Ask nexus to prepare instructions for a new payment.
  Note that ``my-acct`` is the bank account that will be
  **debited** after this operation.

  **Request:**

  .. ts:def:: PreparedPaymentRequest

     interface PreparedPaymentRequest {
       // IBAN that will receive the payment.
       iban: string;
       // BIC hosting the IBAN.
       bic: string;
       // Legal subject that will receive the payment.
       name: string;
       // payment subject.
       subject: string;
       // amount, in the format CURRENCY:XX.YY
       amount: string,

       // This option lets the client associate a unique
       // identifier to the payment being created.  This
       // identifier will NOT be the identifier of the resource
       // created by this request, therefore it won't be possible
       // to _retrieve_ the resource by using this UID.
       // This UID helps, for example, if the client wrongly submits
       // the same request twice, because Nexus can make it idempotent
       // and avoid financial loss.
       uid?: string
     }

  **Response:**

  .. ts:def:: PreparedPaymentResponse

     interface PreparedPaymentResponse {

       // Opaque identifier to be communicated when
       // the user wants to submit the payment to the
       // bank.
       uuid: string;
     }

.. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions

  Nexus will download bank transactions using the given connection.

  **Request:**

  Refer to :ref:`FetchParams <fetch-params>` for
  ``level`` and ``rangeType`` specifications.

  .. ts:def:: CollectedTransaction

     interface CollectedTransaction {
         level: string;
         rangeType: string;
         // Bank connection to use.  Uses the default bank connection,
         // when not given.
         bankConnection?: string;
     }

  **Response:**

  .. code-block:: ts

    interface NewTransactions {
      // How many transactions are new to Nexus.
      newTransactions: number;
      // How many transactions got downloaded by the request.
      // Note that a transaction can be downloaded multiple
      // times but only counts as new once.
      downloadedTransactions: number;
    }

  :http:statuscode:`500 Internal Server Error`: Nexus itself had a problem
  along the operation, and not the bank.


.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions

  Shows the transactions fetched for ``{acctid}``, according to
  the URI parameters.

  **Request:**

  :query long_poll_ms: Optional number to express how many milliseconds
    the server should wait for at least one result to be shown.  If not
    given, the server responds immediately, regardless of the result.
  :query start: Optional number to express the **earliest** transaction
    index, starting from **1**.  For example, if *start* is 6 and three
    transactions are returned, they will have the following indexes:
    6, x, y, where x and y are both greater than 6 but not necessarily
    sequential.  This parameter defaults to 1.
  :query size:  Optional number indicating how many transactions are to
    be included in the response.  It defaults to 5.

  **Response:**

  :http:statuscode:`200 OK`:
  a JSON object with a unique field named ``transactions`` that
  is a list of `Transaction` objects.  This status code applies
  even for an **empty** list.  The list is such that index **x-1**
  is always a **earlier** transaction than **x**.  For example, the
  transaction having the 'start' index lies always at index zero.
  Note that the order does NOT reflect the transaction's timestamp
  as given by the bank, but rather the order that Nexus stored them
  into its database.

  .. ts:def:: Transaction

     interface Transaction {

       // Number as a string, which is the index identifying this
       // transaction at Nexus.
       // Note: users can ONLY expect that this index grows
       // as new transactions get fetched from the bank, but
       // should NOT expect it to grow continuously.
       index: string;

       // Nexus representation of a transaction.  The format is shaped
       // around the CaMt terminology and its XML structure.
       camtData: {
         // money moved by the transaction
         amount: string;
  
         // CRDT or DBIT
         creditDebitIndicator: string
  
         // Two of the most used values are BOOK, or PENDING
         status: string;
  
         // FIXME
         bankTransactionCode: string;
  
         // FIXME
         valueDate: string;
  
         // When this payment got booked.  In the form YYYY-MM-DD
         bookingDate: 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;
       }
     }

Scheduling API
--------------

.. http:post:: {nexusBase}/bank-accounts/{acctid}/schedule

  This endpoint allows the caller to define a recurrent
  execution of a task.

  **Request**

  .. ts:def:: ScheduleTask

    interface ScheduleTask {
      // Name to assign to the task being created.
      name: string;

      // a Unix-compatible cron pattern representing
      // the frequency of execution of this task.
      cronspec: string;

      // Can take values "fetch" (to download the history
      // of the requester's bank account) or "submit" (to submit
      // any initiated payment associated to the requester's
      // bank account).
      type: string;

      // Currently only used for "fetch" operations but required
      // for any type of task.  Whatever value "submit" tasks pass
      // here, it is not going to be consumed by Nexus.  Typically,
      // submit tasks pass FetchParams with all of its fields set
      // as null.
      params: FetchParams;
    }


.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

  Shows ``taskId`` state.

  .. _nexus-task:

  **Response**

  .. ts:def:: NexusTask

     // This object is a mere reflection of
     // what the Nexus database keeps to implement
     // the scheduling feature.

     interface NexusTask {
       // The resource being impacted by this operation.
       // Typically a (Nexus) bank account being ``fetch``ed
       // or whose payments are ``submit``ted.  In this cases,
       // this value is the "bank-account" constant.
       resourceType: string;
       // Name of the resource.  In case of "bank-account", that
       // is the name under which the bank account was imported
       // from the bank.
       resourceId: string;
       // Task name, equals 'taskId'
       taskName: string;
       // Values allowed are "fetch" or "submit".
       taskType: string;
       // FIXME: describe.
       taskCronSpec: string;
       // Only meaningful for "fetch" types.
       taskParams: FetchParams;
       // Timestamp in secons when the next iteration will run.
       nextScheduledExecutionSec: number;
       // Timestamp in seconds when the previous iteration ran.
       prevScheduledExecutionSec: number;
     }


.. http:delete:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

  This call deletes the task associated to ``taskId``.

.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule

   Shows all the scheduled tasks from ``acctid``.

  **Response**

  .. ts:def:: TaskCollection

    interface TaskCollection {

      // This field can contain *multiple* objects of the type sampled below.
      schedule: {

        'task-name': {
          cronspec: string;
          type: "fetch" | "submit";
          params: FetchParams;
        }
      }
    }


Bank Connections
----------------

Bank connections connect the local Nexus bank account to the bank.

.. http:post:: <nexus>/bank-connections

  Activate a new bank connection for the requesting user.

  **Request:**

  This request can accept two formats, depending on whether a
  new bank connection is being made, or a connection backup is
  being restored.


  This type allows the creation of new bank accounts.

  .. _new-conn:

  .. ts:def:: NewBankConnection

     interface NewBankConnection {

       source: string; // only "new" allowed

       // connection name.
       name: string;

       // type of the connection to make: "ebics" for example.
       type: string;

       // Strictly dependent from the connection type.
       data: any;
     }

  This type allows to restore a previously made bank connection.

  .. _restore-conn:

  .. ts:def:: BankConnectionRestore

     interface BankConnectionRestore {

       source: "backup";

       // connection name.
       name: string;

       // Backup data, as typically returned by the
       // "../export-backup" API.
       backup: any;

       passphrase?: string;
     }

  The following examples show the EBICS types for creating and
  restoring a connection.

  This type is found in the ``data`` field of `NewBankConnection <new-conn_>`_.

  .. _ebics-new-conn:

  .. ts:def:: EbicsNewConnection

    interface EbicsNewConnection {
      userID: string,
      partnerID: string,
      hostID: string,
      ebicsURL: string,
      systemID?: string
    }

  This type is found in the ``backup`` field of `BankConnectionRestore <restore-conn_>`_.

  .. ts:def:: EbicsBackup

    interface EbicsBackup {
      type: string, // constant to "ebics"
      userID: string,
      partnerID: string,
      hostID: string,
      ebicsURL: string,

      // The following three values are the EBICS private keys.
      authBlob: string,
      encBlob: string,
      sigBlob: string
    }

  **Response:**

  :http:statuscode:`406 Not acceptable`: a connection with the
  requested name already exists for this user.

.. http:post:: {nexusBase}/bank-connections/delete-connection

  **Request:**

  .. ts:def:: BankConnectionDeletion

      interface BankConnectionDeletion {
        // label of the bank connection to delete
        bankConnectionId: string;
      }

.. http:get:: {nexusBase}/bank-connections

   List available bank connections.

   **Response**

   A JSON object whose ``bankConnections`` element is a list of the following type:

   .. ts:def:: BankConnection

       interface BankConnection {

         // connection type.  For example "ebics".
         type: string;

         // connection name as given by the user at
         // the moment of creation.
         name: string;
       }


.. http:get:: {nexusBase}/bank-connections/{connId}

   Get information about one bank connection.

   .. ts:def:: BankConnectionInfo

      interface BankConnectionInfo {
        type: string;
        owner: string;
        // if true, this connection can be used to communicate
        // with the bank.
        ready: boolean;
        // Depends on the type.
        details: any;
      }

   For example, the following type occupies the ``details``
   field for EBICS connections.

   .. ts:def:: EbicsConnectionInfo

     interface EbicsConnectionInfo {
       ebicsUrl: string;
       ebicsHostId: string;
       partnerId: string;
       userId: string;
     }

.. http:post:: {nexusBase}/bank-connections/{connId}/connect

   Initialize the connection by talking to the bank.  For EBICS
   connections, this endpoint causes Nexus to submit its own keys
   and download the bank's.  That however **still** requires the
   user to send the public keys to the bank via post, in order
   to start operating.

.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup

   Make a passphrase-encrypted backup of this connection.

.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts

   Update accounts that are accessible via this bank connection.
   After this operation, Nexus has stored the names of each bank
   account, under ``connId``, that the bank communicated.

   Note: after this operation, Nexus **still** needs to
   `assign each bank account a local name <import-account_>`_ ,
   in order to start operating.

.. _import-account:

.. http:post:: {nexusBase}/bank-connections/{connId}/import-account

  Import a bank account provided by the connection into the Nexus.
  This operation assigns a local name to one bank account that was
  downloaded from the bank.

  If no Nexus bank account with the ID ``nexusBankAccountId`` exists,
  a new one will be created, and it will have ``connId`` as the
  default bank connection.

  If an existing local bank account whose ID equals ``nexusBankAccountId``
  already exists, this call fails if ``offeredAccountId`` and ``nexusBankAccountId``
  have different IBANs.  If instead the IBAN is the same, this call merely
  associates ``offeredAccountId`` to ``nexusBankAccountId`` internally
  in the database without changing ``nexusBankAccountId`` default connection.

  .. ts:def:: ImportBankAccount

     interface ImportBankAccount {

       // Identifier for the bank account, as returned by /accounts
       // of the bank connection.
       offeredAccountId: string;

       // Nexus-local identifier for the bank account.
       nexusBankAccountId: string;
     }

  **Response:**

  :http:statuscode:`409 Conflict`: ``nexusBankAccountId`` exists already but
  its IBAN is different from the one carried by ``offeredAccountId``.

.. http:get:: {nexusBase}/bank-connections/{connId}/accounts

  List the bank accounts that this bank connection provides access to.

  **Response:**

  The response is a JSON object whose ``accounts`` field is a list of the
  following type.

  .. ts:def:: OfferedBankAccount

     interface OfferedBankAccount {

       // Unique identifier for the offered account
       offeredAccountId: string;

       // IBAN of the offered account
       iban: string;

       // BIC of the account's financial institution
       bic: string;

       // Account owner name
       ownerName: string;

       // If the account has been imported,
       // this field contains the ID of the
       // Nexus bank account associated with it,
       // null otherwise.
       nexusBankAccountId: string | null;
     }


.. http:get:: <nexus>/bank-connections/{connId}/messages

  List *some* details of all the ISO2022 messages gotten from
  the bank.

  **Response:**

  The response is a JSON object whose ``bankMessages`` field
  is a list of the following type.

  .. code-block:: ts

    interface BankMessageInfo {

      // the message type, typically how the containing layer
      // (Ebics, for example) would label this information.  For
      // Camt.053 types, this value is "C53".
      code: string;

      // the unique identifier of the message.
      messageId: string;

      // bytes length of the message.
      length: number;
    }

.. http:get:: <nexus>/bank-connections/{connId}/messages/{msgId}

  Return the ISO20022 XML corresponding to ``msgId``.


Facades
-------

.. http:get:: <nexus>/facades/{fcid}

   **Response:** A `FacadeShowInfo` whose name is ``fcid``.

.. http:get:: <nexus>/facades

  List available facades that belong to the requesting user.

  **Response:**  A list of the following elements:

  .. ts:def:: FacadeShowInfo

    interface FacadeShowInfo {

      // Name of the facade, same as the "fcid" parameter.
      name: string;

      // Type of the facade.
      // For example, "taler-wire-gateway".
      type: string;

      // Bas URL of the facade.
      baseUrl: string;

      // details depending on the facade type.
      config: any;
    }

  For "taler-wire-gateway" and "anastasis" facades,
  ``config`` contains the following type:

  .. ts:def:: TalerAnastasisFacadeState

     interface TalerAnastasisFacadeState {
       // Bank connection this facade relies on.
       bankConnection: string;
       // (Nexus local) bank account associated to this facade.
       bankAccount: string;
       // Whether the facade seeks reports or statements from the bank.
       reserveTransferLevel: string;
       currency: string;
     }

.. http:delete:: {nexus}/facades/{fcid}

  Deletes a facade.

.. http:post:: {nexus}/facades

  Creates a new facade.

  **Request:**

  .. ts:def:: FacadeInfo

     interface FacadeInfo {
        // Name of the facade, same as the "fcid" parameter.
        name: string;

        // Type of the facade.
        // For example, "taler-wire-gateway" or "anastasis".
        type: string;

        // Bank accounts that the facade has read/write access to.
        bankAccountsRead?: string[];
        bankAccountsWrite?: string[];

        // Bank connections that the facade has read/write access to.
        bankConnectionsRead?: string[];
        bankConnectionsWrite?: string[];

        // Facade-specific configuration details.  Only the
        // following type is available.
        config: TalerAnastasisFacadeState;
     }

Bank Connection Protocols
-------------------------

.. http:get:: {nexus}/bank-connection-protocols

   Lists supported bank connection protocols.

.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host

   Check if Nexus can talk to an EBICS host.
   This doesn't create a new connection in the database,
   and is useful during setup when the user hasn't entered
   the full details for the connection yet.

   .. ts:def:: EbicsHostTestRequest

      interface EbicsHostTestRequest {
        ebicsBaseUrl: string;
        ebicsHostId: string;
      }


EBICS-specific APIs
-------------------

The following endpoints are only available for EBICS bank connections.
They are namespaced under the ``/ebics/`` sub-resource.

.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/download/{msg}

  .. warning::

    Use with care.  Typically only necessary for testing and debugging.

  Perform an EBICS download transaction of type ``msg``.
  This request will not affect any bank account or other state
  in Nexus database.  It will just make a request to the bank
  and return the answer.

Anastasis API.
--------------

This is a read-only API offering a view over *only* the incoming
transactions of a bank account.  The name comes from the use in
`Anastasis <https://www.anastasis.lu>`_.

.. http:get:: ${BASE_URL}/history/incoming

  Returns a list of transactions made to the customer.

  Transactions are identified by a numeric identifier,
  that reflects the order in which Nexus downloaded each
  transaction from the bank.

  The list of returned transactions is determined by a row
  ID *starting point* and a signed non-zero integer *delta*:

  * If *delta* is positive, returns a list of up to *delta*
    transactions (all matching the filter criteria) strictly
    **after** the starting point.  The transactions are sorted
    in **ascending** order of the row ID.
  * If *delta* is negative, return a list of up to *-delta*
    transactions (all matching the filter criteria) strictly
    **before** the starting point.  The transactions are sorted
    in **descending** order of the row ID.

  If *starting point* is not explicitly given, it defaults to:

  * A value that is **smaller** than all other row IDs if *delta*
    is **positive**.
  * A value that is **larger** than all other row IDs if *delta*
    is **negative**.

  **Request**

  :query start: *Optional.*
    Row identifier to explicitly set the *starting point* of the query.
  :query delta:
    The *delta* value that determines the range of the query.
  :query long_poll_ms: *Optional.*  If this parameter is specified and the
    result of the query would be empty, Nexus will wait up to ``long_poll_ms``
    milliseconds for new transactions that match the query to arrive and only
    then send the HTTP response.  A client must never rely on this behavior, as
    Nexus may return a response immediately or after waiting only a fraction
    of ``long_poll_ms``.

  **Response**

  :http:statuscode:`200 OK`: JSON object of type `IncomingHistory`.

  :http:statuscode:`400 Bad request`: Request malformed. Nexus replies
  with an `ErrorDetail` object.

  :http:statuscode:`401 Unauthorized`: Authentication failed, likely
  the credentials are wrong.

  :http:statuscode:`404 Not found`: The endpoint is wrong or the user
  name is unknown. Nexus replies with an `ErrorDetail` object.

  .. ts:def:: IncomingHistory

    interface IncomingHistory {

      // Array of incoming transactions.
      incoming_transactions : IncomingBankTransaction[];

    }

  .. ts:def:: IncomingBankTransaction

    interface IncomingBankTransaction {

      // Opaque identifier of the returned record.
      row_id: SafeUint64;

      // Date of the transaction.
      date: Timestamp;

      // Amount transferred.
      amount: Amount;

      // Payto URI to identify the receiver of funds.
      // Typically an exchange's bank accounts.
      credit_account: string;

      // Payto URI to identify the sender of funds.
      debit_account: string;

      // subject of the incoming payment.
      subject: string;
    }

Reaching the facade
-------------------

Once a facade with name ``fcid`` and type ``ftype`` has been
created, all its endpoints become offered by the following base
URL:

.. code-block:: console

   $NEXUS_URL/facades/$fcid/$ftype

For example, a ``taler-wire-gateway`` facade named ``foo`` will
offer its endpoints under

.. code-block:: console

   https://nexus.example.com/facades/foo/taler-wire-gateway/