Table of Contents
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¶Response:
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.
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:
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.
Request:
interface UserChangePassword {
newPassword: string;
}
Response:
200 OK: The password was successfully changeD.
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 the list of all users.
Response:
interface UsersResponse {
users: UserResponse[];
}
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.
Response
interface QueryPermissionsResponse {
permissions: LibeufinPermission[];
}
POST {nexusbase}/permissions¶Modifies permissions.
Request
interface QueryPermissionsResponse {
action: "grant" | "revoke";
permission: LibeufinPermission;
}
**Response**
The response is an empty JSON object.
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.
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¶Response:
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.
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¶Asks 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,
// 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:
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:
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;
}
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;
}
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.
Request:
Response:
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;
}
}
POST {nexusBase}/bank-accounts/{acctid}/schedule¶This endpoint allows the caller to define a recurrent execution of a task.
Request
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.
Response
// 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.
Response
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 connect the local Nexus bank account to the 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;
// 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
}
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;
}
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;
}
Response:
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.
Response:
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.
Response:
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.
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. Only the
// following type is available.
config: TalerAnastasisFacadeState;
}
Response:
200 OK: Either the facade was created, or the request was idempotent. 409 Conflict: The facade name was unavailable.
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;
}
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 Nexus database. It will just make a request to the bank
and return the answer.
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 starting point is not explicitly given, it defaults to:
Request
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
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;
}
Once a facade with name fcid and type ftype has been
created, all its endpoints become offered by the following base
URL:
$NEXUS_URL/facades/$fcid/$ftype
For example, a taler-wire-gateway facade named foo will
offer its endpoints under
https://nexus.example.com/facades/foo/taler-wire-gateway/