DEV Community: Jack Ma

Designing an RCTI Workflow: Validation, Money, Snapshots, and PDFs

Jack Ma — Fri, 28 Aug 2026 13:48:11 +0000

An invoice form looks simple until the software has to preserve what was true when the document was issued.

That problem is especially visible with an Australian recipient-created tax invoice (RCTI). Unlike an ordinary supplier invoice, an RCTI is issued by the recipient of the supply. The workflow also depends on conditions outside the PDF itself, including the parties' GST status and an appropriate agreement.

The Australian Taxation Office explains that an RCTI must make its purpose clear, identify the relevant parties, and state that GST shown is payable by the supplier. Its guidance also describes written-agreement and record-retention requirements. See the ATO's GSTR 2000/10 guidance and RCTI reference form before implementing a production workflow.

This article is about the software architecture behind that workflow. It is not tax or legal advice, and generating a structurally complete PDF does not establish that a business is entitled to issue an RCTI.

Start with a workflow, not a PDF template

A weak implementation models an RCTI as a collection of text boxes followed by a Download PDF button:

Form input -> HTML template -> PDF

A more useful model treats generation as a state transition:

Draft
  -> validate parties
  -> validate commercial inputs
  -> calculate totals
  -> confirm agreement context
  -> render document
  -> store immutable snapshot
  -> allow owner-authorised download

This distinction matters because a saved business profile is mutable, while an issued document is historical evidence. If a supplier changes its trading name or address next month, last month's invoice should not silently change with it.

1. Keep legal entity data separate from display data

Business software often overloads one businessName field. In practice, a user may recognise a supplier by a trading name while the document also needs the correct legal entity and ABN.

A party model can keep those concepts explicit:

type PartyInput = {
  entityName: string;
  businessName: string;
  abn: string;
  address: string;
};

type PartySnapshot = {
  entityName: string;
  businessName: string;
  abn: string;
  address: string;
};

Do not use an ABN lookup response as an automatic compliance decision. A lookup can help the user detect a mistyped number or retrieve an entity name, but the application still needs to distinguish several outcomes:

type AbnLookupResult =
  | { status: "found"; entityName: string; businessNames: string[] }
  | { status: "inactive" }
  | { status: "not_found" }
  | { status: "unavailable" };

These states should produce different messages:

inactive: explain that the ABN is not currently active and ask the user to verify the party.
not_found: ask the user to check all 11 digits.
unavailable: allow manual entry where appropriate and explain that verification could not be completed.

Treating all three as “Invalid ABN” is inaccurate and gives the user no recovery path.

The ATO's own GST data-testing guidance treats ABN and GST-registration checks as meaningful controls for RCTIs, rather than mere formatting concerns. That is a good reason to make verification status visible in the domain model instead of burying it inside an input component.

2. Represent money in minor units

JavaScript floating-point arithmetic is a poor storage model for financial totals:

0.1 + 0.2; // 0.30000000000000004

Store committed amounts as integer cents. If the interface accepts decimal dollars, parse once at the boundary and calculate with integers afterward.

type LineItem = {
  description: string;
  quantity: number;
  unitPriceCents: number;
  discountBasisPoints: number;
  gstApplicable: boolean;
};

type CalculatedLine = LineItem & {
  netCents: number;
  gstCents: number;
  totalCents: number;
};

function calculateLine(item: LineItem): CalculatedLine {
  const grossCents = Math.round(item.quantity * item.unitPriceCents);
  const discountCents = Math.round(
    (grossCents * item.discountBasisPoints) / 10_000,
  );
  const netCents = grossCents - discountCents;
  const gstCents = item.gstApplicable ? Math.round(netCents / 10) : 0;

  return {
    ...item,
    netCents,
    gstCents,
    totalCents: netCents + gstCents,
  };
}

There are two design decisions worth making explicit:

Rounding boundary: decide whether GST is rounded per line or after aggregation, then use the same rule in the UI, API, stored record, and PDF.
GST applicability: do not infer it solely from the existence of an ABN. ABN status, GST registration, the nature of the supply, and the parties' circumstances are separate facts.

