Transaction Health
Transaction Health automatically detects payments whose status has diverged between MagiaPay and the upstream payment provider, or where your payment.succeeded webhook was never confirmed delivered. Findings appear in your dashboard so you can see what needs attention — without waiting for a customer complaint.
What it detects
After every payment reaches a terminal or extended non-terminal state, the daily sweep compares MagiaPay's record against the upstream provider. It classifies any gap into one of four finding classes:
| Class | What it means | Dashboard label |
|---|---|---|
recoverable | The upstream provider recorded a successful payment, but MagiaPay's status is still expired, failed, pending, or processing. The customer was charged but your ledger has not been credited yet. | Paid but not yet credited — recovering |
webhook_undelivered | MagiaPay shows the payment as succeeded and the ledger is credited, but the payment.succeeded webhook delivery to your endpoint was never confirmed. Your system may not know the payment went through. | Paid; notification to your system pending |
stuck_processing | The payment has been in pending or processing for longer than the configured SLA (default 2 hours) and the upstream provider still shows it as non-terminal. Something is taking unusually long to settle. | Awaiting confirmation |
status_mismatch_other | Both MagiaPay and the upstream provider have reached a terminal status, but they disagree on which one (e.g. MagiaPay says failed, upstream says expired). No money risk, but the records are inconsistent. | Under review |
When a payment passes the sweep and all statuses agree, it is automatically marked consistent and does not appear in the findings list. The dashboard shows the friendly labels above rather than the raw class codes.
How the sweep runs
The sweep is automated and runs once per day (at most once per ~22-hour window). It examines payments from the past 14 days, queries the upstream provider for current status (paced to avoid rate limits), and upserts findings into the database. An admin can also trigger a manual on-demand run from the admin dashboard.
The sweep only reads from the upstream provider — it never changes a payment's status by itself. Recovery of recoverable findings (crediting your ledger for a payment the provider already recorded as succeeded) is a human-initiated admin action.
The sweep runs against the live environment by default. See the sandbox section below for test-mode behaviour.
Your merchant view
Go to Transaction Health in your dashboard sidebar (under Payments) to see your own findings. The table shows:
- Payment ID
- Friendly status label (from the table above)
- Amount
- When the upstream provider recorded the payment as paid (if applicable)
- Resolution state (
openuntil admin action closes it)
If the table is empty, you will see "All payments consistent across providers ✓" — meaning the last sweep found no discrepancies for your account.
When findings exist, a Download report button appears. Click it to download an HTML report of your current findings — useful for sharing with your operations team or keeping as a record.
Recovery and resolution
Recovery is an admin action. Merchants cannot self-recover findings. When a recoverable finding is confirmed by an admin, MagiaPay credits your ledger using the existing late-settlement recovery path — the same mechanism that handled the 2026-06 paid-but-expired incident. Once resolved, the finding is closed and no longer appears in your active list.
For webhook_undelivered findings: your webhook endpoint may have been unreachable at delivery time. Poll Events (GET /v1/events?type=payment.succeeded) to catch up on any deliveries your server missed — this is independent of the sweep and works any time.
Relationship to Events
Events track MagiaPay state changes and webhook deliveries from your perspective — you poll them to catch missed webhooks on your side. Transaction Health tracks discrepancies between MagiaPay and the upstream provider — the sweep runs on the MagiaPay side and surfaces gaps you would not see by polling events alone. The two tools are complementary.
Testing in sandbox
Transaction Health is a live-environment feature. The sweep compares MagiaPay's database against the upstream provider's real status — but in test mode, test payments are processed by the MagiaPay sandbox mock provider, which has no independent upstream system to diverge from. Because both sides are the same simulated source of truth, discrepancy findings do not naturally occur in sandbox.
In test mode, the Transaction Health dashboard will show "All payments consistent across providers ✓" even if you have test payments in unusual states. This is expected and correct — it reflects the architecture, not a bug. If you need to verify the detection logic, that requires a live account with real upstream provider data.
See Testing & Sandbox for general sandbox guidance.