Skip to content

Sys.Banking

Sys.Banking connects server-side code to banks. SimpleEbics talks to a bank’s EBICS server: it sets up the subscriber keys, uploads payment orders and downloads account statements and payment status reports. SimpleIso20022 creates ISO 20022 payment messages (pain.001) and reads account statements (camt.053).

An EBICS Connection configuration item (This.$Config.<name>) provides most of the connection fields that SimpleEbics needs.

Availability: Server

SimpleEbics is an EBICS client using EBICS version 3.0 (H005). One instance stands for one subscriber (partner and user) at one bank.

Before the first order, the subscriber’s keys must be set up once:

const ebics = new Sys.Banking.SimpleEbics({ ...This.$Config.EbicsConnection, key: '', bankName: 'Example Bank' })
// 1. Generate the subscriber keys and store ebics.key, for example in the configuration item
await ebics.generateKeys()
// 2. Send the public keys to the bank and print the initialization letter for the bank
await ebics.initialize()
const letterHtml = await ebics.createBankLetter()
// 3. After the bank has activated the subscriber: download the bank's keys,
// compare the hashes with those the bank published, and store newKey
const { e002Hash, x002Hash, newKey } = await ebics.getBankKeys()

After that, orders can be sent:

const ebics = new Sys.Banking.SimpleEbics({ ...This.$Config.EbicsConnection, bankName: 'Example Bank' })
const payment = await ebics.initiatePayment('SCT', painXml, {})
const statements = await ebics.orderStatement('EOP', { start: '2026-10-01', end: '2026-10-27' })
for (const file of statements.files) {
const report = Sys.Banking.SimpleIso20022.parseCamt053Message(file.xml)
}

The methods return the bank’s response without checking it. Check technicalCode and businessCode: '000000' means success; the other technicalCode… and businessCode… fields explain an error.

constructor(options: SimpleEbicsConfig)

Creates an EBICS client for one subscriber.

ParameterTypeDescription
optionsSimpleEbicsConfigBank and subscriber settings.

SimpleEbicsConfig fields

FieldTypeRequiredDescription
bankNamestringYesName of the bank, printed on the initialization letter.
urlstringYesURL of the bank’s EBICS server.
hostIdstringYesEBICS host ID of the bank.
partnerIdstringYesEBICS partner (customer) ID.
userIdstringYesEBICS user ID.
keystringYesThe subscriber’s encrypted key data, as stored after generateKeys() or getBankKeys(). Pass '' before the keys have been generated.
passphrasestring | BufferYesPassphrase that encrypts the key data. A string is decoded as Base64.
ivstring | BufferYesInitialization vector for the key encryption. A string is decoded as Base64.
verbosebooleanNoWrites each EBICS response to the server console.
allowInsecureHttpsbooleanNoIf true, the bank server’s TLS certificate is not verified, for example for a test server with a self-signed certificate.

Availability: Server

key: string

The subscriber’s current encrypted key data. It changes when generateKeys(), setKeys() or getBankKeys() store new keys; save it so that the next instance can use it as key.

Type: string · Availability: Server

options: ClientOptions & SimpleEbicsConfig

The options passed to the constructor, as handed to the underlying EBICS library.

Type: ClientOptions & SimpleEbicsConfig · Availability: Server

generateKeys(certificteOptions?: CertificateOptions): Promise<void>

Generates new signature, authentication and encryption keys for the subscriber and stores them in key.

ParameterTypeDescription
certificteOptionsCertificateOptionsOptional. Settings for the self-signed certificates: subject, issuer, notBefore and notAfter.

Returns: Promise<void> · Availability: Server

setKeys(keys: Partial<Keys>): Promise<void>

Sets existing keys, for example keys created with another EBICS client, and stores them in key.

ParameterTypeDescription
keysPartial<Keys>Keys in PEM format: A006 (signature), X002 (authentication), E002 (encryption), and the bank keys bankX002 and bankE002. Each is an object with a pem property.

Returns: Promise<void> · Availability: Server

initializeIni(): Promise<EbicsKeyManagementResponse>

Sends the subscriber’s public signature key to the bank (EBICS order INI).

Returns: Promise<EbicsKeyManagementResponse> · Availability: Server