The example above demonstrates arithmetic, not a universal tax determination.

3. Separate validation into layers

A single schema cannot answer every question. Split validation according to what the system can actually know.

Shape validation

This is deterministic and belongs at the input boundary:

import { z } from "zod";

const partySchema = z.object({
  entityName: z.string().trim().min(1),
  businessName: z.string().trim().min(1),
  abn: z
    .string()
    .transform((value) => value.replace(/\s/g, ""))
    .pipe(z.string().regex(/^\d{11}$/)),
  address: z.string().trim().min(1),
});

External verification

This includes ABN lookup and service availability. It can time out, so it should return a recoverable state rather than pretending to be synchronous schema validation.

Workflow validation

This answers questions such as:

Is there at least one supply line?
Is the issue date sensible?
Is the invoice number unique under this business's numbering policy?
Has the user confirmed the agreement context?
Are the parties being used in the correct recipient/supplier roles?

Eligibility confirmation

Some conditions cannot be proven by form fields. The software can request an acknowledgement, show the relevant rules, and preserve the acknowledgement, but it should not claim to have replaced professional judgement or the user's legal obligations.

4. Freeze an immutable issuance snapshot

Do not generate document history by joining an old invoice to the current party table.

Consider this schema:

type IssuedDocument = {
  id: string;
  userId: string;
  kind: "rcti" | "agreement";
  issueDate: string;
  documentNumber: string | null;
  recipientSnapshot: PartySnapshot;
  supplierSnapshot: PartySnapshot;
  lineItemsSnapshot: CalculatedLine[];
  totalAmountCents: number;
  pdfObjectKey: string;
  createdAt: string;
};

The recipientSnapshot, supplierSnapshot, and lineItemsSnapshot fields capture the issued state. Foreign keys to saved parties can still be useful for filtering or convenience, but they should not be the only historical source.

This gives the system two different truths:

Profile truth: the latest reusable details for future documents.
Document truth: the details used for one past issuance.

That distinction also makes corrections safer. Instead of editing history in place, create a replacement or adjustment workflow and retain the relationship between records.

5. Make PDF storage and database writes behave like one operation

Object storage and a relational database usually cannot share a transaction. A common failure mode looks like this:

Upload PDF successfully.
Fail to insert the database record.
Leave an orphaned private file forever.

A compensating action handles the partial failure:

async function storeIssuedDocument(input: CreateDocumentInput) {
  const id = crypto.randomUUID();
  const key = `documents/${input.userId}/${id}.pdf`;

  await objectStorage.put(key, input.pdfBytes, {
    contentType: "application/pdf",
  });

  try {
    await database.transaction(async (tx) => {
      await assertDocumentLimit(tx, input.userId);
      await tx.insertIssuedDocument({
        id,
        ...input.snapshot,
        pdfObjectKey: key,
      });
    });
  } catch (error) {
    await objectStorage.delete(key).catch(() => undefined);
    throw error;
  }
}

If usage limits or permissions are involved, check before the upload for fast feedback and check again inside the transaction to prevent a race between concurrent requests.

6. Authorise the download, not just the page

Hiding another user's document in the UI is not access control. The download endpoint must include ownership in the query:

async function getDocumentForDownload(userId: string, documentId: string) {
  const document = await db.query.issuedDocuments.findFirst({
    where: and(
      eq(issuedDocuments.id, documentId),
      eq(issuedDocuments.userId, userId),
    ),
  });

  if (!document) return null;
  return objectStorage.get(document.pdfObjectKey);
}

For administrative access, use a separate route that checks an explicit permission before loading the record. Do not weaken the user-scoped function with an optional isAdmin flag.

Other useful controls include:

private object storage rather than guessable public URLs;
a safe Content-Disposition filename;
an audit event for administrative downloads;
rate limits appropriate to the account and endpoint;
generic not-found responses that do not reveal whether another user's document exists.

