Redirects and Webhooks

This section covers the critical integration settings required to connect your system with our payment gateway. We recommend following these security best practices to ensure a robust and reliable integration.

Redirects

When using our Web Checkout integration, users are directed to a secure, hosted checkout page to complete their payment. Once the process is finished, the gateway redirects the user back to your application.

You must provide two URLs in your dashboard:

• Success Redirect URL: Where users are sent after a successful transaction.
• Failure Redirect URL: Where users are sent if the transaction fails or is declined.

Webhook Configuration

Webhooks allow our payment gateway to notify your backend of payment events in real-time. Whenever a payment status changes, our system sends an asynchronous notification to your server.

To enable webhooks, configure a publicly accessible HTTPS URL in your dashboard. Our system will send a POST request to this URL whenever an event occurs (Successful, Failed, or Cancelled).

Security & Verification To secure your webhook endpoint, you must configure a Webhook Secret Key. This key is used to generate a digital signature that allows you to verify that the request originated from our gateway and has not been tampered with.

Our webhook requests include the following HTTP headers:

Headers:
{
  "YallaPay-Signature": "<HMAC-SHA-256 signature>",
  "YallaPay-TimeStamp": "<timestamp>"
}

YallaPay-Signature: This header contains the HMAC-SHA-256 signature. To verify the request, calculate the signature on your server using your Secret Key and the raw JSON request body (bytes):

YallaPay-Signature = HMAC-SHA-256(SecretKey, RawJsonBodyBytes)

Note: It is critical to use the raw, unparsed byte array of the JSON body for signature calculation. Parsing the JSON into an object before signing may change the formatting and result in a signature mismatch.

YallaPay-TimeStamp: This header contains the generation timestamp. Use this to prevent replay attacks by verifying that the request was sent within a reasonable timeframe (e.g., within the last 5 minutes).

The webhook request body uses the following JSON format:

Body:
{
  "clientReferenceId": "order_12345", // Your internal reference ID
  "paymentReferenceId": "01JXF7HSW41P9FCG9YN6Z094XR", // Our gateway reference ID
  "status": "SUCCESSFUL", // "SUCCESSFUL", "FAILED", or "CANCELLED"
  "timestamp": 1234567890123 // Unix timestamp in milliseconds
}

Best Practices

• Authentication: Always validate the YallaPay-Signature before processing the notification.
• IP Whitelisting: For an additional layer of security, you can whitelist our public IP address in your firewall settings to ensure you only accept traffic from our gateway.
• Idempotency: Ensure your system can handle the same webhook notification more than once in case of retries.