How to handle payment webhooks safely

Start with an order reference your system owns

Create each payment with the order or invoice reference from your own system. Keep that reference attached to the order through fulfilment, support and finance reconciliation. It gives your team one stable connection between the customer journey and the records you already maintain.

The reference is helpful, but it is not payment proof by itself. Your application should still apply its own confirmed-payment policy before releasing goods, access or value. That policy should account for the payment state shown through the authenticated product surfaces and signed events.

Do not treat the browser return as settlement evidence

A browser return improves the payer experience, but it is not the accounting event. External payment rails can remain pending after a customer returns, and a customer can close the browser before a payment reaches its terminal state. Show an appropriate pending or received experience instead of using the return alone to fulfil an order.

For an automated decision, use the confirmed payment state under your merchant policy. This keeps customer-facing navigation separate from the decision that changes your own order, entitlement or finance record.

Verify a delivery before applying it

ZyndPay delivers signed webhooks. Follow the developer documentation to validate the signature using the documented raw payload before trusting an event. Keep the verification step on your server and do not expose credentials or verification material in browser code.

If a delivery cannot be verified, do not let it change business state. Record enough operational context for your team to investigate safely, using the delivery history and support process available to your account rather than copying sensitive material into logs or tickets.

Make event processing idempotent

A delivery can be retried, and a recovery workflow can revisit a previously handled update. Design the consumer so that applying the same confirmed outcome again does not create a second fulfilment, entitlement, refund or accounting movement. Persist the decision your system made for the relevant payment and order before triggering downstream work.

Idempotency is also useful when your own service times out halfway through processing. On recovery, look up the prior decision and reconcile the authoritative payment state instead of assuming that an unknown attempt failed. This is safer than building a flow that relies on receiving every event exactly once.

Test the full lifecycle before requesting live access

Use the test environment exposed to your account to exercise payment creation, status handling and signed webhooks. Include ordinary completion as well as a repeated delivery, an unavailable endpoint and a customer who leaves the payment screen before the result is known.

Test results are not live settlement, and production capabilities remain subject to business verification, account approval and the features enabled for the merchant. Before going live, review the current documented event contract and the payment methods available to that account rather than relying on a generic integration assumption.

FAQ

Does a customer returning to my site prove that payment is complete?

No. A browser return can guide the customer, but it is not authoritative settlement evidence. Apply your fulfilment policy to the confirmed server-side payment state and signed events.

What should my system do when it receives the same webhook more than once?

Process deliveries idempotently: a repeat of an already applied confirmed outcome must not create a second business or money movement in your system.

Can I use webhooks before live access is enabled?

Use the test environment exposed to your account to validate supported payment and event flows. Live access remains subject to account approval and enabled capabilities.