initializeHia(): Promise<EbicsKeyManagementResponse>

Sends the subscriber’s public authentication and encryption keys to the bank (EBICS order HIA).

Returns: Promise<EbicsKeyManagementResponse> · Availability: Server

initialize(): Promise<{ iniResult: EbicsKeyManagementResponse; hiaResult: EbicsKeyManagementResponse }>

Sends INI and then HIA, as initializeIni() and initializeHia() do.

Returns: Promise<{ iniResult: EbicsKeyManagementResponse; hiaResult: EbicsKeyManagementResponse }> · Availability: Server

createBankLetter(): Promise<string>

Creates the initialization letter in English, with the hashes of the subscriber’s public keys. The subscriber signs it and sends it to the bank, which then activates the subscriber.

Returns: Promise<string>: the letter as HTML. · Availability: Server

getBankKeys(): Promise<{ e002Hash: string; x002Hash: string; newKey: string; hpbResult: EbicsKeyManagementResponse }>

Downloads the bank’s public keys (EBICS order HPB) and, if the bank answers with success, stores them in key. Compare the returned hashes with the ones the bank published before you rely on the keys.

Returns: Promise<{ e002Hash: string; x002Hash: string; newKey: string; hpbResult: EbicsKeyManagementResponse }>: the SHA-256 fingerprints of the bank’s encryption (e002Hash) and authentication (x002Hash) certificates, the updated key (newKey), and the bank’s response. · Availability: Server

initiatePayment(serviceName: string, paymentXml: string | Buffer, options: PredefinedUploadOrderOptionsH005): Promise<EbicsPaymentResponse>

Uploads a payment order, for example a pain.001 message created with SimpleIso20022.

ParameterTypeDescription
serviceNamestringA predefined EBICS upload service: 'SCT' (SEPA credit transfer), 'MCT', 'DCT' or 'XCT' (pain.001), 'SDD' or 'DDD' (direct debit, pain.008). Lowgile throws for other names; use executeCustomOrder() for them.
paymentXmlstring | BufferThe payment message as XML.
optionsPredefinedUploadOrderOptionsH005Settings of the order. Pass {} for the defaults.

PredefinedUploadOrderOptionsH005 fields

FieldTypeRequiredDescription
msgVersionstringNoVersion of the message, for example '09' for pain.001.001.09.
msgVariantstringNoVariant of the message.
msgFormatstringNoFormat of the message.
scopestringNoScope of the service, for example a country code such as 'CH'.
serviceOptionstringNoService option agreed with the bank.
containerTypestringNoContainer type, for example 'ZIP'.
signatureFlagbooleanNoWhether the order carries an electronic signature.
requestEDSbooleanNoRequests a distributed electronic signature (EDS).
signatureUserIdstringNoUser ID of the signer, if different from userId.

Returns: Promise<EbicsPaymentResponse> · Availability: Server

orderStatement(serviceName: string, options?: PredefinedDownloadOrderOptionsH005): Promise<EbicsStatementResponse>

Downloads account statements or reports. The bank’s files are unpacked if they come as a ZIP archive.

ParameterTypeDescription
serviceNamestringA predefined EBICS download service: 'EOP' (end-of-period statement, camt.053), 'STM' (intraday report, camt.052), 'REP' (debit and credit notifications, camt.054) or 'PSR' (payment status report, pain.002). Lowgile throws for other names; use executeCustomOrder() for them.
optionsPredefinedDownloadOrderOptionsH005Optional. Settings of the order.

PredefinedDownloadOrderOptionsH005 fields

FieldTypeRequiredDescription
startstring | DateNoStart of the date range.
endstring | DateNoEnd of the date range.
msgVersionstringNoVersion of the message.
msgVariantstringNoVariant of the message.
msgFormatstringNoFormat of the message.
scopestringNoScope of the service, for example 'CH'.
serviceOptionstringNoService option agreed with the bank.
containerTypestringNoContainer type. Defaults to 'ZIP' for EOP, STM and REP.

Returns: Promise<EbicsStatementResponse> · Availability: Server

orderPain002StatusReports(options?: PredefinedDownloadOrderOptionsH005): Promise<EbicsPain002Response>

Downloads payment status reports (pain.002) and reads the original message ID and group status of each.