7. Prefer warnings over arbitrary blocking

Some suspicious situations are not necessarily invalid. Two RCTIs for the same supplier on the same day may be a duplicate, or they may represent two legitimate supplies.

An advisory duplicate check is often better than a hard uniqueness constraint:

const possibleDuplicate = await hasInvoice({
  userId,
  supplierId,
  issueDate,
});

if (possibleDuplicate) {
  return {
    requiresConfirmation: true,
    message: "An RCTI already exists for this supplier on this date.",
  };
}

Block only when the system knows the operation is disallowed. Warn when the system has detected risk but lacks enough context to decide.

A practical pre-issuance checklist

Before enabling the final PDF action, verify that the workflow has addressed:

recipient and supplier roles are unambiguous;
legal entity names, business names, ABNs, and addresses are separate fields;
external lookup failure is distinguishable from a negative result;
GST calculations use one documented rounding policy;
line items and totals are recalculated server-side or otherwise integrity-checked;
agreement context is captured before issuance;
the generated document is clearly identified as an RCTI;
issued party and line-item data are stored as immutable snapshots;
partial object-storage failures are cleaned up;
downloads are scoped to the authenticated owner;
administrative access uses an explicit permission path;
corrections preserve rather than rewrite history.

Where this architecture is used

I applied these patterns while building RCTI Generator, a web application for preparing Australian RCTI invoices and RCTI agreements. The application includes ABN-assisted party entry, optional GST calculations, PDF generation, saved business/payee profiles, immutable document history, and owner-scoped downloads.

The tool helps structure and retain the information, but users remain responsible for confirming that their arrangement and supplies satisfy the current ATO requirements.

Closing thought

The hardest part of document software is rarely drawing the document. It is preserving the relationship between user input, external facts, calculation rules, authorisation, and historical state.

If the architecture treats the PDF as the last output of a controlled workflow—not the workflow itself—the product becomes easier to audit, safer to extend, and less likely to rewrite history accidentally.

Disclosure: I am involved in building RCTI Generator, the product mentioned in this article.

AI assistance disclosure: AI tools assisted with outlining, drafting, and editing. The implementation details and cited sources were reviewed against the project code and official ATO materials before publication.

How to Convert CSV or Excel to a NACHA ACH File — and Validate It Before Upload

Jack Ma — Tue, 25 Aug 2026 13:16:14 +0000

A CSV file is easy to inspect. A NACHA ACH file is not.

At first glance, an ACH file looks like a collection of arbitrary numbers and padded text. In reality, it is a fixed-width format with strict rules for record length, ordering, totals, routing numbers, and padding.

That means “converting CSV to ACH” is not simply changing a file extension. You are building a structured payment instruction that must agree with your bank’s origination requirements.

This guide covers three practical approaches:

Exporting an ACH file from payroll or accounting software
Generating one programmatically
Using a browser-based converter and validator

It also includes a small JavaScript validator you can use to catch structural errors before submitting a file to a bank.

What is inside a NACHA file?

According to the Nacha ACH developer guide, every record in a standard ACH file is exactly 94 characters long.

The first character identifies the record type:

Code	Record
`1`	File Header
`5`	Batch Header
`6`	Entry Detail
`7`	Addenda
`8`	Batch Control
`9`	File Control or padding

A minimal file normally follows this shape:

1 — File Header
5 — Batch Header
6 — Entry Detail
6 — Entry Detail
8 — Batch Control
9 — File Control
9 — Optional padding records

An ACH file can contain multiple batches. Each batch can contain multiple entries, and some entries may have addenda records.

The file is normally padded so its total record count is a multiple of 10. Padding records contain 94 number-nine characters.

Before converting the spreadsheet

A source spreadsheet should use explicit columns rather than relying on visual formatting.

For example:

routing_number,account_number,account_type,amount,name,identification
021000021,123456789,checking,1250.00,Example Employee,EMP-1001
026009593,987654321,savings,875.50,Example Contractor,CTR-2042

