Callback URL or return URL: why a customer coming back is not proof of payment

PHP & Development·· 25 views· 4 min read

The short answer: an online payment usually involves two addresses of yours that the operator uses. The return URL (or success URL) is where the customer’s browser is sent after paying: it is there to show them a page. The callback URL (also called notify URL, IPN or webhook) is called by the operator’s server directly to yours: that is the one that confirms the payment. Marking orders as paid because the customer reached the return URL means accepting proof anyone can type by hand, such as https://asuaempresa.ao/thank-you?order=1042&status=paid, and missing the payments of everyone who closed the tab before coming back. This is for whoever codes or configures a site’s payment integration.

The two addresses, side by side

Criterion Return URL Callback URL
Who calls it The customer’s browser. The operator’s server.
What it is for Showing a page: thank you, waiting, failed. Changing the order’s status.
Can you trust it? No. It can be typed by hand, or never happen (tab closed, network down, phone out of battery). Yes, once you have checked the signature or confirmed the status with the operator’s API.
What it should return A page for the customer to read. A 200 code, quickly. Nobody reads anything else.
Can it require a login? Yes. No. The operator has no session on your site and cannot solve captchas.

Setting up a callback URL that works

1 Use the final address, with HTTPS and no redirects. If the site redirects from http to https, or from www to the bare domain, the operator’s POST can arrive as a GET with no body. Test it as in what a webhook is and how to test one with curl: it must answer without a 301 or 302.
2 Keep it clear of anything that stops a visitor: password-protected areas, maintenance mode, captchas, plugins that block requests without a browser. If the operator gets a 403, see errors 500, 403, 404 and 508 and why an IP gets blocked by the firewall.
3 Confirm the origin before touching the order: check the signature (receiving a webhook in PHP and checking its signature) or, if the operator does not sign, use only the identifier you received to ask its API for the real status. Never trust the status or amount in the request without one of these two checks.
4 Check what was paid: the amount and currency match the order, and the order is still pending. A repeated notice for an order already paid is checked again and ignored: retries and idempotency.
5 Answer fast, work afterwards. Log every call (time, identifier, outcome of the check) to a file or a table, answer 200, and do the heavy work after that. If your code is slow, the operator may treat the call as failed and send it again.
6 On the return page, show what YOUR server knows: paid, or “waiting for confirmation”. Never what is in the address. If the callback has not arrived yet, the page says pending and, when it does arrive, the customer gets the confirmation by e-mail.
“The customer paid but the order is still pending” nearly always means the callback did not arrive or was refused: a wrong address in the operator’s settings, a redirect, a 403 block, or a 500 error in your code. Check the PHP error log and the operator’s dashboard, which often lists the notification attempts and the code your site returned.
When you change domain, move to HTTPS or change the shop’s path, update the callback URL in the operator’s settings (or in the code, if it is sent with each request). It is the most forgotten step of a migration, and payments keep coming in without the site noticing.

The operator says it notified your site and you see nothing in the log? Open a ticket with the callback address and the time of one notice, and we will look for the request in the hosting logs.

Open a support ticket

SEE ALSO

Receiving a webhook in PHP and checking its signature

What a webhook is, and how to test one with curl

Synchronous or asynchronous: why a payment or SMS confirmation arrives later

Timeouts, retries and idempotency: how not to charge a customer twice

How online payments work: gateway, processor and merchant account in plain words

Where the PHP error log is, how to read it, and the errors you will see most

RECOMMENDED PRODUCT

Web hosting with cPanel

Domain and SSL included, daily backups and the panel you already know. from 5.940,00 Kz/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

PHP & Development 375 How to change your PHP version You can choose which PHP version your site runs on, from the older releases up to the most recent ones, and turn extensi...
PHP & Development 251 Which technologies run here: PHP, Node, Python, Perl, games and the limits «My developer asks whether you support X.» This page answers that in one go, with names and versions - and it also says...
PHP & Development 439 Viewing and adjusting your PHP configuration: version per folder, extensions and phpinfo Changing a whole site's PHP version is easy and is covered in how to change your PHP version. This article is the next s...
PHP & Development 229 PHP limits: memory, time, upload size and the one that fails silently «I cannot upload the image.» «The import stops halfway.» «The menu lost half its items after saving.» Three different co...
PHP & Development 272 Where the PHP error log is, how to read it, and the errors you will see most When a site breaks there are two ways to react: guess, or read what the server already wrote down. The second is faster...
PHP & Development 27 Timeouts, retries and idempotency: how not to charge a customer twice The short answer: when a request to an API times out, you do not know whether it got through. It may have failed before...