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
Classes
Section titled “Classes”SimpleEbics
Section titled “SimpleEbics”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 itemawait ebics.generateKeys()
// 2. Send the public keys to the bank and print the initialization letter for the bankawait 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 newKeyconst { 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()
Section titled “constructor()”constructor(options: SimpleEbicsConfig)Creates an EBICS client for one subscriber.
| Parameter | Type | Description |
|---|---|---|
options | SimpleEbicsConfig | Bank and subscriber settings. |
SimpleEbicsConfig fields
| Field | Type | Required | Description |
|---|---|---|---|
bankName | string | Yes | Name of the bank, printed on the initialization letter. |
url | string | Yes | URL of the bank’s EBICS server. |
hostId | string | Yes | EBICS host ID of the bank. |
partnerId | string | Yes | EBICS partner (customer) ID. |
userId | string | Yes | EBICS user ID. |
key | string | Yes | The subscriber’s encrypted key data, as stored after generateKeys() or getBankKeys(). Pass '' before the keys have been generated. |
passphrase | string | Buffer | Yes | Passphrase that encrypts the key data. A string is decoded as Base64. |
iv | string | Buffer | Yes | Initialization vector for the key encryption. A string is decoded as Base64. |
verbose | boolean | No | Writes each EBICS response to the server console. |
allowInsecureHttps | boolean | No | If true, the bank server’s TLS certificate is not verified, for example for a test server with a self-signed certificate. |
Availability: Server
key: stringThe 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
Section titled “options”options: ClientOptions & SimpleEbicsConfigThe options passed to the constructor, as handed to the underlying EBICS library.
Type: ClientOptions & SimpleEbicsConfig · Availability: Server
generateKeys()
Section titled “generateKeys()”generateKeys(certificteOptions?: CertificateOptions): Promise<void>Generates new signature, authentication and encryption keys for the subscriber and stores them in key.
| Parameter | Type | Description |
|---|---|---|
certificteOptions | CertificateOptions | Optional. Settings for the self-signed certificates: subject, issuer, notBefore and notAfter. |
Returns: Promise<void> · Availability: Server
setKeys()
Section titled “setKeys()”setKeys(keys: Partial<Keys>): Promise<void>Sets existing keys, for example keys created with another EBICS client, and stores them in key.
| Parameter | Type | Description |
|---|---|---|
keys | Partial<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()
Section titled “initializeIni()”initializeIni(): Promise<EbicsKeyManagementResponse>Sends the subscriber’s public signature key to the bank (EBICS order INI).
Returns: Promise<EbicsKeyManagementResponse> · Availability: Server
initializeHia()
Section titled “initializeHia()”initializeHia(): Promise<EbicsKeyManagementResponse>Sends the subscriber’s public authentication and encryption keys to the bank (EBICS order HIA).
Returns: Promise<EbicsKeyManagementResponse> · Availability: Server
initialize()
Section titled “initialize()”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()
Section titled “createBankLetter()”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()
Section titled “getBankKeys()”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()
Section titled “initiatePayment()”initiatePayment(serviceName: string, paymentXml: string | Buffer, options: PredefinedUploadOrderOptionsH005): Promise<EbicsPaymentResponse>Uploads a payment order, for example a pain.001 message created with SimpleIso20022.
| Parameter | Type | Description |
|---|---|---|
serviceName | string | A 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. |
paymentXml | string | Buffer | The payment message as XML. |
options | PredefinedUploadOrderOptionsH005 | Settings of the order. Pass {} for the defaults. |
PredefinedUploadOrderOptionsH005 fields
| Field | Type | Required | Description |
|---|---|---|---|
msgVersion | string | No | Version of the message, for example '09' for pain.001.001.09. |
msgVariant | string | No | Variant of the message. |
msgFormat | string | No | Format of the message. |
scope | string | No | Scope of the service, for example a country code such as 'CH'. |
serviceOption | string | No | Service option agreed with the bank. |
containerType | string | No | Container type, for example 'ZIP'. |
signatureFlag | boolean | No | Whether the order carries an electronic signature. |
requestEDS | boolean | No | Requests a distributed electronic signature (EDS). |
signatureUserId | string | No | User ID of the signer, if different from userId. |
Returns: Promise<EbicsPaymentResponse> · Availability: Server
orderStatement()
Section titled “orderStatement()”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.
| Parameter | Type | Description |
|---|---|---|
serviceName | string | A 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. |
options | PredefinedDownloadOrderOptionsH005 | Optional. Settings of the order. |
PredefinedDownloadOrderOptionsH005 fields
| Field | Type | Required | Description |
|---|---|---|---|
start | string | Date | No | Start of the date range. |
end | string | Date | No | End of the date range. |
msgVersion | string | No | Version of the message. |
msgVariant | string | No | Variant of the message. |
msgFormat | string | No | Format of the message. |
scope | string | No | Scope of the service, for example 'CH'. |
serviceOption | string | No | Service option agreed with the bank. |
containerType | string | No | Container type. Defaults to 'ZIP' for EOP, STM and REP. |
Returns: Promise<EbicsStatementResponse> · Availability: Server
orderPain002StatusReports()
Section titled “orderPain002StatusReports()”orderPain002StatusReports(options?: PredefinedDownloadOrderOptionsH005): Promise<EbicsPain002Response>Downloads payment status reports (pain.002) and reads the original message ID and group status of each.
| Parameter | Type | Description |
|---|---|---|
options | PredefinedDownloadOrderOptionsH005 | Optional. As for orderStatement(). |
Returns: Promise<EbicsPain002Response> · Availability: Server
produceOrderXml()
Section titled “produceOrderXml()”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().
| Parameter | Type | Description |
|---|---|---|
orderFn | OrderFunction | A function that receives the order factories OrdersH004 and OrdersH005 and returns an order. |
Returns: Promise<string> · Availability: Server
executeCustomOrder()
Section titled “executeCustomOrder()”executeCustomOrder(orderFn: OrderFunction): Promise<EbicsBaseResponse>Sends an order that the other methods do not cover, built with the order factories of the EBICS library.
| Parameter | Type | Description |
|---|---|---|
orderFn | OrderFunction | A 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
SimpleEbicsOld
Section titled “SimpleEbicsOld”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 & SimpleEbicsConfigkey: stringinitializeIni(): 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
Section titled “SimpleIso20022”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()
Section titled “createSepaPain001Message()”createSepaPain001Message(message: SEPACreditPaymentInitiationConfig): stringCreates a pain.001 message for SEPA credit transfers in euros.
| Parameter | Type | Description |
|---|---|---|
message | SEPACreditPaymentInitiationConfig | The payer and the payments. |
SEPACreditPaymentInitiationConfig fields
| Field | Type | Required | Description |
|---|---|---|---|
initiatingParty | Party | Yes | The party that sends the payments. It is also the debtor: its account and agent are debited. |
paymentInstructions | SEPACreditPaymentInstruction[] | Yes | At least one payment. |
messageId | string | No | ID of the message, at most 35 characters. Defaults to a generated ID. |
creationDate | Date | No | Creation date of the message. Defaults to now. |
categoryPurpose | ExternalCategoryPurpose | No | ISO 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()
Section titled “createSwitfPain001Message()”createSwitfPain001Message(message: SWIFTCreditPaymentInitiationConfig): stringCreates a pain.001 message for international (SWIFT) credit transfers in any currency.
| Parameter | Type | Description |
|---|---|---|
message | SWIFTCreditPaymentInitiationConfig | The 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()
Section titled “createRtpPain001Message()”createRtpPain001Message(message: RTPCreditPaymentInitiationConfig): stringCreates a pain.001 message for US real-time payments (RTP) in US dollars.
| Parameter | Type | Description |
|---|---|---|
message | RTPCreditPaymentInitiationConfig | The payer and the payments: initiatingParty, paymentInstructions with currency 'USD', and the optional messageId and creationDate. |
Returns: string: the message as XML. · Availability: Server
createAchPain001Message()
Section titled “createAchPain001Message()”createAchPain001Message(message: ACHCreditPaymentInitiationConfig): stringCreates a pain.001 message for US ACH credit transfers in US dollars.
| Parameter | Type | Description |
|---|---|---|
message | ACHCreditPaymentInitiationConfig | The 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()
Section titled “parseCamt053Message()”parseCamt053Message(messageXml: string | Buffer | ArrayBuffer): CashManagementEndOfDayReportReads a camt.053 end-of-day account statement, for example a file downloaded with SimpleEbics.orderStatement('EOP').
| Parameter | Type | Description |
|---|---|---|
messageXml | string | Buffer | ArrayBuffer | The 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
SimpleEbicsConfig
Section titled “SimpleEbicsConfig”interface SimpleEbicsConfigSettings for the SimpleEbics constructor. See the field table there.
Availability: Server
OrderFunction
Section titled “OrderFunction”type OrderFunction = (orders: { OrdersH004: typeof OrdersH004; OrdersH005: typeof OrdersH005 }) => anyA function that builds an EBICS order from the order factories of the EBICS library, used by produceOrderXml() and executeCustomOrder().
Availability: Server
EbicsReponseFile
Section titled “EbicsReponseFile”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
EbicsStatementResponse
Section titled “EbicsStatementResponse”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
EbicsPaymentResponse
Section titled “EbicsPaymentResponse”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
EbicsPain002File
Section titled “EbicsPain002File”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.
EbicsPain002Response
Section titled “EbicsPain002Response”interface EbicsPain002Response extends EbicsDownloadResponse { files: EbicsPain002File[]}Result of orderPain002StatusReports(): the bank’s response plus the status reports.
Availability: Server
Related
Section titled “Related”- Configuration items
- Sys.Zip
- Sys API overview