Reconciliation
Reconciliation compares your internal transaction records and settlements with external payment provider reports to detect discrepancies before they become financial losses or disputes.
Why Reconciliation Matters
As a payment platform operator, you process transactions through external providers (acquirers, banks, payout services). Each provider maintains their own records. Discrepancies between your records and theirs can result in:
- Undetected financial losses
- Incorrect merchant settlements
- Negative margin on transactions
- Disputes with providers or merchants
Regular reconciliation catches these issues early and keeps your financial data trustworthy.
Types of Reconciliation
Transaction-Level Reconciliation
Compares individual transactions between Miracle and the payment provider.
What is matched:
- Transaction reference / provider reference
- Transaction status
- Amount and currency
- Fee amounts
Common discrepancies at this level:
- Transaction exists at the provider but not in Miracle (missing capture notification)
- Transaction exists in Miracle but not at the provider (failed to reach provider)
- Status mismatch (e.g., Miracle shows
succeeded, provider showsdeclined) - Amount mismatch (partial captures, FX differences)
- Duplicate transactions
Settlement-Level Reconciliation
Compares aggregated settlement reports from providers against Miracle's internal settlement records.
What is matched:
- Total volume for the period
- Total fees charged by the provider
- Net settlement amount
- Number of transactions
Common discrepancies at this level:
- Missing settlement (provider settled but Miracle has no matching record)
- Total amount mismatch
- Fee mismatch (provider fees differ from configured rates)
- Timing differences (provider and Miracle use different cutoff times)
Exception-Based Workflow
Rather than reviewing every transaction manually, the system focuses on outliers and discrepancies.
- Matched transactions are marked as reconciled automatically.
- Unmatched or mismatched items are surfaced as exceptions.
- Operators review and resolve exceptions individually.
Provider Settlement Reconciliation
Provider settlements represent the movement of funds from the acquirer or terminal to your tenant's FundingAccount.
In the Portal:
- Navigate to Provider Settlements.
- View incoming settlement records from each provider.
- Compare against Miracle's internal transaction data for the same period.
- Review any flagged discrepancies.
What to check:
- Does the provider's total match your expected gross volume for that terminal?
- Are provider fees consistent with your contracted rates?
- Is the net settlement amount correct after fees?
Reconciliation Workflow
Step 1: Import Provider Data
Provider settlement reports are imported into the system. This can happen via:
- Automated file import (CSV, XML from provider SFTP)
- Manual upload through the Portal
- API-based data pull (where supported by the provider)
Step 2: Automatic Matching
The system attempts to match provider records against internal transactions using:
- Provider transaction reference
- Amount and currency
- Transaction date
Successfully matched items are marked as reconciled.
Step 3: Review Exceptions
Unmatched items appear in the exceptions queue. For each exception:
- Identify the type of discrepancy (missing, status mismatch, amount mismatch).
- Investigate the root cause (timing, FX, provider error, internal bug).
- Resolve: mark as explained, create an adjustment, or escalate.
Step 4: Adjustments
When a discrepancy requires a financial correction:
- Adjustments are created through a controlled process with a mandatory reason.
- Each adjustment creates an auditable ledger entry.
- The system never auto-corrects ledger entries from reconciliation. All corrections require explicit operator action.
Reconciliation detects discrepancies. It does NOT automatically modify balances or recalculate fees. Any correction goes through a controlled adjustment process with full audit trail.
Common Discrepancy Types
| Discrepancy | Cause | Resolution |
|---|---|---|
| Missing transaction (provider has it, Miracle does not) | Missed webhook, notification failure | Investigate and create missing record or adjustment |
| Missing transaction (Miracle has it, provider does not) | Transaction failed to reach provider | Verify transaction status, update if needed |
| Status mismatch | Delayed status update, webhook out of order | Fetch latest status from provider, reconcile |
| Amount mismatch | Partial capture, FX conversion difference | Verify amounts, create adjustment if needed |
| Fee mismatch | Provider rate change, incorrect fee configuration | Compare contracted rates, update fee schedule |
| Timing difference | Different settlement cutoff times | Align date ranges using provider's cutoff time |
| Duplicate transaction | Retry without idempotency, double processing | Identify and flag the duplicate |
Best Practices
- Reconcile regularly. Run reconciliation daily or per settlement cycle. Do not let discrepancies accumulate.
- Investigate promptly. The longer a discrepancy sits unresolved, the harder it is to trace the root cause.
- Keep provider reports. Store all provider settlement reports for audit trail and historical reference.
- Monitor margins. Use reconciliation to detect negative margin cases where provider fees exceed what was charged to the merchant.
- Review fee configurations. When fee mismatches appear repeatedly, verify that your configured rates match your provider contracts.
- Use cutoff times correctly. Each provider may have a different banking day boundary. The provider's cutoff time is stored on the ProviderIntegration record.
Reconciliation Objects
Reconciliation covers five core objects:
| Object | Description |
|---|---|
| Transaction | Individual payment, refund, or chargeback matched against provider records by reference, amount, currency, and status. |
| Settlement | Financial statement document aggregating transactions, fees, and net amounts for a period. Compared against provider-reported totals. |
| ProviderSettlement | Movement of funds from acquirer/terminal to the tenant's FundingAccount. Reconciled to verify that the provider's payout matches expected net amounts after fees. |
| FundingAccount | The tenant's real external account (bank account, crypto wallet) where money physically resides. Reconciled against bank statements to confirm actual fund receipt. |
| Fee | Provider fees, platform fees, and operational fees. Cross-checked between contracted rates, configured fee schedules, and provider-reported deductions. |
Key Points
- Reconciliation is a cross-system data consistency check, not balance synchronization.
- Five reconciliation objects: Transaction, Settlement, ProviderSettlement, FundingAccount, and Fee.
- Three workflow levels: transaction-level, settlement-level, and exception-based.
- The system highlights discrepancies; operators resolve them through controlled adjustments.
- No automatic ledger corrections. Every adjustment requires explicit action and an audit trail.
- Regular reconciliation is the foundation of financial control and provider trust.