node-ebics / node-ebics-client

Node.js EBICS Client - compliant with ISO 20022

node-ebics-client

Pure node.js ( >=8 ) implementation of EBICS ( Electronic Banking Internet Communication ).

The client is aimed to be 100% ISO 20022 compliant, and supports the complete initializations process ( INI, HIA, HPB orders ) and HTML letter generation.

Supported Banks

The client is currently tested and verified to work with the following banks:

• Credit Suisse (Schweiz) AG
• Zürcher Kantonalbank
• Raiffeisen Schweiz
• BW Bank
• Bank GPB International S.A.
• Bank GPB AO
• J.P. Morgan

Inspiration

The basic concept of this library was inspired by the EPICS library from the Railslove Team.

Copyright

Copyright: Dimitar Nanov, 2019-2022.
Licensed under the MIT license.

node-ebics-client's Issues

@anandsahil This information should be in the README

@anandsahil
Hi,
First part, where you define clinet is OK.
You do not have to generate keys yourself. It is done automatically when initialisation process is started.
Here are the steps:

1. You create a clinet - you've done that.
2. You send initialisation process orders (INI and HIA) like that:

• get INI order - you've done it;
• with async/await: const response = await client.send(iniOrder);
• without async/await client.send(iniOrder).then(r => console.log(r)).catch(e => console.log(e));
• do the same for HIA order

3. You have to generate and print ini letter. You can do it like this:

const bankName = 'Zürcher Kantonalbank';
const template = fs.readFileSync('your_path_to_this_file/ini.hbs').toString();
const letter = new ebics.BankLetter({ client, bankName, template });

await letter.serialize('bankLetterFilename.html'); // or then, catch

• Open the html file. Print it. Send it to the bank. Now they are suppose to activate your account.

4. Once your account is activated by the bank, now you're ready to download their (bank) keys:

• Execute HPB order and get the keys

const hpbOrder = ebics.Orders.HPB;
const response  = await client.send(hpbOrder);
await client.setBankKeys(response.bankKeys);

5. Now you're ready to go.

Hope this will help.

Regards,
Vlad

Originally posted by @vladhristov in #1 (comment)

Need help with multiple signatures

One of the request from the bank is that in case of XCT order, there should be multiple signatures. Any ideas how can I use this library to do that?

Typescript support

Is it planned to write types for this library?

Add X.509 support

Some banks ( mainly french ) do not support RSA authentication, but rather X.509. It would be an important addition to implement support for such authentication.

The test platform which is mentioned in #9 supports only X.509 authentication, so implementing it and testing against the platform will enable us to implement the H005 ( Ebics 3.0 ) standard as well.

What should be done

• Research and decide on a good X.509 nodejs library.
• Implement X.509 authentication and encryption.
• Make encryption modular/switchable ( RSA / X.509 ).

Useful

https://software.elcimai.com/efs/accueil-qualif.jsp - test platform ( french only ).

Incorrect signature length (257 vs 256)

I have a bit of a weird edge case with a payment file where the signature length somehow gets 257 bytes instead of 256 bytes. I'm trying to debug it, but not really sure where the actual issue is yet. If anyone would be able to help with this that would be great!

client.keys is undefined when creating a bankLetter

I ran into the problem that my client.keys are undefined. And thus the bankLetter cannot be created.

Here is my code:

initZKB = async () => {
const ebicsClient = await new ebics.Client({
        url: 'https://testplattform.zkb.ch/ebicsweb/ebicsweb',
        partnerId: 'XXX',
        userId: 'XXX',
        hostId: 'XXX',
        passphrase: 'PASS',
        keyStorage: ebics.fsKeysStorage('./src/keys-dev')
      })

      await ebicsClient
        .send(ebics.Orders.INI)
        .then((resp: any) => {
          console.log('Response for INI order %j', resp);
          return ebicsClient.send(ebics.Orders.HIA);
        })
        .then(async (resp: { technicalCode: string }) => {
          console.log('Response for HIA order %j', resp);
          if (resp.technicalCode !== '000000')
            throw new Error('Something might went wrong');

          console.log(
            'Public keys should be sent to bank now. See examples/bankLetter.js'
          );
        });

      const bankName = 'Zürcher Kantonalbank';
      const template = fs.readFileSync('./src/ini_de.hbs').toString();
      const bankLetterFile = path.join(os.homedir(), 'bankLetter_de.html');

      const letter = await new ebics.BankLetter({
        ebicsClient,
        bankName,
        template
      });

// This serialize() function throws the error
      await letter.serialize(bankLetterFile).then(() => {
        console.log('Send your bank the letter (%s)', bankLetterFile);
      });

}

