Lockbox JSON Specification
Outlines the Lockbox specification for ingestion lockbox payments made outside of PatientPay
Updated at April 22nd, 2025
Table of Contents
Lockbox payments are typically made to a third-party service via physical check. It is important that PatientPay and the system of record be kept in sync with lockbox payments to ensure the patient's bill balance is accurate. We provide an Lockbox JSON Specification to allow partners to send us a smaller update file that includes transactions made outside of PatientPay.
Drop Folder for Lockbox JSON
Lockbox update files should be dropped in the same incoming SFTP folder as the statement files.
The following outlines the specifications and minimum required fields for a Lockbox statement ingestion via JSON file and SFTP.
| Object | Field | Required | Data Type | Description |
| schema | Y | string (13) | Identifies this as a payment update file; hard-coded to "ppay-payment-updates" | |
| version | Y | string (5) | Identifies the version of the payment update file; hard-coded to current schema version of "1.0.0" | |
| statements | The statements array contains one or more statement objects separated by comma | |||
| statement | A statement object is a nested object that contains fields and nested objects pertaining to the statement or bill | |||
| statementId | Y | string (32) | This unique statementId should match an existing statementId for which bill that is being updated | |
| clientId | Y | string (10) | Unique identifier for the organization for which bill belongs to that is being updated. NOTE: Case sensitive. | |
| partnerTransactionsOnly | Y | boolean | This flag indicates whether to process the partnerTransactions array as an update instead of validating as a complete statement; it should always be true for payment updates | |
| statement.patients | The patients array contains one or more patient objects separated by the comma | |||
| patient | The patient object is a nested object that contains fields pertaining to the patient record | |||
| accountId | Y | string (55) | Uniquely identified the patient account ID for which you are updating a bill | |
| statement.partnerTransactions | The partnerTransactions array contains one or more transactions that are added/subtracted from the bill | |||
| transactionId | N | string (55) | A unique identifier for each transaction | |
| transactionDate | Y | date | The date of the transaction in the format YYYY-MM-DD. | |
| transactionAmt | Y | Amount of transaction to be recorded in system. The amount should be negative if deducting from the bill and positive if adding to the bill. Transaction amount cannot be greater than bill amount. | ||
| transactionDesc | N | string | Description for the transaction | |
| payerId | N | string (10) | Identifies the payer from the payer table, if applicable. Pass null if not providing a value | |
| transactionType | N | string | Specifies the type of transaction (“SALE” or “DEBIT”); default is “DEBIT” if not provided | |
| transactionPaymentMethodType | Y | string | Specifies payment method (“CARD” or “CHECK”); Use "CHECK" for lockbox payment | |
| transactionSource | N | string | Specifies the source of the payment. Use "LOCKBOX" for lockbox payment | |
Example Lockbox JSON:
{
"schema": "ppay-payment-updates",
"version": "1.0.0",
"statements": [
{
"statementId": "TST108531",
"partnerTransactionsOnly": true,
"clientId": "TST",
"patients": [
{
"accountId": "TB135H"
}
],
"partnerTransactions": [
{
"transactionId": "314001717607",
"transactionDate": "2021-10-24",
"transactionAmt": "-40.00",
"transactionDesc": "Check # 3004",
"payerId": null,
"transactionType": "DEBIT",
"transactionPaymentMethodType": "CHECK",
"transactionSource": "LOCKBOX"
}
]
}
]
}