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:

• Payment notify events
• Payment callbacks
• Get payment status

Integration choice

Surface	Best for	Strengths	Weaknesses
notify	Fast lifecycle signaling	Lightweight, responsive, good for merchant workflow triggers	Not authoritative for final request-level state
callback	Richer push-style request updates	Fuller request snapshot with payer/payee and fee context	Still must be treated as at-least-once delivery
GET /payments/status	Reconciliation and support tooling	Latest normalized state on demand	Pull-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:

• Production go-live checklist

Current scope

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

For the concrete current public docs set:

• notify payloads are documented in Payment notify events
• callback payloads are documented in Payment callbacks

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