Skip to main content
Version: 0.0.1

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.

Most merchants should combine all three approaches:

  1. Real-time: process callbacks as transactions complete (Approach 1).
  2. Asynchronous state updates: subscribe to webhooks for settlement, PayTo status, and post-payment events (Approach 2).
  3. Daily reconciliation sweep: run a scheduled job that queries GET /v2/payments for 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 merchantUniquePaymentId as an idempotency key.
  • Partial settlement: isPaymentSettledToMerchant may flip false → true days 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.
Last updated on by Ian Menethil