A CSV uploaded by a client still needs an explicit account scope, Merchant IDs, period, timezone, currency, output shape, and review result before the application can know what it represents.
The request says:
Please upload the May processor report.
The client opens the processor portal, exports one CSV, and uploads it successfully.
The file contains activity from three Merchant IDs. One location processes CAD while the other two use USD. The export timestamps are in UTC, but the bookkeeping period was planned using the client’s local timezone. Processing fees are combined, while payouts are grouped by location.
The upload control has no reason to reject the file.
It is a valid CSV, it arrived within the size limit, and the transfer completed.
The problem appeared before the upload began: nobody defined what “the May processor report” was supposed to contain.
A manual export is still a system boundary
It is easy to reserve the phrase “integration contract” for APIs, webhooks, and automated data connections.
A client-provided export crosses a similar boundary.
One system produces the report. A person downloads it. Another application receives it. Staff then decide whether the file satisfies a requested item.
The transport is manual, but the receiving application still needs answers to several questions:
- Which processor account produced the report?
- Which Merchant IDs should be included?
- Does the request cover one location, several locations, or an account group?
- What exact start and end dates apply?
- Which timezone defines those dates?
- Which currencies should appear?
- Is the expected output combined or separated?
- Which report type should the client export?
- What file format should staff expect?
Without those fields, the filename becomes responsible for explaining the interface.
settlement-may-final.csv cannot reliably do that.
A conceptual request contract might look like this:
{
"processor_account": "Approved processor account label",
"merchant_ids": ["MID-A", "MID-B"],
"report_type": "payout_detail",
"period": {
"start": "2026-05-01",
"end": "2026-05-31",
"timezone": "UTC"
},
"currencies": ["USD"],
"output_structure": "separate_by_mid",
"expected_format": "CSV"
}
This is not processor configuration.
It is the application recording what the firm expects the client or report holder to provide.
Combined versus separate belongs in the contract
Suppose the client operates three locations under one processor account.
Requesting one combined report may be reasonable when:
- the selected MIDs belong to the same client
- they use the same reporting period
- they use the same timezone
- each MID remains identifiable in the export
- staff needs a group-level view
A combined file becomes harder to review when it mixes currencies, hides one MID, combines unattributable fees, or makes location-level adjustments impossible to identify.
Separate reports may be clearer when:
- the MIDs belong to different entities
- each location is reviewed independently
- currencies differ
- reporting periods differ
- one requested item may need reupload without reopening the others
Neither structure is universally better.
The important part is that the firm chooses the expected shape before the client exports the files.
Otherwise, the review process has to reverse-engineer the intended scope after the upload arrives.
That is not validation. It is reconstruction.
Report type should remain explicit
Processor portals often contain several reports that sound related:
- settlement summary
- payout detail
- transaction-level settlement export
- processing fee report
- refund report
- dispute or chargeback report
- adjustment report
- reserve balance report
- reserve activity report
They may describe overlapping financial activity, but they are not interchangeable requested files.
A settlement summary may describe period-level activity.
Payout detail may describe the composition and timing of individual payouts.
A transaction-level export may provide records beneath those summaries.
A bank statement records what entered or left the bank account.
Calling all four of them processor_report removes the distinction before staff have had a chance to review anything.
For the request layer, I would keep each report type as a separate requested item whenever its scope, period, source, or review action differs.
That allows one item to be accepted while another remains open.
For example:
Settlement summary
Status: Received
Next owner: None
Payout detail
Status: Pending review
Next owner: Staff
Reserve activity report
Status: Waiting on client
Next owner: Client
One successful file does not need to decide the outcome of the entire processor request.
The application should not imply that a connector exists
A structured processor request can look integration-shaped.
It contains account labels, Merchant IDs, date ranges, timezones, currencies, output choices, and report types.
That does not mean the application connects to the processor.
In the payment processor report request checklist I added, those fields define the human handoff. They tell the client what to export and give staff enough context to review the submitted source record.
The request layer is not:
- logging into the processor
- retrieving the export
- mapping Merchant IDs
- splitting currencies
- converting timezones
- calculating reserves
- matching payouts to bank deposits
- reconciling processor and bank activity
That boundary affects the interface language.
A button should say that the client uploaded a report, not that processor data was synchronized.
A review result should say that staff accepted the requested source file, not that the payout was reconciled.
The fields make a manual exchange clearer. They do not turn it into an automated integration.
The return path is part of the contract
The first upload is only one direction of the handoff.
The request also needs a defined response when the file does not match the expected contract.
A report may have:
- the wrong MID
- the wrong date range
- an unexpected timezone
- mixed currencies when separate reports were requested
- a combined output that hides location detail
- the wrong report type
- an unreadable or unsupported file
After upload, the item should first move to:
Status: Pending review
Next owner: Staff
If staff accepts the report:
Status: Received
If the export does not match the requested scope:
Status: Needs reupload
Next owner: Client
The replacement request should explain which part of the contract was not met.
For example:
This export includes MID-A and MID-B, but the request also requires MID-C. Please provide a report covering all three selected Merchant IDs for May 1–31, 2026.
That is more useful than:
Please upload the correct report.
It also prevents the application from reminding the client while the existing file is still waiting for staff review.
Define the manual contract before automating the connector
An API integration can move data faster.
It cannot repair an undefined request.
Before building a processor connector, I would want the manual workflow to answer:
- Which account and Merchant IDs are in scope?
- Which report types are separate requested items?
- Which dates and timezone define the period?
- How should currencies be handled?
- Should the output be combined or separated?
- What evidence allows staff to accept each item?
- What sends the item back for reupload?
Those decisions become the contract an automated integration would eventually need to preserve.
If the human request cannot explain which export is correct, the API parameters will be equally ambiguous.
A successful upload proves that a file crossed the boundary.
A useful processor-report workflow also records what was expected to cross it.
Top comments (0)