Skip to main content

Webhooks

PayWise Checkout integrations can use two push-style payment delivery surfaces:

  • notify: lightweight lifecycle notifications
  • callback: fuller request-level transaction snapshots

Use this page as the navigation and implementation guide for webhook-style payment delivery.

These are configured in the Checkout request contract under:

  • transaction_request.urls.notify
  • transaction_request.urls.callback

See Create payment request.

Start here​

Read these concrete payment payload docs first:

Integration choice​

SurfaceBest forStrengthsWeaknesses
notifyFast lifecycle signalingLightweight, responsive, good for merchant workflow triggersNot authoritative for final request-level state
callbackRicher push-style request updatesFuller request snapshot with payer/payee and fee contextStill must be treated as at-least-once delivery
GET /payments/statusReconciliation and support toolingLatest normalized state on demandPull-based, not event-driven

Which one should I use?​

Use notify when you want:

  • fast UI updates
  • lightweight merchant workflow triggers
  • event-style lifecycle logging

Use callback when you want:

  • fuller request-level payment snapshots
  • richer payer/payee and fee context
  • a better push-side record of terminal request state

Use GET /payments/status when you want:

  • the latest normalized state on demand
  • reconciliation after delivery delays or retries
  • support and operations tooling

Recommended integration model:

  1. receive notify events for responsiveness
  2. receive callbacks for richer request-level state
  3. reconcile with GET /payments/status for final confirmation

Delivery model​

Design both notify and callback consumers as if delivery is at-least-once.

That means:

  • duplicate deliveries must be safe
  • arrival order must not be trusted by itself
  • your handler should be idempotent
  • your persistence layer should tolerate replay

Persist enough metadata to debug support cases:

  • PayWise request id if present
  • your own correlation id or order id
  • transaction_id
  • callback/request id where applicable
  • receive timestamp
  • HTTP response code returned by your handler

Current auth and trust contract​

For payment notify and payment callback, the current public docs set does not freeze a PayWise-wide shared signature/header contract the way the personal-account callback docs do.

That means:

  • do not assume personal-account callback headers apply to Checkout payment webhooks
  • do not build business logic around undocumented signature headers
  • do treat HTTPS reachability, idempotency, correlation, and reconciliation with GET /payments/status as mandatory

When a payment-specific signature/header contract is frozen publicly, it should be documented on the concrete payment payload pages and linked here.

Receiver requirements​

Your endpoint should:

  • be publicly reachable over HTTPS
  • return a 2xx response when the payload is accepted
  • validate the raw request body before destructive side effects if and when a documented signature contract applies
  • log failures with request ids and timestamps

Do not rely on:

  • browser redirects as proof of payment finality
  • a single notify delivery as the only record of success
  • one payload shape serving every payment lifecycle purpose

Production guidance​

Before going live:

  • use production HTTPS URLs for notify and callback
  • make sure they are not localhost
  • verify monitoring and alerting for non-2xx responses
  • confirm reconciliation with GET /payments/status
  • test at least one end-to-end delivery path for both notify and callback

Related production checklist:

Current scope​

This page is intentionally focused on payment webhook-style delivery.

For the concrete current public docs set:

If PayWise later introduces additional generic webhook families outside Checkout payments, they should be documented separately rather than overloading this page.