1.11.5. Nexus HTTP API

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


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

GET {nexusBase}/config


interface ConfigResponse {

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


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. The username carried along the HTTP basic auth points at the user to be shown.


interface UserResponse {

  // User name
  username: string;

  // Is this a super user?
  superuser: boolean;
POST {nexusBase}/users/{userName}/password

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


interface UserChangePassword {
  newPassword: string;


200 OK: The password was successfully changeD.

POST {nexusBase}/users

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


The body is a User object.


409 Conflict: Username is not available.


interface User {

  // User name
  username: string;

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

Return the list of all users.


interface UsersResponse {
  users: UserResponse[];

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 of type fetch and submit.
GET {nexusbase}/permissions

Lists all permissions.


interface QueryPermissionsResponse {
  permissions: LibeufinPermission[];
POST {nexusbase}/permissions

Modifies permissions.


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


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.


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.

GET {nexusBase}/bank-accounts


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

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}/submit-all-payment-initiations

Asks nexus to submit all the prepared initiations that weren’t already submitted.

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

Asks 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}

Asks the status of payment $uuid.


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

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


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.


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


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.


Refer to FetchParams for level and rangeType specifications.

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


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;

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

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

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


Query Parameters
  • 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.
  • 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.
  • size – Optional number indicating how many transactions are to be included in the response. It defaults to 5.


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.

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[];
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.


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

Shows taskId state.


// 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 fetched
  // or whose payments are submitted.  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;
DELETE {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}

This call deletes the task associated to taskId.

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

Shows all the scheduled tasks from acctid.


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.

POST <nexus>/bank-connections

Activate a new bank connection for the requesting user.


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;

  // Strictly dependent from the connection type.  Notably,
  // a "dialect" field is accepted here to adapt the EBICS client
  // to one particular bank.
  data: any;

This type allows to restore a previously made bank connection.

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.

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

This type is found in the backup field of BankConnectionRestore.

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


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

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


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

List available bank connections.


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;

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

interface EbicsConnectionInfo {
  ebicsUrl: string;
  ebicsHostId: string;
  partnerId: string;
  userId: string;
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.

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. 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 , in order to start operating.

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.

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;


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

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

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


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

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

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


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

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.


GET <nexus>/facades/{fcid}

Response: A FacadeShowInfo whose name is 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;

For “taler-wire-gateway” and “anastasis” facades, config contains the following type:

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

Deletes a facade.

POST {nexus}/facades

Creates a new facade.


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;


200 OK: Either the facade was created, or the request was idempotent. 409 Conflict: The facade name was unavailable.

Bank Connection Protocols

GET {nexus}/bank-connection-protocols

Lists supported bank connection protocols.

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.

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}


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.

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.


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, 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.


200 OK: JSON object of type IncomingHistory.

400 Bad request: Request malformed. Nexus 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. Nexus 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.
  // 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:


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