And this is the error:

UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'keys' of undefined
    at BankLetter.generate (/xxx/node_modules/ebics-client/lib/BankLetter.js:48:34)
    at BankLetter.serialize (/xxx/node_modules/ebics-client/lib/BankLetter.js:63:29)

Does anyone have an idea why the keys are not set?
Thanks in advance.

Redesign defaultKeyEncrypter to use modern encryption.

Currently the defaultKeyEncrypter which is used to encrypt persisted keys is using deprecated createCipher method.

This results in weaker encryption. Migrating the encryption into some modern one would involve changing the keys files format, so a convertor should be written in order to migrate old ones to new ones, as well as some kind of metadata in the new format in order to assure correct keys file version.

TODO:

• Discuss and decide the new keys format (maybe a binary one with metadata as first few bits)
• Implement encryption and decryption with the newly decided format, plus version and corruption checking.
• Write a tool to upgrade v1 ( current ) files to v2.

Error while decrypting the keys

I am able to encrypt the key. While decrypting the key it is throwing JSON parse error unexpected json error. Please help me out.

Support for Custom Order Types

Hi,

Is this possible to use this library with custom order types? I am trying to connect to UBS and download transaction and position statements. They have custom order types like ZAA for forex transaction download.

Thanks

Demo EBICS server

Hi,

I try to implement EBICS on PHP and got the proble,
Have you an address of demo-server for test ebics protocol? Or how do you testing requests?

Test platform

Hello !

Which ISO 20022 test platform have you used for testing your EBICS library ?

Drop unneeded dependencies

The following two dependencies can be dropped:

• moment.js - it is used to format dates in letters - a custom ISO formatter based on JS native Date type can be implemented.

• bn.js - as node-forge library exposes it's own BigNumber implementation ( based on jsbn ) we can use this one instead of another implementation.

TODOS:

• Implement custom date validation and formatting utils and drop moment.js
• Write own BigNumber wrapper which uses jsbn from node-forge and use it where needed.

how to transfer with XG1

hi,
i am working on a application that the app should Settle workers' wages every night,
i use EBICS and want to use XG1 order but not found any sample file for mytestfile.xml in send-xg1-order.js.
I apologize for my bad English
thanks.

Getting 091008 - EBICS_BANK_PUBKEY_UPDATE_REQUIRED for upload orders

I am getting 091008 - [EBICS_BANK_PUBKEY_UPDATE_REQUIRED] Bank key invalid error on upload orders, CCT for example.

Download orders are working ok.
Refetching bank keys don't help.

Connecting to Handelsbanken, if that matters.

Wrong public key by bigger than usual exponent.

Some banks use unusually big exponents when generating public keys, this leads to wrong key public key generation.

Different licenses - LICENSE (MIT) vs package.json (GPL-3.0-only)

It seems that the update of the package.json was overlooked when updating the LICENSE (7520a56). The package.json still contains the old GPL-3.0-only license which has already been updated in the LICENSE file. If I understand correctly, it should be just a matter of updating the package.json to MIT, correct?

send-c53.order.js ERR_INVALID_ARG_TYPE

Hello,

Thank you for your interesting work !

I'm trying to download c53 from Credit-Suisse.
Letter and and keys are okay and my account has been activated by the bank.
I use sen-c53-order.js
Sometimes i can download some data but the next time I get an ERR_INVALID_ARG_TYPE error.
See screenshot.

Any hints ?

Best regards.
JP Buttet

C53 has "junk data" in header and footer?

I'm trying to get C53 statements instead of STA for one of our projects, however it seems that the XML I get has some header & footer information in there. Not sure how to deal with this properly?

I'm simply using the following code now:

