Consuming Webhooks

Notify URL (PayGate Webhooks / Instant Transaction Notification)

PayGate supports a callback mechanism commonly known as the notify_url. Some developers refer to this feature as "ITN" (Instant Transaction Notification). While it differs from modern webhook implementations, it plays the same role — notifying your server of transaction results in real-time.

This guide explains how the notify_url works, what data to expect, and how to ensure successful integration.

How It Works

1. During your integration, you define a publicly accessible HTTP or HTTPS URL as the notify_url.
2. After a transaction is processed via PayWeb, PayGate sends a server-to-server HTTP POST request to the notify_url using form-encoded data.
3. Your system must respond with plain-text OK (case-sensitive) to confirm successful receipt.
4. If the response is not OK, or if the delivery fails, PayGate will retry the notification 3 times at 30-minute intervals.

Setup

To enable the notify_url:

• Include it as part of your PayWeb request parameters, or configure it via your integration settings.
• Ensure your endpoint supports HTTP POST, either on port 443 (HTTPS) or port 80 (HTTP).
• Accept application/x-www-form-urlencoded payloads.

Sample Payload

Here is an example of the data sent by PayGate to your notify_url:

PAYGATE_ID=10011072130&
PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&
REFERENCE=pgtest_123456789&
TRANSACTION_STATUS=1&
RESULT_CODE=990017&
AUTH_CODE=5T8A0Z&
CURRENCY=ZAR&
AMOUNT=3299&
RESULT_DESC=Auth+Done&
TRANSACTION_ID=78705178&
RISK_INDICATOR=AX&
PAY_METHOD=CC&
PAY_METHOD_DETAIL=Visa&
CHECKSUM=f57ccf051307d8d0a0743b31ea379aa1

Validation

We recommend validating the CHECKSUM included in the payload using your encryption key to ensure the data hasn't been tampered with.

Expected Response

Your server must return this exact response:

OK

• It must be plain-text only.
• No HTML, JSON, or additional data should be returned.
• Failure to return this will cause PayGate to retry.

Retry Mechanism

If PayGate doesn’t receive a valid OK response:

• It will retry 3 times.
• Each retry happens 30 minutes apart.
• After 3 failed attempts, PayGate stops trying.

Testing Your Notify URL

When testing:

• Use tools like ngrok to expose local servers.
• Check server logs to confirm the POST request arrives.
• Ensure the endpoint is reachable on port 80 or 443.
• Validate that your response is only OK.

Troubleshooting Tips

Key Notes

• Notify is only triggered after transaction completion.
• Works independently of the browser redirect.
• Cannot be used to update transaction status if missed — use the Query API instead for status checks.