Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flash-oss/aba-generator
Generate Australian banking ABA file
https://github.com/flash-oss/aba-generator
Last synced: about 2 months ago
JSON representation
Generate Australian banking ABA file
- Host: GitHub
- URL: https://github.com/flash-oss/aba-generator
- Owner: flash-oss
- License: apache-2.0
- Created: 2020-03-18T02:38:07.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-02-14T13:16:35.000Z (almost 2 years ago)
- Last Synced: 2024-04-29T17:08:02.145Z (8 months ago)
- Language: JavaScript
- Size: 43.9 KB
- Stars: 19
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ABA generator
Generate ABA Files from Node.js and browser.
Notable:
- The minified version of this module is 4.2kb. No dependencies.
- The source code of `aba-generator` is quite easy to read, understand, and amend. We welcome any changes.
## Changes between v1 and v2
- **BREAKING**: header options were `options: { ...headerData }`, become `options: { header: headerData }`.
- Added support of non-standard ABA files.
## Usage
Installation
```shell script
npm i -S aba-generator
```
Minimal example of sending money from your account:
```js
const ABA = require("aba-generator");
const aba = new ABA({
header: {
bank: "ANZ", // The bank processing this file
user: "Allowasa Pertolio Accounting&Tax", // Your (money sender) company name
userNumber: 1234, // Your ID in the bank system, often hardcoded to some number. Consult with your bank
description: "Credits Of The Wooloomooloo", // Description of the transactions within the file
// Optional
// bsb: String, // Main account BSB. Not in the ABA spec, but required by most banks
// account: String, // Main account number. Not in the ABA spec, but required by most banks
// date: Date|String|Number, // The date to be processed, default is now. If string must be DDMMYY format
// time: Date|String|Number, // The time to be processed. Not in the ABA spec, but required by most banks. If string must be HHmm format
},
});
const transaction = {
bsb: "061021", // recipient's account BSB
transactionCode: ABA.CREDIT,
// indicates "you are sending money (debit), they are receiving (credit)". ABA.PAY works in the same way but with code 53
account: "123456", // recipient's account number
amount: 12.0, // Number|String sending amount the recipient will see in their bank account
accountTitle: "Georgian Council of New South Wales", // recipient account name
reference: "Invoice # 1234", // payment reference, will be visible to the recipient
traceBsb: "061123", // your (sender) bank account BSB
traceAccount: "1234567", // your (sender) bank account number
remitter: "Acme Inc", // Your (sender) company name
// Optional
// tax: "N"|"W"|"X"|"Y"|" "|"", // Tax withholding indicator. Typically blank, meaning no tax. See ABA specification.
// taxAmount: Number|String, // Tax amount. Typically 0.
};
const file = aba.generate([transaction]);
console.log(file);
```
Should print:
```
0 01ANZ Allowasa Pertolio Accounti001234Credits Of T180320
1061-021 123456 500000001200Georgian Council of New South WaInvoice # 1234 061-123 1234567Acme Inc 00000000
7999-999 000000120000000012000000000000 000001
```
which is a fully valid ABA file. Note spaces in the end of the first and last lines.
Every line in the ABA file must be 120 chars. So data like `user`, `description`, `accountTitle`, etc are truncated if too long.
## Note
Even though the format is standardised, banks typically mandate some fields to be hardcoded.
## ABA file specification
1. http://ddkonline.blogspot.com/2009/01/aba-bank-payment-file-format-australian.html
1. https://www.cemtexaba.com/aba-format/cemtex-aba-file-format-details
1. https://github.com/mjec/aba/blob/master/sample-with-comments.aba
## API
### new ABA(options)
Constructor options:
```
* @param [options] {Object} Header data.
* @param [options.header.bank] {String} Name of financial institution processing this file. 3 characters, like "ANZ", "WBC"
* @param [options.header.user] {String} How the user will be shown in the transactions of the third party banks.
* @param [options.header.userNumber] {Number} The ID of the user supplying the file.
* @param [options.header.description] {String} Description of this file entries. Up to 12 chars.
* @param [options.header.bsb=""] {String} Main account BSB. Should be ignored according to the specs.
* @param [options.header.date=Date.now()] {Date|Number} Date to be processed.
* @param [options.header.time] {Date|Number} Time to be processed. Should be ignored according to the specs.
* @param [options.header.account=""] {String} Main account number. Up to 9 chars. Should be ignored according to the specs.
* @param [options.footer.type="7"] {String} This is an auto-generated field. But you can override it with anything.
* @param [options.footer.bsb="999999"] {String} This is an auto-generated field. But you can override it with anything.
* @param [options.footer.netTotal] {String} This is an auto-generated field. But you can override it with anything.
* @param [options.footer.creditTotal] {String} This is an auto-generated field. But you can override it with anything.
* @param [options.footer.debitTotal] {String} This is auto-generated field. But you can override it with anything.
* @param [options.footer.numberOfTransactions] {String} This is an auto-generated field. But you can override it with anything.
* @param [options.schemas] { [key in RecordTypeNumber]?: RecordSchema } custom schemas
```
### Custom transaction generating
You can add multiple custom schemas or replace default schemas to generate non-standard ABA files or those extended by a particular bank.
#### Keys description
`N` - is a string key with one character, that represents the first character in the ABA record,
for default schemas ("0" - Descriptive Record (header), "1" - Detail Record (transaction), and "7" - File Total Record (footer)).
Keep in mind that all ABA strings begin with this number and that the field `name: "type"` in the provided data and custom schema must be the same as `N` in the schema.
`recordType` - a string that identifies the batch's record type.
Descriptive Record -> header; Detail Record -> transaction; File Total Record -> footer
`name` - the name of a field (amount, tax, etc.).
`boundaries` - array with 2 numbers, that specify the start and end of the field in the record string.
`padding` - Alignment within field size, can be `left` or `right`, and only for type `string`, default alignment is to the right
`type` - type of the field, provide the desired type to reformat the field.
#### Possible types:
`string` – trim spaces and return the string
`money` - convert cents to dollars and return the number.
`integer` - trim all `0` in the start and return the number
`bsb` - remove "-" and return the string
`""` – retrieve the original string
```js
customSchemas = {
N: {
recordType: "header" | "transaction" | "footer",
fields: [
{
name: "string",
boundaries: [number, number],
type: "string" | "money" | "integer" | "bsb" | "",
padding: "left",
},
],
},
};
const aba = new ABA({ header: headerData, schemas: customSchemas });
```
### Attention! In order to generate standard footer you must have at least these transaction fields
```js
fields: [
{ name: "transactionType", boundaries: [0, 1], type: "string" },
{ name: "transactionCode", boundaries: [18, 20], type: "integer" },
{ name: "amount", boundaries: [20, 30], type: "money" },
];
```
### Custom schema use example
```js
const customSchemas = {
5: {
recordType: "transaction",
fields: [
{ name: "transactionType", boundaries: [0, 1], type: "string" }, // must be 5, same as schema number N
{ name: "bsb", boundaries: [1, 8], type: "bsb" },
{ name: "account", boundaries: [8, 17], type: "string" },
{ name: "transactionCode", boundaries: [18, 20], type: "integer" },
{ name: "amount", boundaries: [20, 30], type: "money" },
{ name: "traceBsb", boundaries: [80, 87], type: "bsb" },
{ name: "customString", boundaries: [120, 135], type: "string" },
{ name: "customInt", boundaries: [135, 140], type: "integer" },
{ name: "customBsb", boundaries: [140, 145], type: "bsb" },
{ name: "custom", boundaries: [145, 150], type: "" },
{ name: "customBsb", boundaries: [155, 160], type: "bsb" },
{ name: "customMoney", boundaries: [165, 170], type: "money" },
],
},
6: {
recordType: "header",
fields: [
{ name: "type", boundaries: [0, 1], type: "string" }, // must be 6, same as schema number N
{ name: "bsb", boundaries: [1, 8], type: "bsb" },
{ name: "account", boundaries: [8, 17], type: "string" },
{ name: "custom", boundaries: [145, 150], type: "" },
],
},
};
const aba = new ABA({
header: { type: "6", custom: "any", bsb: "123456", account: "12345678" }, // field "type" is requred
schemas: customSchemas,
});
const batches = aba.generate([transactions]);
```
### Default schemas
Here the list of standard schemas, you can rewrite them with custom types by using the same key
```js
const defaultAbaSchemas = {
0: {
recordType: "header",
fields: [
{ name: "type", boundaries: [0, 1], type: "string" },
{ name: "bsb", boundaries: [1, 8], type: "bsb" },
{ name: "account", boundaries: [8, 17], type: "string" },
{ name: "sequenceNumber", boundaries: [18, 20], type: "integer" },
{ name: "bank", boundaries: [20, 23], type: "string" },
{ name: "user", boundaries: [30, 56], type: "string", padding: "left" },
{ name: "userNumber", boundaries: [56, 62], type: "string" },
{ name: "description", boundaries: [62, 74], type: "string", padding: "left" },
{ name: "date", boundaries: [74, 80], type: "string" },
{ name: "time", boundaries: [80, 84], type: "string" },
{ name: "filler", boundaries: [84, 120], type: "string" }, // filler to match 120 char line size
],
},
1: {
recordType: "transaction",
fields: [
{ name: "transactionType", boundaries: [0, 1], type: "string" },
{ name: "bsb", boundaries: [1, 8], type: "bsb" },
{ name: "account", boundaries: [8, 17], type: "string" },
{ name: "tax", boundaries: [17, 18], type: "string" },
{ name: "transactionCode", boundaries: [18, 20], type: "integer" },
{ name: "amount", boundaries: [20, 30], type: "money" },
{ name: "accountTitle", boundaries: [30, 62], type: "string", padding: "left" },
{ name: "reference", boundaries: [62, 80], type: "string", padding: "left" },
{ name: "traceBsb", boundaries: [80, 87], type: "bsb" },
{ name: "traceAccount", boundaries: [87, 96], type: "string" },
{ name: "remitter", boundaries: [96, 112], type: "string", padding: "left" },
{ name: "taxAmount", boundaries: [112, 120], type: "money" },
],
},
7: {
recordType: "footer",
fields: [
{ name: "type", boundaries: [0, 1], type: "string" },
{ name: "bsb", boundaries: [1, 8], type: "bsb" },
{ name: "netTotal", boundaries: [20, 30], type: "money" },
{ name: "creditTotal", boundaries: [30, 40], type: "money" },
{ name: "debitTotal", boundaries: [40, 50], type: "money" },
{ name: "numberOfTransactions", boundaries: [74, 80], type: "integer" },
{ name: "filler", boundaries: [80, 120], type: "string" }, // filler to match 120 char line size
],
},
};
```
In the end your code can look like this
```js
const { ABA } = require("aba-generator");
const aba = new ABA({ header, schemas: { customSchema } });
const batch = aba.generate(transactions);
```
### .generate(transactions)
Transactions schema. Most of the params are required as you can see.
```
* Generate ABA file of these transactions.
* @param transactions {Object[]} Transactions in the file
* @param transactions[].bsb {String} The third party account BSB
* @param [transactions[].tax=" "] {"N"|"W"|"X"|"Y"|" "|""}
* @param transactions[].transactionCode {Number|ABA.CREDIT|ABA.DEBIT|ABA.PAY} Debit or credit? ABA.CREDIT or ABA.DEBIT or ABA.PAY
* @param transactions[].account {String} The third party account number
* @param transactions[].amount {String|Number}
* @param transactions[].accountTitle {String} The third party (recipient) account name. Up to 32 chars.
* @param [transactions[].reference] {String} Payment reference, e.g. "Invoice # 123". Up to 18 chars.
* @param transactions[].traceBsb {String} The transacting account BSB
* @param transactions[].traceAccount {String} The transacting account number
* @param transactions[].remitter {String} The transacting company name.
* @param [transactions[].taxAmount=0] {Number}
* @return {String} The ABA file contents as a string.
```
# TODO
- Input data validation
# Credits
The module is based on this excellent work: https://github.com/ordermentum/aba
Changes: removed all runtime dependencies, added documentation and examples, simplified code infrastructure, fixed few bugs, added features.