14.3. Nexus API

14.3.1. HTTP API

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.

Users 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;

  // Is it a superuser?
  superuser: boolean;
}
POST {nexusBase}/users

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

Request:

The body is a User object.

Response:

Status Codes

Details:

interface User {

  // User name
  username: string;

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

Return list of users.

Bank Account Management

GET {nexusBase}/bank-accounts

Response:

A list of BankAccount objects that belong to the requester.

interface BankAccount {
  // mnemonic name identifying this bank account.
  account: string;
  // IBAN
  iban: string;
  // BIC
  bic: string;
  // Legal subject owning the account.
  holder: string;
}
POST {nexusBase}/bank-accounts/{acctid}/prepared-payments/{pmtid}/submit

Ask nexus to submit one prepare payment at the bank.

Status Codes
  • 404 Not Found – the unique identifier or the bank connection could not be found in the system
GET {nexus}/bank-accounts/{my-acct}/prepared-payments/{uuid}

Ask the status of payment $uuid.

Response:

interface PaymentStatus {

  // Payment unique identifier
  uuid: 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;
}
POST {nexusBase}/bank-accounts/{my-acct}/prepared-payments

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 {
  // Optional field to specify the bank connection to
  // use for such operation.
  bankConnection?: string;
  // dashed date (YYYY-MM-DD) of the earliest payment
  // in the result. Optional, defaults to "earliest
  // possible" date.
  start: string;
  // dashed date (YYYY-MM-DD) of the earliest payment
  // in the result. Optional, defaults to "latest
  // possible" date.
  end: string;
}
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 list of Transaction objects.

interface Transaction {
  // local bank account involved in the transaction.
  account: string;

  // counterpart IBAN
  counterpartIban: string;

  // counterpart BIC
  counterpartBic: string;

  // counterpart holder name
  counterpartName: 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;

  // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction.
  date: string;

  // Payment subject.
  subject: string;
}

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:

interface BankConnectionRestoreRequest {

  name: string;

  // Restore a previous connection.  Take precedence
  // over the 'new' field.
  backup?: BankConnectionBackup;

  // Data to create a fresh bank connection without
  // restoring any backup.
  data?: BankConnectionNew;
}
interface ConnectionNew {

  // 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 connectionis being restored.

}

Response:

Status Codes
  • 409 Conflict – The name field exists already for the requesting user.
GET {nexusBase}/bank-connections

List available bank connections.

GET {nexusBase}/bank-connections/{connid}

Get information about one bank connection.

interface BankConnectionInfo {
   name: string;

   connectionType: string;

   ready: boolean;

   // Did the user review the bank's keys?
   bankKeysReviewed: boolean;
}
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}/accounts/fetch

Update accounts that are accessible via this bank connection.

GET {nexusBase}/bank-connections/{connid}/accounts

list accounts that are accessible via this bank connection and what LibEuFin accounts they are connected to.

Facades

GET <nexus>/facades

List available facades.

POST {nexus}/facades

Create a new facade; it requires a FacadeInfo as the request’s body.

GET {nexus}/facades/${fcid}

Get details about a facade.

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

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

   // Name of the user that created the facade.
   // Whenever the facade accesses a resource it is allowed to
   // access, the creator must *also* have access to that resource.
   creator: 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.

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;

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

  // Time between incremental requests
  intervalIncremental: string;

  // FIXME:  maybe more scheduling parameters?
}