const data = Buffer.from(resp.orderData); fs.writeFile("myfilename.dat", data.toString('utf8'), function (err)

Critical vulnerability on xmldom

xmldom *
Severity: critical
Misinterpretation of malicious XML input - GHSA-5fg8-2547-mr8q
xmldom allows multiple root nodes in a DOM - GHSA-crh6-fp67-6883
No fix available
node_modules/xmldom
ebics-client *
Depends on vulnerable versions of xmldom
node_modules/ebics-client

Better to use @xmldom/xmldom

Postfinance Test account

it is possible to gain access to Swiss Postfinance testplatform to test EBICS

It is free of charge and open.
https://isotest.postfinance.ch/corporates/register
https://testplattform.postfinance.ch/corporates/register

here is some documentation.
https://testplattform.postfinance.ch/corporates/help

https://www.postfinance.ch/content/dam/pfch/doc/prod/pay/FS_EBICS_Parameterblatt_Software_479.07_de.pdf

I am open to do some testing and verification as we have a live account.

V.

key format and passphrase

Hi, nice work

I would like to read an extract of information of my bank account from a script.
Is EBICS able to do that ?

I tried to do it from the information i got from https://www.certeurope.fr :

• I got a key :
  I have a pem file (looks like an ssh public key)
  and a der file (binary)
• I got some parameters : hostid, url, userid, partnerid.

Could you please give me some intel about your program so i can understand how it work.

• Can you explain what is the "passphrase" and what it looks like ?

• And what is the "key" format you want ? which is which

Thank you in advance for your reply

Ebics 3.0 compatible ?

Is the library or someone has implement new ebics 3.0 standard ?
New schema in H005

Thanks

Replacing `request` with `rock-req` breaks the library

I believe the API of rock-req is not followed correctly, and this breaks the library in its current release (v4)

https://github.com/node-ebics/node-ebics-client/blob/master/lib/Client.js#L218

rock.post(
  this.url, 
  {
     body: r,
     headers: { 'content-type': 'text/xml;charset=UTF-8' },
  },
...

Should be replaced with

rock.(
  {
    method: 'POST',
    url: this.url, 
     body: r,
     headers: { 'content-type': 'text/xml;charset=UTF-8' },
  },
...

See https://github.com/carboneio/rock-req/blob/master/doc/api.md

This also seems to break the response parsing in the lib.

Demo for Bank statement

Hello,

May I have an example how to receive banque statement daily ? automatically ?

Thank you

CCT request always response error

Hello, great library.

Can you give me an advise, why I get error EBICS_INVALID_ORDER_DATA_ FORMAT on CCT request?

Submitting CCT initialization, then submitting Transfer with this OrderData:

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
    <CstmrCdtTrfInitn>
        <GrpHdr>
            <MsgId>8c448cb606054338904493f77e13dabd</MsgId>
            <CreDtTm>2021-02-24T16:34:36</CreDtTm>
            <NbOfTxs>1</NbOfTxs>
            <CtrlSum>100.00</CtrlSum>
            <InitgPty>
                <Nm>SENDER NAME</Nm>
            </InitgPty>
        </GrpHdr>
        <PmtInf>
            <PmtInfId>SENDERNAME-58c2d396c548</PmtInfId>
            <PmtMtd>TRF</PmtMtd>
            <BtchBookg>true</BtchBookg>
            <NbOfTxs>1</NbOfTxs>
            <CtrlSum>100.00</CtrlSum>
            <PmtTpInf>
                <SvcLvl>
                    <Cd>SEPA</Cd>
                </SvcLvl>
            </PmtTpInf>
            <ReqdExctnDt>2021-02-24</ReqdExctnDt>
            <Dbtr>
                <Nm>SENDER NAME</Nm>
            </Dbtr>
            <DbtrAcct>
                <Id>
                    <IBAN>CH1004835833740031001</IBAN>
                </Id>
            </DbtrAcct>
            <DbtrAgt>
                <FinInstnId/>
            </DbtrAgt>
            <ChrgBr>SLEV</ChrgBr>
            <CdtTrfTxInf>
                <PmtId>
                    <EndToEndId>NOTPROVIDED</EndToEndId>
                </PmtId>
                <Amt>
                    <InstdAmt Ccy="EUR">100.00</InstdAmt>
                </Amt>
                <CdtrAgt>
                    <FinInstnId/>
                </CdtrAgt>
                <Cdtr>
                    <Nm>RECEIVER NAME</Nm>
                </Cdtr>
                <CdtrAcct>
                    <Id>
                        <IBAN>DE67120300001032686147</IBAN>
                    </Id>
                </CdtrAcct>
                <RmtInf>
                    <Ustrd>SOME PURPOSE</Ustrd>
                </RmtInf>
            </CdtTrfTxInf>
        </PmtInf>
    </CstmrCdtTrfInitn>
</Document>

Multisegment download support

It is currently impossible to perform multisegmented downloads.

Sometimes we may have multiple downloadable segments coming from EBICS. In this case, the first request/response pair is transferred in Initialisation phase. Following requests are delivered in Transfer phase and may not contain a transaction key. After all segments have been transferred, the client may request a Receipt.

Diagram from spec:

Proposed PR contains a loop that makes requests until the last segment is received from EBICS.