This page is a ZenPay-styled copy of the Zenith Payments developer documentation. View the original docs
Payment Reconciliation
Reconciliation is the process of matching payments processed by Zenith against records in your own system. Zenith supports three complementary approaches, and most merchants use a combination depending on volume and operational needs.
Approach 1: Callback-based reconciliation#
When a Hosted Checkout payment completes, Zenith sends a server-to-server callback containing the full payment result including merchantUniquePaymentId, paymentStatus, baseAmount, processingDate, settlementDate, and a validationCode that authenticates the payload.
Use for: near-real-time reconciliation of Hosted Checkout flows.
Strengths: immediate, includes validation code for tamper protection, no polling required.
Limitations: only covers transactions that used a callbackUrl. Network failures or merchant-side outages may delay or drop callbacks — you still need a fallback.
See Callbacks and Validation for the full payload shape and validation flow.
Approach 2: Webhook-based reconciliation#
The Zenith webhook fires when specific payment state parameters change — including paymentStatus, payToStatus, and isPaymentSettledToMerchant. Unlike callbacks (which are tied to a single transaction and its callbackUrl), webhooks are merchant-wide and trigger on state transitions across all transactions.
Use for: tracking settlement status, PayTo mandate lifecycle updates, and events that happen after the initial payment completes (settlement, dispute, refund completion).
Strengths: covers events that callbacks miss (settlement transitions, PayTo status changes, post-payment updates).
Limitations: webhook delivery is best-effort; fall back to the API for authoritative state.
See Webhooks for subscription and payload details.
Approach 3: API-based reconciliation#
The GET /v2/payments endpoint returns payment records and can be queried on-demand. This is the authoritative source of payment state — use it to verify any callback or webhook, backfill missed events, or run periodic reconciliation sweeps.
Use for: end-of-day reconciliation runs, investigation of individual payments, recovery from missed webhooks, any audit process that needs a source of truth.
Strengths: deterministic, replayable, authoritative.
Limitations: requires merchant-side scheduling; higher overhead than event-driven approaches.
See the REST API Reference for the GET /v2/payments request and response schema.
Recommended reconciliation pattern#
Most merchants should combine all three approaches:
- Real-time: process callbacks as transactions complete (Approach 1).
- Asynchronous state updates: subscribe to webhooks for settlement, PayTo status, and post-payment events (Approach 2).
- Daily reconciliation sweep: run a scheduled job that queries
GET /v2/paymentsfor the previous day and compares against your local records to catch any missed events (Approach 3).
Edge cases to handle#
- Callbacks received out of order or duplicated: use
merchantUniquePaymentIdas an idempotency key. - Partial settlement:
isPaymentSettledToMerchantmay flipfalse → truedays after the initial payment; treat settlement as a separate event. This is when funds are released to the merchant and can be used to track successful bank payments. - PayTo mandate cancellation: a mandate active at payment time can later be cancelled by the customer in their bank app, triggering a webhook. Your reconciliation loop should handle status changes on existing records.
- Refunds: refund requests are manually approved, so the refund state on a payment record can change days after the refund was requested. Periodic API reconciliation is the only reliable way to track this.