PayNow Zimbabwe webhooks should be treated as the source of payment updates, not as a nice extra. A checkout can show a customer that payment is pending, but the server should wait for PayNow’s callback or a verified status check before marking an order as paid. That single rule prevents false confirmations, missing orders, and painful support tickets.
TLDR: PayNow Zimbabwe webhooks send payment status updates to a merchant’s server, usually after EcoCash, OneMoney, card, or other payment actions. A store should verify the callback, read the status field, and update the order only once. For example, if 1,000 payments are processed in a month and 7% are delayed by mobile money confirmation, webhook based handling can stop about 70 orders from being marked too early or left stuck in limbo.
What a PayNow Zimbabwe Webhook Does
A webhook is an automated message from PayNow to a merchant system. When a payment changes state, PayNow can notify the merchant’s result URL. This means the store does not need a staff member refreshing dashboards or a customer sending screenshots.
In a normal integration, the merchant creates a transaction and sends the customer to PayNow or starts a mobile payment request. PayNow replies with basic transaction data, often including a payment reference and a URL that can be checked later. After the customer pays, cancels, or fails to complete the flow, PayNow posts a status update.
The catch is that payment systems rarely feel instant from the server side. A customer may see an EcoCash prompt within seconds, while the merchant system waits longer for the final update. That gap is where many bad integrations break.
Why Status Fields Matter
The status field tells the merchant what happened to the transaction. It should drive the order state inside the shop, booking system, school portal, donation platform, or billing app.
A weak integration only checks whether PayNow sent a response. A better integration checks exactly what the response says. A response can exist even when the payment is not complete. This is where developers lose time. Honestly, it feels like three extra seconds saved at checkout can create three days of order cleanup later.
Common PayNow Status Values
Exact status names can vary by API version or implementation style, so teams should confirm against the PayNow documentation and live responses. Still, most integrations revolve around these common meanings:
| Status | Meaning | Recommended Action |
|---|---|---|
| Created | The transaction has been created but payment has not been completed. | Keep the order as pending. |
| Sent | A mobile money request may have been sent to the customer. | Wait for a later update. Do not ship. |
| Paid | The payment has been confirmed. | Mark the order as paid and trigger fulfilment. |
| Cancelled | The customer or payment process cancelled the transaction. | Mark as cancelled or keep checkout open for retry. |
| Disputed | The payment has a dispute or needs review. | Pause fulfilment and alert staff. |
| Refunded | Funds have been reversed. | Update finance records and stop unpaid service access. |
| Awaiting Delivery | Payment may be complete, but fulfilment confirmation is still expected. | Check business rules before closing the order. |
Key Fields Usually Seen in Webhook Data
A PayNow webhook or status response commonly includes several fields. The merchant should store them for audit and support.
- reference: The merchant’s own order or invoice reference.
- paynowreference: PayNow’s transaction reference.
- amount: The amount attached to the payment.
- status: The current payment state.
- pollurl: A URL that can be checked to confirm the latest status.
- hash: A security value used to verify that the data is genuine.
The reference field links the callback to the merchant’s internal order. The paynowreference helps when support teams compare records with PayNow. The amount protects against mismatches. The hash helps confirm that the message has not been tampered with.
Webhook Verification Should Happen Before Order Updates
A webhook endpoint should not blindly trust incoming data. It should verify the hash using the integration key or approved signing method. It should also check that the amount and reference match an existing unpaid order.
A safe flow looks like this:
- Receive the webhook request.
- Log the raw payload for audit.
- Verify the hash or signature.
- Find the matching order by merchant reference.
- Compare amount, currency, and PayNow reference.
- Apply the status change only if valid.
- Return a quick successful response to PayNow.
A server should avoid slow work inside the webhook request. Email, SMS, stock updates, and licence generation can run in a background job. The webhook should receive, verify, record, and respond.
Designing an Event Driven Payment Flow
An event driven integration reacts to updates instead of assuming checkout is finished when the customer leaves the payment page. This model fits PayNow well because mobile money confirmations may take time.
The merchant’s order system can use simple internal states:
- Pending Payment: The order exists, but no final payment has arrived.
- Payment Sent: A request was pushed to the customer’s phone.
- Paid: PayNow confirmed payment.
- Failed or Cancelled: Payment did not complete.
- Needs Review: The amount, reference, or status requires staff action.
This structure is easier to support than a single “paid yes or no” field. It also helps customer service staff explain what happened without calling a developer.
Handling Duplicate and Late Webhooks
Webhook systems may send the same event more than once. Networks fail. Servers time out. Retries happen. A good PayNow integration must be idempotent, meaning the same webhook can arrive twice without charging benefits twice or shipping two parcels.
The system should store each payment reference and final state. If a second Paid callback arrives for the same order, the system should record it but not trigger fulfilment again. If a late Cancelled status arrives after a verified Paid status, staff review may be safer than an automatic reversal.
Polling Still Has a Place
Webhooks are useful, but polling can act as a backup. If a customer returns to the merchant site before the webhook arrives, the system can check the pollurl for the latest status. This is also useful for daily reconciliation.
A practical setup uses both:
- Webhook first: Main path for payment updates.
- Poll on return: Quick check when the customer comes back.
- Scheduled polling: Cleanup for orders stuck in pending status.
For example, a merchant may poll pending orders every 10 minutes for one hour, then every hour for the rest of the day. This catches delayed confirmations without hammering the API.
Common Mistakes to Avoid
- Marking orders paid too early: A created transaction is not the same as a completed payment.
- Ignoring the hash: This can expose the system to fake callbacks.
- Not checking the amount: A reference match alone is not enough.
- Doing slow work in the webhook: Timeouts can cause repeated callbacks.
- Missing logs: Without logs, support teams guess instead of solving.
- No retry plan: Failed webhooks and stuck pending orders need cleanup jobs.
Best Practice Summary
A strong PayNow Zimbabwe integration treats payment status as an event stream. The store creates the transaction, waits for trusted updates, verifies every callback, and changes the order state based on the status field. It also keeps polling as a backup, not as the main process.
This setup reduces manual work. It gives finance teams better records. Most of all, it prevents customers from paying successfully while the merchant’s system still shows “pending.” That small failure is common, frustrating, and avoidable.
FAQ
What is a PayNow Zimbabwe webhook?
A PayNow Zimbabwe webhook is an automated callback sent to a merchant’s server when a payment status changes. It helps the merchant update orders without manual checks.
Which PayNow status means the order can be fulfilled?
Paid is the main status used to confirm that payment has been received. The merchant should still verify the hash, reference, and amount before fulfilment.
Should a merchant rely only on webhooks?
No. Webhooks should be the main update method, but polling the status URL is useful when a callback is delayed or when reconciling pending orders.
Why does the hash field matter?
The hash helps prove that the webhook data came from a trusted source and was not changed. The server should verify it before updating an order.
What happens if PayNow sends the same webhook twice?
The system should handle duplicates safely. A second callback for the same paid order should not trigger a second shipment, licence, email reward, or service credit.
How should disputed or refunded payments be handled?
They should move the order into a review state. Staff should check the PayNow record, the customer account, and the fulfilment history before taking action.
