> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Lockbox for fusionCore

> Import a bank lockbox file and automatically apply the payments it lists to matching fusionCore Orders and installments.

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.