Table of Contents
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.
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¶Create a new user. Only a superuser can call this API.
Request:
The body is a User object.
Response:
Details:
interface User {
// User name
username: string;
// Initial password
password: string;
}
GET {nexusBase}/users¶Return list of users.
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;
}
POST {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit¶Ask nexus to submit one prepare payment at the bank.
GET {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}¶Ask the status of payment $uuid.
Response:
interface PaymentStatus {
// 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;
}
GET {nexusBase}/bank-accounts/{acctid}/transactions¶Shows which transactions are stored locally at nexus.
Query parameters:
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 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:
name field exists already for
the requesting 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
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 {
bankConnectionId: string;
bankConnectionType: string;
// Is this bank connection ready, or
// are we waiting for the bank to activate
// the connection?
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}/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>/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;
}
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;
}
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 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?
}