https://github.com/svapnil/iso20022.js
Create ACH, SEPA, FedNow, SWIFT, RTP payment initiations and process bank statements. Used in production to move hundreds of thousands of dollars a month.
https://github.com/svapnil/iso20022.js
ach banking cashmanagement iso20022 payment-initiation payments payments-rtp sepa
Last synced: about 2 months ago
JSON representation
Create ACH, SEPA, FedNow, SWIFT, RTP payment initiations and process bank statements. Used in production to move hundreds of thousands of dollars a month.
- Host: GitHub
- URL: https://github.com/svapnil/iso20022.js
- Owner: svapnil
- License: mit
- Created: 2024-07-16T16:47:05.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-22T02:02:04.000Z (8 months ago)
- Last Synced: 2025-09-22T03:32:45.890Z (8 months ago)
- Topics: ach, banking, cashmanagement, iso20022, payment-initiation, payments, payments-rtp, sepa
- Language: TypeScript
- Homepage: https://iso20022js.com
- Size: 957 KB
- Stars: 367
- Watchers: 2
- Forks: 24
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
iso20022.js
This package is meant for companies using ISO20022 to send and receive payment information, specifically initiating SEPA, ACH, FedWire, RTP, SWIFT payments and receiving cash management files.
Read the Docs: https://docs.iso20022js.com
The mission of this NPM package is to connect the most widely used programming language to the most widely used payment standard.
If you're interested in using iso20022.js and would like to use different payment types or ingest files using CAMT, please email [iso20022js@woodside.sh](mailto:iso20022js@woodside.sh).
[](https://cal.com/woodside/iso20022js?utm_source=banner&utm_campaign=oss)
# Installation
```bash
npm install iso20022.js
```
# Examples
Examples of ISO20022 messages being created across different payment types:
```bash
npx tsx examples/sepa-credit-transfer.ts
npx tsx examples/rtp-credit-transfer.ts
npx tsx examples/swift-credit-transfer.ts
npx tsx examples/get-account-messages.ts
```
# Usage
### Full Payment Initiation Example: Sending a SEPA Transfer
```ts
import { ISO20022 } from 'iso20022.js';
const iso20022 = new ISO20022({
initiatingParty: {
name: 'Acme Corporation',
id: 'ACMECORP',
account: {
iban: 'ES1234567890123456789012'
},
agent: {
bic: 'BANKESMMXXX',
bankAddress: {
country: 'ES'
}
}
},
});
const creditPaymentInitiation = iso20022.createSEPACreditPaymentInitiation([
{
type: 'sepa',
direction: 'credit',
amount: 1000,
currency: 'EUR',
creditor: {
name: 'Hans Schmidt',
account: {
iban: 'DE1234567890123456789012'
},
agent: {
bic: 'DEUTDEFFXXX'
},
address: {
streetName: 'Example Street',
buildingNumber: '123',
townName: 'Berlin',
countrySubDivision: 'Berlin',
postalCode: '10115',
country: 'DE'
}
}
}
]);
console.log(creditPaymentInitiation.toString());
```
Note that amounts are reresented in the smallest decimal unit (`$100.55` is stored as a number `10055`) and the decimal precision of a currency can be retrieved from `getCurrencyPrecision(Ccy)`
### Example: Sending an ACH Payment
```ts
// Send an ACH Payment Anywhere in the U.S.
const payment = iso20022.createACHCreditPaymentInitiation({
paymentInstructions: [
{
type: 'ach',
direction: 'credit',
amount: 1250000, // $12,500.00 Dollars
currency: 'USD',
creditor: {
name: 'Alex Kan',
account: {
accountNumber: '333456118812',
},
agent: {
abaRoutingNumber: '021000021',
}
},
remittanceInformation: 'PAYROLL - BIWEEKLY SALARY SR SOFTWARE ENGINEER'
}],
});
```
### Cash Management: Ingesting a CAMT.053 file
```ts
import { CashManagementEndOfDayReport } from 'iso20022.js';
const xml = fs.readFileSync('balance_report.xml', 'utf8');
const report = CashManagementEndOfDayReport.fromXML(xml);
console.log(report.transactions);
```
### Cash Management: Create an account request CAMT.003 file
```ts
import { ISO20022 } from 'iso20022.js';
import { CashManagementGetAccount } from 'iso20022.js';
const msg = new CashManagementGetAccount({
...
});
const xml = msg.serialize();
const json = msg.toJSON();
const msg2 = CashManagementGetAccount.fromXML(xml);
const msg3 = CashManagementGetAccount.fromJSON(json);
```
### Generic class implementation (preview)
If you need generic implementation to a type of message implemented you can do the following
```ts
const type = "CAMT.006"; // can come as an input
import { getISO20022Implementation } from 'iso20022.js';
let impl = getISO20022Implementation(type);
if (impl) {
const msg1 = impl.fromXml("some xml content");
const msg2 = impl.fromJSON({ some: object }); // following the ISO format
const msg3 = new impl({config: object}); // following the internal data definition
const xml1 = msg1.serialize(); // generate a xml message as string
const json2 = msg1.toJSON(); // generate a js object that can then be stringify
const data = msg1.data; // the internal representation of the message
}
```
### Testing
```bash
npm run test
```
## About ISO20022
ISO20022 is the standard format for financial transactions. This library aims to build a powerful yet simple API to create these files, following Typescript conventions.
You might want to use this package if you need to create these types of files.
# Features
| Feature | Description | Todo |
| ---------------------- | ---------------------------------------------------- | ---- |
| SWIFT Credit Transfer | Create SWIFT credit transfer messages | ✅ |
| CAMT Transactions | Ingest transaction data from CAMT files | ✅ |
| CAMT Requests | Query and Responses on accounts and transactions | ✅ |
| SEPA Credit Transfer | Create SEPA credit transfer messages | ✅ |
| ACH Credit Transfer | Create ACH credit transfer messages | ✅ |
| RTP / Fednow Credit Transfer | Create Fednow credit transfer messages | ✅ |
| FedWire Credit Transfer | Create FedWire credit transfer messages | 🚧 |
# Reasons to use `iso20022.js`
| Feature | Description | |
| ---------------------- | ---------------------------------------------------- | ---- |
| XML Generation | Generate valid ISO 20022 XML files | ✅ |
| Type Safety | Built with TypeScript for enhanced type checking | ✅ |
| Extensible | Easy to extend for custom message types | ✅ |
| Validation | Built-in validation for ISO 20022 message structures | ✅ |
# Security
`iso20022.js` is local, open source, and free to use. This means that payment instructions are created on your machine, not on a remote server.
We take security seriously, and are consistently looking for ways to improve. If you have any suggestions or find any security issues, please [open an issue](https://github.com/svapnil/iso20022.js/issues/new/choose).
**NOTE: We are tracking the [libxmljs vulnerability](https://github.com/svapnil/iso20022.js/issues/26), a dependency we use in our unit tests and have a plan to deprecate. Note that production use of `iso20022.js` is not affected by this vulnerability.**