Nexus API ########### .. contents:: Table of Contents HTTP API ======== Configuration ------------- Returns configuration values currently used by the Nexus process. This API is mostly used by testing jobs. .. http:get:: {nexusBase}/service-config **Response:** .. ts:def:: ServiceConfigResponse interface ConfigResponse { // Connection string to the database. dbConn: string; } Returns configuration values currently used by Nexus. .. http:get:: {nexusBase}/config **Response:** .. ts:def:: ConfigResponse 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 --------------- .. http:get:: {nexusBase}/user Get information about the current user (based on the authentication information in this request). **Response:** .. ts:def:: GetUserResponse interface UserResponse { // User name username: string; // Password password: string; } .. http:post:: {nexusBase}/users Create a new user. Only a superuser can call this API. **Request:** The body is a `User` object. **Response:** :http:statuscode:`409 Conflict`: Username is not available. **Details:** .. ts:def:: User interface User { // User name username: string; // Initial password password: string; } .. http:get:: {nexusBase}/users Return list of users. Test API -------- .. http: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. .. http:get:: {nexusBase}/bank-accounts **Response:** A list of `BankAccount` objects that belong to the requester. .. ts:def:: BankAccount interface BankAccount { // mnemonic name identifying this bank account. nexusBankAccountId: string; // IBAN iban: string; // BIC bic: string; // Legal subject owning the account. ownerName: string; } .. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit Ask nexus to submit one prepare payment at the bank. :http:statuscode:`404 Not found`: the unique identifier **or** the bank connection could not be found in the system .. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid} Ask the status of payment ``$uuid``. **Response:** .. ts:def:: PaymentStatus 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; } .. http: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** .. ts:def:: InitiatedPayments interface InitiatedPayments { // list of all the initiated payments' UID. initiatedPayments: PaymentStatus[]; } .. http: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:** .. ts:def:: PreparedPaymentRequest 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:** .. ts:def:: PreparedPaymentResponse interface PreparedPaymentResponse { // Opaque identifier to be communicated when // the user wants to submit the payment to the // bank. uuid: string; } .. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions Nexus will download bank transactions using the given connection. **Request:** .. ts:def:: CollectedTransaction 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; } .. http: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. .. ts:def:: Transaction 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[]; }; } .. ts:def:: 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; } } .. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} This call returns the information related to the task associated to ``taskId``. **Response** In case of success, it responds with one `NexusTask` object. .. http:delete:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} This call deletes the task associated to ``taskId``. .. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule This call returns a list of all the scheduled tasks, under one bank account. The list is wrapped into a ``tasks`` object, and contains elements of `NexusTask`. **Response** .. ts:def:: NexusTask // 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; } Bank Connections ---------------- Bank connections connect the local LibEuFin bank account to the real bank. .. http:post:: /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. .. ts:def:: NewBankConnection 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. .. ts:def:: BankConnectionRestoreRequest interface BankConnectionRestoreRequest { source: "backup"; // connection name. name: string; // Backup data, as typically returned by the "../export-backup" API. backup: BankConnectionBackup; passphrase?: string; } .. ts:def:: BankConnectionNew 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! } .. ts:def:: BankConnectionBackup interface BankConnectionBackup { // The information needed in this type depend entirely // on which connection is being restored. } **Response:** :http:statuscode:`406 Not acceptable`: a connection with the requested name already exists for this user. .. http:post:: {nexusBase}/bank-connections/delete-connection **Request:** .. ts:def:: BankConnectionDeletion interface BankConnectionDeletion { // label of the bank connection to delete bankConnectionId: string; } .. http:get:: {nexusBase}/bank-connections List available bank connections. **Response** .. ts:def:: BankConnection interface BankConnection { // connection type. For example "ebics". type: string; // connection name as given by the user at // the moment of creation. name: string; } .. http:get:: {nexusBase}/bank-connections/{connId} Get information about one bank connection. .. ts:def:: BankConnectionInfo 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; } .. http:post:: {nexusBase}/bank-connections/{connId}/connect Initialize the connection by talking to the bank. .. http:post:: {nexusBase}/bank-connections/{connId}/export-backup Make a passphrase-encrypted backup of this connection. .. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts Update accounts that are accessible via this bank connection. .. http:get:: {nexusBase}/bank-connections/{connId}/accounts List the bank accounts that this bank connection provides access to. .. ts:def:: OfferedBankAccount 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; } .. http: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. .. ts:def:: ImportBankAccount 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; } Facades ------- .. http:get:: /facades List available facades. .. http:post:: {nexus}/facades Create a new facade; it requires a `FacadeInfo` as the request's body. .. http:get:: {nexus}/facades/${fcid} Get details about a facade. .. ts:def:: FacadeInfo 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; // On which currency this facade operates. Note: // ideally, Nexus will provide a global object that // holds such information. currency: 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 ------------------------- .. http:get:: {nexus}/bank-connection-protocols List supported bank connection protocols. .. http: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. .. ts:def:: EbicsHostTestRequest 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. .. http: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. .. http: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: .. ts:def:: TalerWireGatewayFacadeConfig 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? }