ParameterTypeDescription
optionsPredefinedDownloadOrderOptionsH005Optional. As for orderStatement().

Returns: Promise<EbicsPain002Response> · Availability: Server

produceOrderXml(orderFn: OrderFunction): Promise<string>

Returns the EBICS request XML for an order without sending it, for example to check an order before sending it with executeCustomOrder().

ParameterTypeDescription
orderFnOrderFunctionA function that receives the order factories OrdersH004 and OrdersH005 and returns an order.

Returns: Promise<string> · Availability: Server

executeCustomOrder(orderFn: OrderFunction): Promise<EbicsBaseResponse>

Sends an order that the other methods do not cover, built with the order factories of the EBICS library.

ParameterTypeDescription
orderFnOrderFunctionA function that receives the order factories OrdersH004 and OrdersH005 and returns an order. OrdersH005.genericUpload(document, options) and OrdersH005.genericDownload(options) take the upload or download option fields plus serviceName and msgName.
const result = await ebics.executeCustomOrder(({ OrdersH005 }) =>
OrdersH005.genericDownload({
serviceName: 'EOP',
msgName: 'camt.053',
msgVersion: '08',
scope: 'CH',
containerType: 'ZIP',
}),
)

Returns: Promise<EbicsBaseResponse>: the bank’s response. For a download, it also has orderData, the raw downloaded data. · Availability: Server

An earlier version of SimpleEbics, built on the older ebics-client library instead of @lowgile/ebics. Use it only if a bank does not work with SimpleEbics. It has the same constructor, SimpleEbicsConfig fields and members, which behave like those of SimpleEbics:

constructor(options: SimpleEbicsConfig)
options: ClientOptions & SimpleEbicsConfig
key: string
initializeIni(): Promise<EbicsKeyManagementResponse>
initializeHia(): Promise<EbicsKeyManagementResponse>
initialize(): Promise<{ iniResult: EbicsKeyManagementResponse; hiaResult: EbicsKeyManagementResponse }>
createBankLetter(): Promise<string>
getBankKeys(): Promise<{ e002Hash: string; x002Hash: string; newKey: string; hpbResult: EbicsKeyManagementResponse }>
setKeys(keys: Partial<Keys>): Promise<void>
generateKeys(certificteOptions?: CertificateOptions): Promise<void>
initiatePayment(serviceName: string, paymentXml: string | Buffer, options: PredefinedUploadOrderOptionsH005): Promise<EbicsPaymentResponse>
orderStatement(serviceName: string, options?: PredefinedDownloadOrderOptionsH005): Promise<EbicsStatementResponse>
orderPain002StatusReports(options?: PredefinedDownloadOrderOptionsH005): Promise<EbicsPain002Response>
produceOrderXml(orderFn: OrderFunction): Promise<string>
executeCustomOrder(orderFn: OrderFunction): Promise<EbicsBaseResponse>

The types ClientOptions, Keys, CertificateOptions and the order options come from ebics-client here.

Availability: Server

SimpleIso20022 creates ISO 20022 credit transfer messages (pain.001) and reads end-of-day account statements (camt.053). It uses the iso20022.js library, version 0.2.7.

const painXml = Sys.Banking.SimpleIso20022.createSepaPain001Message({
initiatingParty: {
name: 'Example AG',
id: 'EXAMPLEAG',
account: { iban: 'DE89370400440532013000' },
agent: { bic: 'COBADEFFXXX' },
},
paymentInstructions: [
{
type: 'sepa',
amount: 125000, // 1250.00 EUR, in cents
currency: 'EUR',
creditor: {
name: 'Supplier GmbH',
account: { iban: 'FR1420041010050500013M02606' },
agent: { bic: 'PSSTFRPPPAR' },
},
remittanceInformation: 'Invoice 4711',
},
],
})
createSepaPain001Message(message: SEPACreditPaymentInitiationConfig): string

Creates a pain.001 message for SEPA credit transfers in euros.

ParameterTypeDescription
messageSEPACreditPaymentInitiationConfigThe payer and the payments.

SEPACreditPaymentInitiationConfig fields

