Payment Reconciliation

Pull payout records from a payment processor and compare them against your internal ledger to surface mismatches, then stage corrections for human approval.

When to use

• You need to confirm that processor payouts (money a payment provider like Stripe or Adyen sends to a bank account) match what your ledger (internal record of transactions) says was collected.
• A finance team member asks for a recurring reconciliation (matching two sets of records) report instead of doing it by hand.
• Mismatches keep slipping through and you need a repeatable diff process with an audit trail.
• You want discrepancies flagged and routed for human review rather than silently adjusted.

Tools

• http-get — read payout batches and transaction records from the payment processor's API and pull the internal ledger export.
• shell-execute — run a diff script that compares processor payouts against ledger entries and produces a mismatch list.
• write-file — save the reconciliation report (matched, unmatched, and disputed items) to a durable location.
• send-message — notify a human teammate that the report is ready or that action is needed.

Playbook

1. Use http-get to fetch the latest payout batches from the processor, e.g. GET https://api.processor.example.com/v1/payouts?since=<date>. Auth is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. On 401/403 or missing Integration, stop and message a human via send-message naming the service and scopes.
2. Use http-get again to pull the matching transaction-level detail for each payout, e.g. GET https://api.processor.example.com/v1/transactions?payout_id=<id>.
3. Use http-get to export the internal ledger records for the same period from the accounting system, e.g. GET https://api.ledger.example.com/v1/entries?period=<range>.
4. Use shell-execute to run a diff script that matches processor transactions to ledger entries by amount, date, and reference ID, and classifies each pair as matched, missing-from-ledger, missing-from-processor, or amount-mismatch.
5. Use write-file to save the full reconciliation report, including the raw diff output and a summary count by category.
6. If the diff reveals a discrepancy that would require a payment, refund, or journal entry to correct, do not execute it. Use create-task titled "APPROVAL: reconcile discrepancy — " so a human can review and authorize the correction.
7. Use send-message to notify the requesting teammate that the report is ready, summarizing counts of matched vs. mismatched items and linking to the saved report.
8. If an update to processor or ledger records is genuinely needed (e.g. marking an item reconciled via PATCH), route through http-request rather than attempting it with http-get, and still stage any money-moving action as an approval task rather than executing it directly.

Failure modes

• Processor API paginates payouts or transactions and only the first page is pulled, understating volume — always follow pagination cursors before running the diff.
• Currency or timezone differences between processor and ledger timestamps cause false mismatches — normalize both to the same currency and date basis before comparing.
• A missing or expired Integration row for either the processor or ledger host silently returns partial data — treat any 401/403 as a hard stop, not a skip.
• Ambiguous partial matches (e.g. two transactions splitting one payout) get miscategorized as full mismatches — flag these separately as "needs manual review" rather than forcing a match or a discrepancy label.

Done when

• A reconciliation report is written via write-file covering every payout and ledger entry in the period, with matched and unmatched items clearly separated.
• Any required correction is staged as an "APPROVAL:" task rather than executed, and a human has been notified via send-message.
• The summary counts (matched, missing, amount-mismatch) are accurate against the raw data pulled in steps 1-3.