Before generating the ACH file, check:

Routing numbers contain exactly nine digits.
Account numbers are treated as text, not numbers.
Leading zeroes have not been removed by Excel.
Amounts have no currency symbols or thousands separators.
Debit and credit intent is explicit.
Each payment has a stable internal identifier.
Consumer and corporate entries are not accidentally mixed.
The effective date agrees with your bank’s processing rules.

Do not infer the account type from the account number. Your input needs to specify checking or savings explicitly.

Method 1: Export from payroll or accounting software

If your payroll, ERP, treasury, or accounting system already supports your bank’s ACH format, use that export first.

Typical workflow:

Import or enter the payment instructions.
Select the correct bank account and payment type.
Choose the ACH or NACHA export option.
Confirm the effective date and batch description.
Export the file.
Validate the exported file before uploading it to the bank.

Advantages

Usually incorporates your company and bank configuration
Can integrate approval and payment workflows
Avoids maintaining custom payment-generation code

Limitations

Export formats may be bank-specific
Configuration mistakes can still create invalid files
Some systems hide control totals and record-level details
Moving between banks may require a new export profile

Even files created by established payroll software should be validated. A structurally valid file can still contain the wrong company ID, origin routing number, SEC code, or effective date.

Method 2: Generate the ACH file programmatically

Programmatic generation is useful when payments originate in your own application.

The important part is to treat every field as a fixed-width value.

For example:

function alpha(value, length) {
  return String(value)
    .toUpperCase()
    .slice(0, length)
    .padEnd(length, " ");
}

function numeric(value, length) {
  const digits = String(value).replace(/\D/g, "");
  if (digits.length > length) {
    throw new Error(`Numeric value exceeds ${length} characters`);
  }
  return digits.padStart(length, "0");
}

function cents(value) {
  const amount = Math.round(Number(value) * 100);

  if (!Number.isSafeInteger(amount) || amount < 0) {
    throw new Error("Invalid payment amount");
  }

  return numeric(amount, 10);
}

These helpers reflect two central formatting rules:

Alphanumeric fields are generally left-justified and space-padded.
Numeric fields are right-justified and zero-padded.

Do not build amounts with floating-point string manipulation such as:

String(amount * 100);

Round deliberately and verify that the result is a safe non-negative integer.

Validate routing-number checksums

A nine-digit ABA routing number includes a checksum.

function isValidRoutingNumber(value) {
  if (!/^\d{9}$/.test(value)) return false;

  const digits = [...value].map(Number);

  const checksum =
    3 * (digits[0] + digits[3] + digits[6]) +
    7 * (digits[1] + digits[4] + digits[7]) +
    (digits[2] + digits[5] + digits[8]);

  return checksum % 10 === 0;
}

A valid checksum does not prove that the routing number is active or eligible for ACH. It only detects many common transcription errors.

Validate record length by bytes

JavaScript string length and file byte length are not always the same.

ACH records are fixed-width ASCII records, so validate encoded bytes:

function validateRecordLengths(contents) {
  const lines = contents
    .replace(/\r\n/g, "\n")
    .replace(/\r/g, "\n")
    .split("\n");

  if (lines.at(-1) === "") lines.pop();

  return lines.flatMap((line, index) => {
    const bytes = new TextEncoder().encode(line).length;

    return bytes === 94
      ? []
      : [`Record ${index + 1} contains ${bytes} bytes instead of 94`];
  });
}

This catches problems caused by:

Truncated fields
Extra delimiters
Smart quotes
Emoji
Multi-byte characters
Accidental spaces at the end of a record
Incorrect line construction

A practical structural validator

The following validator does not replace full NACHA validation, but it catches several useful structural problems:

