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.
- Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is
application/x-www-form-urlencoded
. - Validate the webhook data using your salt value
- Return HTTP status code 200 to Hitpay
- 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¤cy=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c
Webhook fields
Following fields are sent with the webhook request:
Parameter | Description |
---|---|
payment_id | Payment ID |
payment_request_id | Payment request ID |
phone | Buyer’s phone number |
amount | Amount related to the payment |
currency | Currency related to the payment |
status | Payment status (completed / failed) |
reference_number | Arbitrary reference number that you have mapped during payment request creation |
hmac | Message Authentication code of this 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
- Ensure that you are using the correct salt value from the correct environment (Sandbox or Production)
- Make sure NOT to include the hamc value when calculating the hmac
- 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:
- Point of Sale
- Invoice
- Payment Link
- 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.
Updated 4 months ago