15.3. Nexus API

15.3.1. HTTP API

Configuration

Returns configuration values currently used by the Nexus process. This API is mostly used by testing jobs.

GET {nexusBase}/service-config

Response:

interface ConfigResponse {

  // Connection string to the database.
  dbConn: string;
}

Returns configuration values currently used by Nexus.

GET {nexusBase}/config

Response:

interface ConfigResponse {

  currency: string;

  // 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

GET {nexusBase}/user

Get information about the current user (based on the authentication information in this request).

Response:

interface UserResponse {

  // User name
  username: string;

  // Password
  password: string;
}
POST {nexusBase}/users/password

Change password of a user. The username is extracted from the HTTP authentication parameters.

Request:

interface UserChangePassword {
  newPassword: string;
}
POST {nexusBase}/users

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

Request:

The body is a User object.

Response:

409 Conflict: Username is not available.

Details:

interface User {

  // User name
  username: string;

  // Initial password
  password: string;
}
GET {nexusBase}/users

Return list of users.

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.
GET {nexusbase}/permissions

List all permissions.

Response

interface QueryPermissionsResponse {
  permissions: {
    subjectType: string;
    subjectId: string;
    resourceType: string;
    resourceId: string;
    permissionName: string
  }[];
}
POST {nexusbase}/permissions

Modify permissions.

Request

  interface QueryPermissionsResponse {
    action: "grant" | "revoke";
    permission: {
      subjectType: string;
      subjectId: string;
      resourceType: string;
      resourceId: string;
      permissionName: string
    };
  }

**Response**

The response is an empty JSON object.

Test API

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

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

GET {nexusBase}/bank-accounts

Response:

A list of BankAccount objects that belong to the requester.

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

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

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;

}

POST {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit

Ask nexus to submit one prepare payment at the bank.

404 Not found: the unique identifier or the bank connection could not be found in the system

GET {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}

Ask the status of payment $uuid.

Response:

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;
}
GET {nexusBase}/bank-accounts/{my-acct}/payment-initiations

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

Response

interface InitiatedPayments {

  // list of all the initiated payments' UID.
  initiatedPayments: PaymentStatus[];
}
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:

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
}

Response:

interface PreparedPaymentResponse {

  // Opaque identifier to be communicated when
  // the user wants to submit the payment to the
  // bank.
  uuid: string;
}
POST {nexusBase}/bank-accounts/{acctid}/fetch-transactions

Nexus will download bank transactions using the given connection.

Request:

interface CollectedTransaction {

    // This type indicates the time range of the query.
    // It can assume the following values:
    //
    // 'latest': retrieves the last transactions from the bank.
    //           If there are older unread transactions, those will *not*
    //           be downloaded.
    //
    // 'all': retrieves all the transactions from the bank,
    //        until the oldest.
    //
    // 'previous-days': currently *not* implemented, it will allow
    //                  the request to download transactions from
    //                  today until N days before.
    //
    // 'since-last': retrieves all the transactions since the last
    //               time one was downloaded.
    //
    rangeType: string;

    // Because transactions are delivered by banks in "batches",
    // then every batch can have different qualities.  This value
    // lets the request specify which type of batch ought to be
    // returned.  Currently, the following two type are supported:
    //
    // 'report': intra-day information
    // 'statement': prior day bank statement
    level: string;

    // Bank connection to use.  It is a *optional* value that
    // defaults to the default bank connection, if not given.
    bankConnection: string;
}

Response:

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;
}
GET {nexusBase}/bank-accounts/{acctid}/transactions

Shows which transactions are stored locally at nexus.

Query parameters:

  • start start (dashed YYYY-MM-DD) date of desired payments. Optional, defaults to “earliest possible” date.
  • end end (dashed YYYY-MM-DD) date of desired payments. Optional, defaults to “earliest possible” date.

Response: A object with a unique field named transactions that contains a list of Transaction objects.

interface Transaction {

  // 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[];
  };
}
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

POST {nexusBase}/bank-accounts/{acctid}/schedule

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

Request