function validateAchStructure(contents) {
  const lines = contents
    .replace(/\r\n/g, "\n")
    .replace(/\r/g, "\n")
    .split("\n")
    .filter((line, index, all) => line || index < all.length - 1);

  const errors = [];

  lines.forEach((line, index) => {
    const recordNumber = index + 1;
    const byteLength = new TextEncoder().encode(line).length;

    if (byteLength !== 94) {
      errors.push(
        `Record ${recordNumber}: expected 94 bytes, found ${byteLength}`
      );
    }

    if (!/^[156789]/.test(line)) {
      errors.push(
        `Record ${recordNumber}: unknown record type ${JSON.stringify(line[0])}`
      );
    }
  });

  if (!lines[0]?.startsWith("1")) {
    errors.push("The first record must be a File Header record");
  }

  const logicalRecords = lines.filter((line) => line !== "9".repeat(94));

  if (!logicalRecords.at(-1)?.startsWith("9")) {
    errors.push("The last logical record must be a File Control record");
  }

  if (lines.length % 10 !== 0) {
    errors.push("The total record count is not a multiple of 10");
  }

  return errors;
}

A production validator should go further and recalculate:

Batch count
Block count
Entry and addenda count
Entry hash
Total debit amount
Total credit amount
Batch numbers
Trace-number ordering
Addenda indicators
Service-class consistency

It should also distinguish the File Control record from padding records. Both begin with 9, but padding records consist entirely of nines.

Method 3: Use a browser-based converter and validator

A browser-based tool can be useful when:

The source data is already in CSV or Excel.
You do not want to install finance software.
You need to inspect the generated records.
You want a quick structural validation before bank upload.

I am building ACH File Converter for this workflow. It includes CSV/Excel conversion, viewing, editing, control-total calculation, and ACH validation.

The important step is not just generating the file. Review the result before submitting it:

Confirm the origin and destination values.
Check the company identification.
Verify the SEC and service-class codes.
Compare the entry count with the spreadsheet.
Compare debit and credit totals.
Confirm the effective date.
Validate the routing numbers.
Keep a copy of the source data and generated file.
Follow your bank’s approval and test-file process.

Your bank may require values that cannot be inferred from a spreadsheet, including an assigned company ID, immediate-origin value, file modifier policy, or offset-account entry.

Balanced and unbalanced files

One frequent source of confusion is whether the file needs an offset entry.

A balanced file includes an offset entry that balances the debit and credit totals inside the file.

An unbalanced file does not include that offset. The bank applies settlement outside the submitted file.

Neither choice is universally correct. It depends on your ODFI’s requirements.

Do not automatically add an offset entry because the totals look unbalanced. Ask the bank which format it expects and which account information should be used.

Common reasons banks reject ACH files

The most common failures are often small formatting or configuration mistakes:

A record contains 93 or 95 characters instead of 94.
Excel removed a leading zero from a routing or account number.
The routing-number checksum is invalid.
Batch and file control totals do not match the entries.
The file contains unsupported characters.
The block count or padding is wrong.
A batch header and control record use different batch numbers.
The wrong SEC code was selected.
The effective date is invalid or outside the bank’s accepted window.
A company ID or immediate-origin value does not match the bank profile.
A balanced file was submitted where the bank expects an unbalanced file, or vice versa.

A validator can detect structural errors, but only the bank can confirm customer-specific origination settings.

Final checklist

Before uploading a production ACH file:

Validate all 94-byte records.
Recalculate control totals from the entries.
Confirm the routing-number checksums.
Confirm the number of spreadsheet rows against ACH entries.
Check the effective date and file modifier.
Confirm balanced versus unbalanced requirements.
Remove unexpected multi-byte characters.
Test with non-production payment data first.
Follow dual-control and approval procedures.
Never send real account data through screenshots, public issue trackers, or chat messages.

Generating the file is only one part of the workflow. The safer approach is:

structured input
→ explicit field mapping
→ ACH generation
→ independent validation
→ human review
→ bank upload

That extra validation step is much cheaper than investigating a rejected or incorrectly configured payment batch.

Disclosure: I am the builder of ACH File Converter, the tool mentioned in this article.

AI assistance disclosure: AI was used to help edit and structure this article. The technical content and examples were reviewed by the author.