Payment Webhooks Explained: Why Your Order Says Pending

A payment webhook is a message that your payment provider sends to your server when something happens to a payment, such as a payment succeeding or failing. If a customer pays but your order still says pending, the usual cause is that your system never received, or never handled, that message. The safe approach is to trust the webhook as the signal, then confirm the payment through the provider's API before you mark the order as paid.

• Webhook: a message from the provider to a web address on your server.
• Pending order: an order your system has not yet been told is paid.
• Confirm with the API: ask the provider directly for the payment's current status.

This guide is the written companion to our short video on the same topic.

What is a payment webhook?

A webhook is an automatic message sent from your provider's system to a web address you choose on your own server. When an event happens, such as a payment succeeding, the provider sends a small request describing it. Your server receives it and updates your records.

Webhooks exist because the customer's browser is not a reliable messenger. A customer can close the tab, lose their connection or never be sent back to your shop after paying. The webhook goes server to server, so it does not depend on what the customer does.

Why does an order stay pending after the customer paid?

A customer can finish paying and still never return to your site, so the page that would mark the order paid never runs. If you rely only on that page, the order stays pending even though the money moved.

Other causes are on the receiving side: the webhook address is wrong, your server was unavailable, a firewall blocked the request, or the code that handles the message failed. To see the earlier part of the path, read how a card payment moves.

How should you handle a webhook safely?

Treat the webhook as a signal, not as proof. A careful setup does the following.

• Verify the sender. Check the signature or secret your provider supplies, so a stranger cannot fake a message.
• Respond quickly. Reply with a success status as soon as you have received the message, and do slower work afterwards.
• Confirm with the API. Ask the provider for the payment's status before you mark the order paid.
• Handle repeats. The same webhook can arrive more than once, so make your handling safe to run twice.

Our guide on how to set up webhooks shows the steps in the EPaySe merchant dashboard, and how to manage API keys covers the keys you use to call the API.

What if a webhook never arrives?

Providers commonly retry a failed webhook for a while, but how often and for how long depends on the provider, so check the documentation. Do not rely on retries alone.

A good fallback is to check the status of any order that has stayed pending for longer than expected, using the API. That way an order is not left pending forever because a single message was lost. Testing this before launch is part of our payment integration testing checklist.

What is the difference between a webhook and an API call?

With an API call, your server asks the provider a question and gets an answer. With a webhook, the provider tells your server something without being asked. Used together, the webhook tells you when to look, and the API call confirms what you see.

FAQ

What is a webhook in simple words?

It is an automatic message from your payment provider to your server, sent when something happens to a payment, such as a success or a failure.

Why does my order say pending when the customer paid?

Usually your system has not received or handled the message that says the payment succeeded. The customer may not have returned to your site, or the webhook may not have reached your server.

Can I trust a webhook on its own?

Verify who sent it, then confirm the payment through the API before marking the order paid. That keeps a faked or repeated message from changing your records.

Can the same webhook arrive twice?

Yes. Design your handling so that running it twice leads to the same result as running it once.

What if my server was down when the webhook was sent?

Many providers retry for a time, but this varies. Check your provider's documentation, and use the API to check any order that stays pending.