return_url vs notify_url: why a payment redirect is not proof of payment

return_url is for the buyer: when checkout ends, it brings their browser back to your site. notify_url (or a webhook) is for your server: once the payment platform has confirmed the result, it tells you directly, server to server.

Whether an order is paid can only be decided from a signature-verified notification, or from your server querying the order — never from the browser redirect. That holds on almost every payment platform; here is why.

return_url vs notify_url at a glance

Why the redirect is unreliable

The buyer paid and never came back

With a wallet, the buyer often approves the payment in another app. After approving, they may simply close the browser or switch apps, and your return_url is never visited. If your system updates orders only on the redirect, that is money taken and nothing delivered.

The buyer came back before the result was final

Cards that need 3D Secure, wallets that need a QR scan or an app approval — each has a window where the buyer has acted but the result is not yet final. When the buyer lands on your page, the payment may still be processing, or may end up failing.

Anyone can open the return URL

return_url is an ordinary URL. If your return page treats a parameter like ?paid=1 as success, anyone who copies that URL into a browser has "paid".

One order can see several payment attempts

A buyer may start with one method at checkout, abandon it and switch to another, so one order can go through several channel payments. Trusting any single redirect makes it easy to act on an attempt other than the one that finally succeeded.

The right way to confirm a payment

The backend lookup behind the return page looks like this:

curl "https://api.kukopay.com/v1/orders/TRD_9F3A2C7E..." \
  -H "X-Api-Key: $KUKOPAY_API_KEY"

Only a status of paid means the payment succeeded and has been credited; pending means it is still waiting.

When the notification is late

If notifications are delayed or every delivery failed, you have two ways back:

• Query the order. The order is still pending on your side but the buyer says they paid? Ask the platform once through order lookup.
• Backfill from the Events API. KukoPay records every payment result as an event first; a delivery is just one attempt to tell you. Events missed while your receiver was down can be pulled back by time range from the Events API.

The platform has its own safety net too: a reconciliation job keeps re-checking pending payments and refunds, so even if a channel's notification is lost and the buyer closed the page, the platform re-reads the result and credits the payment, sends the notification or closes the order.

Two details that are easy to miss

A payment that arrives after the order closed is refunded automatically. Rarely, a buyer's payment arrives after the order was already paid by another attempt or had expired. KukoPay refunds that payment to the buyer in full and sends payment.duplicate_refunded; your balance is not touched and you need do nothing.

Reconcile by order number, not payment_id. Because an order can go through several channel payments, the payment_id on the order object can change. Reconcile on trade_no / out_trade_no and the payment.succeeded event.

Summary

• return_url is for the experience; notify_url and webhooks carry the result;
• a redirect may never happen, may come too early, or may be forged;
• fulfil only on a verified notification or a server-side lookup;
• the return page reads state and never writes it.

To see these cases for yourself, use the 3D Secure test card 4000 0000 0000 3220 in the sandbox, or pick a wallet and close the browser on the test approval page, then check that the order is still credited and the notification still arrives. The test cards are listed in sandbox testing.