Skip to main content

​
Overview

A bank lockbox collects mailed check payments on an organization’s behalf and sends back a data file listing what it received. The Lockbox for fusionCore accelerator imports that file, matches each line to an existing Order or installment by Order number or installment number, and applies the payment automatically — so your team doesn’t have to hand-key or manually reconcile a batch of check payments. It supports both CSV and fixed-width text file formats, both fully configurable to match your bank’s exact layout. This accelerator is layered on top of core fusionCore Commerce and is an optional add-on, not part of the base install.

​
Prerequisites

  • fusionCore Commerce installed, with your Business Units already configured.
  • Know your bank’s exact file layout (CSV column order, or fixed-width column positions) — you’ll need this to configure the file mapping.

​
How to Configure

Installing the package automatically creates a Lockbox payment type and matching GL Account for every Business Unit that doesn’t already have one — you don’t create these by hand.
1

Confirm the Lockbox payment type

Check that a Lockbox payment type now exists on each Business Unit that should accept lockbox payments. If your org needs a different name, change it in the FS_Lockbox_Setting__mdt settings.
2

Map your bank's file layout

Configure FS_Lockbox_Field_Mapping__mdt records to match your bank’s exact file format — one record per column (CSV) or fixed position (text file), pointing to the matching field on the imported payment line (Order number, installment number, amount, payment date, and so on).
3

Upload, validate, and apply a file

On a Payment Request Header record: click Upload and select the bank’s file, click Validate to check every line against fusionCore’s Orders and installments, then click Apply Payment once validation passes. Both validation and applying run in the background — watch the header’s status rather than expecting an instant result.
4

Resolve errors and re-run

Any line that fails validation or application shows its error on the payment line. Fix the underlying data (in fusionCore or in a corrected file) and re-run — applying only retries the lines that previously failed.

​
Limitations and Common Pitfalls

  • Uploading a file replaces everything already staged for that batch. Re-uploading a file deletes and rebuilds every payment line under that Payment Request Header — don’t re-upload after you’ve already applied some of the payments, or you’ll lose that progress.
  • Amounts must match exactly — there’s no partial or overpayment support. A payment line’s amount must exactly equal the installment’s total or the Order’s balance due, or that line fails validation. Short and over payments are both rejected, not partially applied.
  • CSV files are split on plain commas. A customer name or other value containing a comma will shift every column after it. If your data commonly includes commas, use the fixed-width text format instead.
  • The first row of a CSV file is always treated as a header and skipped — fixed-width text files don’t have this skip, every line is parsed.
  • A line needs an Order number or installment number, plus a payment date, or it’s rejected outright. Confirm your bank’s file (or your field mapping) actually includes these.
  • Currency must match between the payment line and the Order. A mismatch fails that line, which matters for organizations running multiple currencies.
  • Orders that are already paid, written off, or voided reject the payment.
  • “Apply Manually” is a status flag, not an actual payment. Marking a line as applied manually records that someone handled it outside the system — it does not create a Financial Event or move money. Use it only as a bookkeeping note for payments you’ve already applied another way.