How do I verify that a callback is genuinely from OxaPay (HMAC signature)?

Always validate the HMAC signature included with each callback – this step is crucial for security. OxaPay signs every webhook message using a secret key that only you and OxaPay know (your API key). It generates an HMAC (Hash-based Message Authentication Code)  over the raw JSON payload and sends this signature in the request headers.

To verify the callback’s authenticity, recompute the HMAC on your server using your API key and compare it to the signature provided by OxaPay. If the signatures match, the webhook is genuine and untampered. If they don’t, do not trust the data. This HMAC check acts like a fingerprint for the message, ensuring it really came from OxaPay and wasn’t altered in transit.

What information does OxaPay send in a callback?

OxaPay’s callback will include a JSON payload containing details about the transaction. The data typically includes:

• status: The payment status, such as "Paying" (in progress) or "Paid" (payment confirmed).

• amount: The amount paid in the transaction (in the specified currency).

• currency: The cryptocurrency used (e.g. "POL" for Polygon).

• track_id: A unique invoice ID from OxaPay to identify the payment.

• order_id: Your own order identifier, if you provided one when generating the payment.

There are some other fields as well, such as the payer’s email, a note, and an array of transaction details. The key point is that the webhook data tells you what payment this is and its current status. You can use this information to update your records (for example, mark an order as paid when you receive a status "Paid").