Aba-parser NPM

ABA parser

NPM module to parse ABA (Australian Bankers Association) files

How to use

Install

npm i aba-parser

Usage

const { ABA } = require("aba-parser");

const aba = new ABA();
const batches = aba.parse(abaString);
for (const { header, transactions, footer } of batches) {
  console.log(...transactions);
}

Options

Validation

Attention! Batch validation depends significantly on the default ABA structure; in order for it to function, you must specify a minimum structure, as seen in the example below.

const minimalBatchForValidation = {
  header: { ...otherFields },
  transaction: [{ amount: number, transactionCode: number, ...otherFields }],
  footer: {
    bsb: string, // must be 999999
    netTotal: number,
    creditTotal: number,
    debitTotal: number,
    numberOfTransactions: number,
    ...otherFileds,
  },
};

If you want to throw an error on an invalid batch, you need to pass options options: {validation: true} into the ABA constructor for automatic batch validation.

Otherwise, you can use the manual validation method aba.validateBatch(batch) see examples below

Automatic batch validation

import { ABA } from "aba-parser";

const aba = new ABA({ validation: boolean });

try {
  const batches = aba.parse(invaidAbaString);
} catch (error) {
  console.log(error);
}

Manual batch validation

You can validate batches manually without throwing an error, see the example below.

const aba = new ABA();
const batches = aba.parse(sourceFile);
for (const batch of batches) {
  const { success, code, message } = aba.validateBatch(batch);
}

Custom transaction parsing

You can add multiple custom schemas or replace default schemas to parse 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 original ABA record, for default schemas ("0" - Descriptive Record (header), "1" - Detail Record (transaction), and "7" - File Total Record (footer))

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.

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

customSchemas = {
  N: {
    recordType: "header" | "transaction" | "footer",
    fields: [
      {
        name: "string",
        boundaries: [number, number],
        type: "string" | "money" | "integer" | "bsb" | "",
      },
    ],
  },
};

const aba = new ABA({ schemas: customSchmas });

Custom schema use example

const customSchemas: RecordSchema = {
  "5": {
    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: "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: "bsb", boundaries: [1, 8], type: "bsb" },
      { name: "account", boundaries: [8, 17], type: "string" },
    ],
  },
};

const aba = new ABA({ schemas: customSchemas });

const batches = aba.parse(abaString);
for (const { header, transactions, footer } of batches) {
  console.log(...transactions);
}

Default schemas

Here the list of standard schemas, you can rewrite them with custom types by using the same key

const defaultAbaSchemas = {
  0: {
    recordType: "header",
    fields: [
      { name: "bsb", boundaries: [1, 8], type: "bsb" },
      { name: "account", boundaries: [8, 17], type: "string" },
      { name: "sequenceNumber", boundaries: [19, 20], type: "integer" },
      { name: "bank", boundaries: [20, 23], type: "string" },
      { name: "user", boundaries: [30, 56], type: "string" },
      { name: "userNumber", boundaries: [56, 62], type: "string" },
      { name: "description", boundaries: [62, 74], type: "string" },
      { name: "date", boundaries: [74, 80], type: "string" },
      { name: "time", boundaries: [80, 84], type: "string" },
    ],
  },

  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" },
      { name: "reference", boundaries: [62, 80], type: "string" },
      { name: "traceBsb", boundaries: [80, 87], type: "bsb" },
      { name: "traceAccount", boundaries: [87, 96], type: "string" },
      { name: "remitter", boundaries: [96, 112], type: "string" },
      { name: "taxAmount", boundaries: [112, 120], type: "money" },
    ],
  },

  7: {
    recordType: "footer",
    fields: [
      { 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" },
    ],
  },
};

In the end your code can look like this

const { ABA } = require("aba-parser");
const options = {
  validation: boolean,
  schemas: { customSchema, customSchema },
};
const aba = new ABA(options);
const batches = aba.parse(abaString);
for (const { header, transactions, footer } of batches) {
  console.log(...transactions);
}

Reference information and links

Sibling modules

aba-generator - if you need to generate an ABA string, you can use this module.

ABA file specification

Standard transactions codes for ABA files

Shortcuts that are used in ABA files and what they mean

Codes for tax in debit/credit transactions

Must be a space or the letter 'N', 'T', 'W', 'X', or 'Y'.

'N' - for new or varied BSB number or name details. 'T' - for a drawing under a Transaction Negotiation Authority.

Withholding Tax Indicators: 'W' - dividend paid to a resident of a country where a double tax agreement is in force. 'X' - dividend paid to a resident of any other country. 'Y' - interest paid to all non-residents.

Where applicable, the amount of withholding tax is to appear in character positions 113-120. Note: Accounts of non-residents. Where withholding tax has been deducted, the appropriate Indicator as shown above, is to be used and will override the normal Indicator."