Lockbox

Opening a lockbox

POST /lockboxes takes the account_id that receives the deposits, a number of at most seven characters, a name and an optional address. A number already in use answers 409 conflict. The lockbox (lkbx_) has a status of open or closed, and a closed one takes no remittances.

Recording a remittance

POST /lockboxes/{id}/remittances takes an Idempotency-Key and the day's mail in one of two forms.

• JSON: batches, each with items. An item has an amount in minor units, the check's micr line, a remitter, a list of invoices (each a number and an amount) and optional front_image and back_image.
• Text: a transmission in the bank's remittance layout, sent with Content-Type: text/plain. It must name the same lockbox number, and its batch and file totals must agree with its items.

The whole request is checked before anything posts. It needs 1 to 999 batches, numbered uniquely, with 1 to 999 items each. A remitter is at most 14 characters, an invoice number at most 10, and the account and serial read from the MICR line at most 10 each, because those are the widths of the file. A request that breaks a limit answers validation_failed.

How the checks post

Each item becomes a check deposit on the lockbox's account with channel lockbox and the remittance's id in lockbox_remittance_id. It posts and is collected like any other deposit: a debit to GL 1050 and a credit to the account, under Reg CC holds, then into the next forward cash letter.

• Every item takes the remittance's business date, and the Reg CC schedule counts the items of one remittance together.
• The account's description is screened as the payee and the remitter as the drawer. An item that is not clear is credited to the transit account until it is reviewed.
• An item another deposit is still collecting, or the same check twice in one remittance, refuses the whole remittance with payments.duplicate_item before anything posts.
• If a remittance is interrupted part way, send it again with the same key. The checks already posted are found, not posted again, and the rest are processed.

The answer is a lockbox remittance (lkrm_) with status posted, its batch_count, item_count and total_amount, and its items. Each item names its check_deposit_id. The remittance publishes payments.lockbox_remittance.posted, and each check publishes payments.check_deposit.deposited.

Invoices and the remittance file

The bank does not match invoices against anything. It records the invoice numbers and amounts given with each check, exactly as sent, and does not compare their sum with the check. Applying the cash to open invoices is the work of the customer's receivables system.

For that system, GET /lockbox-remittances/{id}/content returns the remittance as text in the bank's BAI lockbox layout: 80-character records for the file header (1), service (2), batch header (5), one detail record per check with its first invoice (6), overflow records with up to three more invoices each (4), the batch total (7), the lockbox total (8) and the trailer (9). When the remittance arrived as text, the same text is returned.

The objects are Lockbox and Lockbox Remittance.