In this article
Connect business records, provider objects, and later adjustments without matching on amount alone.
Two payments for the same amount on the same day are not interchangeable. Reconciliation becomes reliable when every relevant record can be traced through a durable chain of identifiers. Build that chain before the first operational report, rather than asking a spreadsheet to infer relationships after an incident.
Distinguish identity from transaction history
Moov’s glossary describes foreignID as an optional unique alias linking an account in your system to a Moov account. That account-level association is useful, but it does not replace the separate identifiers required to explain orders, payment intentions, transfers, events, and adjustments.
Begin with the business record: an order, invoice, booking, or obligation. Associate it with the internal payment intention and the provider transfer reference when available. Preserve account and method references as separate fields. An identifier’s type is part of its meaning; a generic “external ID” column invites accidental joins between unrelated objects.
Expect one-to-many relationships
One order might be paid in more than one legitimate installment. One payment may have multiple later adjustments. One provider object may generate many observations. Your data model should represent those relationships explicitly rather than assuming one order always equals one transfer equals one event.
Use amount, currency, and date as validation attributes, not the only matching key. They help detect discrepancies, but they do not prove identity. Store timestamps with an unambiguous time zone and preserve the distinction between business date, submission time, event time, and ingestion time when those concepts matter to the report.
Fictional worked example: identical amounts
At fictional Spruce Studios, two clients each pay $75 for different appointments. A daily export contains two rows with the same amount. Later, one client receives an authorized $20 adjustment. A reconciliation process based on amount and customer display name can easily attach the adjustment to the wrong booking, especially if a name was edited.
Spruce’s revised design starts with each immutable booking reference, connects the corresponding internal intention and provider transfer, and then links the adjustment to its original payment. The report still shows $75 and $20, but it no longer asks those numbers to serve as identifiers.
The team can now answer three distinct questions: which booking created the obligation, which payment addressed it, and which later action changed the net position. The example is fictional and no export was retrieved. It illustrates why a net total can be correct while individual customer records remain wrong.
Make unmatched records a visible queue
When a provider object cannot be linked confidently, place it in an exception queue with a reason and owner. Do not force a match to make a report balance. A temporary unmatched item with evidence is easier to investigate than a confident but false association that spreads into customer statements and accounting exports.
Classify discrepancies by type: missing internal intent, missing provider reference, amount mismatch, duplicate association, unexplained adjustment, or timing difference. Each category suggests a different investigation. Record what resolved the case so the same underlying problem can be fixed rather than manually rediscovered every reporting period.
Protect traceability during change
A renamed business, merged customer profile, or new reporting system should not destroy the historical chain. Keep immutable identifiers and explicit mapping history. Where a migration changes keys, maintain a reviewed crosswalk and validate totals as well as row-level relationships. Correct totals alone cannot prove that money belongs to the correct participants.
Identifier-chain checklist
- Give each business record and payment intention a durable identifier.
- Store provider references with their object type and environment.
- Represent installments and adjustments as explicit relationships.
- Use amounts and dates to validate, not to guess identity.
- Keep an owned queue for unresolved matches.
- Preserve mappings when names or systems change.
- Check both aggregate totals and individual associations.
Scope of the exercise
This is a data-design and operations framework, not a complete accounting policy or a statement about the fields present in every Moov export. Confirm the current API and reporting schema for your integration. Your finance team should approve the accounting treatment. The goal is to make every reported amount explainable through records that retain their identity when circumstances change.