FieldTypeRequiredDescription
initiatingPartyPartyYesThe party that sends the payments. It is also the debtor: its account and agent are debited.
paymentInstructionsSEPACreditPaymentInstruction[]YesAt least one payment.
messageIdstringNoID of the message, at most 35 characters. Defaults to a generated ID.
creationDateDateNoCreation date of the message. Defaults to now.
categoryPurposeExternalCategoryPurposeNoISO 20022 category purpose code, for example 'SALA' for salaries.

A Party has the optional fields id, name, address (structured address with streetName, buildingNumber, postalCode, townName, country and more), account ({ iban } or { accountNumber }) and agent ({ bic } or { abaRoutingNumber }). A payment instruction has amount (in the minor unit of the currency, for example cents), currency, creditor (a Party), and the optional id, endToEndId and remittanceInformation.

Returns: string: the message as XML. · Availability: Server

createSwitfPain001Message(message: SWIFTCreditPaymentInitiationConfig): string

Creates a pain.001 message for international (SWIFT) credit transfers in any currency.

ParameterTypeDescription
messageSWIFTCreditPaymentInitiationConfigThe payer and the payments: initiatingParty, paymentInstructions, and the optional messageId and creationDate, as for createSepaPain001Message(). Creditors need a complete address.

Returns: string: the message as XML. · Availability: Server

createRtpPain001Message(message: RTPCreditPaymentInitiationConfig): string

Creates a pain.001 message for US real-time payments (RTP) in US dollars.

ParameterTypeDescription
messageRTPCreditPaymentInitiationConfigThe payer and the payments: initiatingParty, paymentInstructions with currency 'USD', and the optional messageId and creationDate.

Returns: string: the message as XML. · Availability: Server

createAchPain001Message(message: ACHCreditPaymentInitiationConfig): string

Creates a pain.001 message for US ACH credit transfers in US dollars.

ParameterTypeDescription
messageACHCreditPaymentInitiationConfigThe payer and the payments: initiatingParty, paymentInstructions with currency 'USD', the optional messageId and creationDate, and the optional localInstrument (ACH standard entry class, defaults to 'CCD').

Returns: string: the message as XML. · Availability: Server

parseCamt053Message(messageXml: string | Buffer | ArrayBuffer): CashManagementEndOfDayReport

Reads a camt.053 end-of-day account statement, for example a file downloaded with SimpleEbics.orderStatement('EOP').

ParameterTypeDescription
messageXmlstring | Buffer | ArrayBufferThe statement as XML text or UTF-8 data.

Returns: CashManagementEndOfDayReport: the report, with messageId, creationDate, statements, and the balances, entries and transactions of all statements. · Availability: Server

interface SimpleEbicsConfig

Settings for the SimpleEbics constructor. See the field table there.

Availability: Server

type OrderFunction = (orders: { OrdersH004: typeof OrdersH004; OrdersH005: typeof OrdersH005 }) => any

A function that builds an EBICS order from the order factories of the EBICS library, used by produceOrderXml() and executeCustomOrder().

Availability: Server

interface EbicsReponseFile {
xml: string
get binaryData(): Buffer
fileName?: string
}

One file downloaded from the bank: xml is its content as text, binaryData the raw bytes, and fileName the name of the file inside the ZIP archive, if the bank sent one.

Availability: Server

interface EbicsStatementResponse extends EbicsDownloadResponse {
files: EbicsReponseFile[]
}

Result of orderStatement(): the bank’s response (orderId, technicalCode, businessCode and their texts, and the raw orderData), plus the downloaded files.

Availability: Server

interface EbicsPaymentResponse extends EbicsUploadResponse {
transactionId: string
messageId: string
}

Result of initiatePayment(): the bank’s response, the EBICS transactionId, and the messageId read from the group header of the pain.001 message.

Availability: Server

interface EbicsPain002File extends EbicsReponseFile {
originalMessageId: string
status: 'ACTC' | 'ACCP' | 'RJCT' | 'ACWC'
}

One payment status report: the downloaded file, the message ID of the payment message it refers to (originalMessageId), and the group status (status).

Availability: Server

Note

status holds whatever group status the report contains, for example also PART or PDNG, and is undefined if the report has no group status.

interface EbicsPain002Response extends EbicsDownloadResponse {
files: EbicsPain002File[]
}

Result of orderPain002StatusReports(): the bank’s response plus the status reports.

Availability: Server