Webhooks

Webhooks

Webhook is a POST request sent from HitPay's server to your server about the payment confirmation. If you are using hitpay APIs to integrate into your e-commerce checkout you must mark your order as paid ONLY after the webhook is received and validated.

1. Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is application/x-www-form-urlencoded.
2. Validate the webhook data using your salt value
3. Return HTTP status code 200 to Hitpay
4. Mark your order as paid

payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00&currency=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c

Webhook fields

Following fields are sent with the webhook request:

Validate Webhook

Hitpay creates a list of all values from the key-value pairs that we send in the POST request and sort them in the order of their keys alphabetically. We then concatenate all these values together. We then use the HMAC-SHA256 algorithm to generate the signature. The HMAC key for the signature generation is the secret salt from your dashboard under Settings > Payment Gateway > API Keys.

public function generateSignatureArray($secret, array $args) 
    {   
        $hmacSource = [];        

        foreach ($args as $key => $val) {
            $hmacSource[$key] = "{$key}{$val}";
        }    

        ksort($hmacSource);

        $sig            = implode("", array_values($hmacSource));
        $calculatedHmac = hash_hmac('sha256', $sig, $secret); 

        return $calculatedHmac;
    }

Signature Mismatch?

Possible reasons for the wrong hmac value generated

1. Ensure that you are using the correct salt value from the correct environment (Sandbox or Production)
2. Make sure NOT to include the hamc value when calculating the hmac
3. Make sure all the values stated above are included in the payload including reference_number. Use an empty string if the value does not exist

Webhook For POS and Other Payment

Hitpay also allows you to receive webhook for payments that are not initiated from "Payment Request APIs".
Example:

1. Point of Sale
2. Invoice
3. Payment Link
4. Online Store

To set the webhook for these payments navigate to "Settings > Notifications" and enter the URL. The webhooks are also sent for every successful refund.

🚧

NOTE

If you are using payment request APIs, do not use this feature. Using the "webhook" parameter from the payment request API would be a better solution.