interface ScheduleTask {
  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
  params: {
    level: "report" | "statement" | "all";
    rangeType: "latest" | "all" | "previous-days" | "since-last";
  };
}
GET {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

Response

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

interface NexusTask {
  // FIXME: document all.
  resourceType: string;
  resourceId: string;
  taskName: string;
  taskType: string;
  taskCronSpec: string;
  taskParams: string;
  nextScheduledExecutionSec: number;
  prevScheduledExecutionSec: number;
}
DELETE {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

This call deletes the task associated to taskId.

GET {nexusBase}/bank-accounts/{acctid}/schedule

Response

interface TaskCollection {

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

    'task-name': {
      cronspec: string;
      type: string; // fetch | submit

      // Depends on the type.  Submit has it empty, whereas
      // the fetch type includes the time range and the report
      // level.
      params: any;
    }
  }
}

Bank Connections

Bank connections connect the local LibEuFin bank account to the real bank.

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.

interface NewBankConnection {

  source: string; // only "new" allowed

  // connection name.
  name: string;

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

  data: BankConnectionNew;
}

This type allows to restore a previously made bank connection.

interface BankConnectionRestoreRequest {

  source: "backup";

  // connection name.
  name: string;

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

  passphrase?: string;
}
interface BankConnectionNew {

  // This type is strictly dependent on
  // the connection being created.  For Ebics,
  // it will contain the required fields (as strings):
  // 'ebicsURL', 'userID', 'partnerID', 'hostID', and
  // the optional 'systemID'.

  // Other connection types, like 'local' (used for testing
  // purposes skipping any interaction with the bank service)
  // and 'fints' are all work in progress!

}
interface BankConnectionBackup {

  // The information needed in this type depend entirely
  // on which connection is being restored.
}

Response:

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

POST {nexusBase}/bank-connections/delete-connection

Request:

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

List available bank connections.

Response

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

interface BankConnection {

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

  // connection name as given by the user at
  // the moment of creation.
  name: string;
}
GET {nexusBase}/bank-connections/{connId}

Get information about one bank connection.

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;
}
POST {nexusBase}/bank-connections/{connId}/connect

Initialize the connection by talking to the bank.

POST {nexusBase}/bank-connections/{connId}/export-backup

Make a passphrase-encrypted backup of this connection.

POST {nexusBase}/bank-connections/{connId}/fetch-accounts

Update accounts that are accessible via this bank connection.

GET {nexusBase}/bank-connections/{connId}/accounts
List the bank accounts that this bank connection provides access to.
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.
  nexusBankAccountId: string | null;
}
POST {nexusBase}/bank-connections/{connId}/import-account

Import a bank account provided by the connection into the Nexus.

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 Nexus bank account with the same ID already exists, this connection will be added as an available connection for it. This only succeeds if the bank account has the same IBAN.

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;
}
GET <nexus>/bank-connections/{connId}/messages

List some details of all the ISO2022 messages gotten from the bank. It responds with a list of the following elements:

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;
}
GET <nexus>/bank-connections/{connId}/messages/{msgId}

Return the ISO20022 XML corresponding to msgId.

Facades

GET <nexus>/facades/{fcid}

Response: A FacadeShowInfo pointed to by fcid.

GET <nexus>/facades

List available facades that belong to the requesting user.

Response: A list of the following elements:

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;
}
DELETE {nexus}/facades/{fcid}

Delete a facade.

POST {nexus}/facades

Create a new facade.

Request:

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.
   config: any;
}

Bank Connection Protocols

GET {nexus}/bank-connection-protocols

List supported bank connection protocols.

POST {nexus}/bank-connection-protocols/ebics/test-host

Check if the 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.

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.

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 the nexus database. It will just make a request to the bank and return the answer.

POST {nexusBase}/bank-connections/{connection-name}/ebics/upload/{msg}

Warning

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

Perform an EBICS upload transaction of type msg. This request will not affect any bank account or other state in the 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. It is named after the typical user - a Anastasis service - but can be used in any case where only the incoming transactions are of interest.

GET ${BASE_URL}/history/incoming

Return a list of transactions made to the customer.

The bank account of the customer is determined via the base URL and/or the user name in the Authorization header. In fact the transaction history might come from a “virtual” account, where multiple real bank accounts are merged into one history.

Transactions are identified by an opaque numeric identifier, referred to here as row ID. The semantics of the row ID (including its sorting order) are determined by the bank server and completely opaque to the client.

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

  • If delta is positive, return 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 Parameters
  • startOptional. Row identifier to explicitly set the starting point of the query.
  • delta – The delta value that determines the range of the query.
  • long_poll_msOptional. If this parameter is specified and the result of the query would be empty, the bank 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 the bank may return a response immediately or after waiting only a fraction of long_poll_ms.

Response

200 OK: JSON object of type IncomingHistory. 400 Bad request: Request malformed. The bank replies with an ErrorDetail object. 401 Unauthorized: Authentication failed, likely the credentials are wrong. 404 Not found: The endpoint is wrong or the user name is unknown. The bank replies with an ErrorDetail object.

interface IncomingHistory {

  // Array of incoming transactions.
  incoming_transactions : 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.
  // This must be one of the 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;

}

The anastasis facade

The anastasis facade has the following configuration:

interface AnastasisFacadeConfig {
  // Bank account and connection that is abstracted over.
  bankAccount: string;
  bankConnection: string;

  currency: string;

  // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
  // for incoming transfers.
  reserveTransferLevel: "statement" | "report" | "notification";
}

The taler-wire-gateway facade

The taler-wire-gateway facade has the following configuration:

interface TalerWireGatewayFacadeConfig {
  // Bank account and connection that is
  // abstracted over.
  bankAccount: string;
  bankConnection: string;

  currency: string;

  // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
  // for incoming transfers.
  reserveTransferLevel: "statement" | "report" | "notification";
}