# Transaction Webhooks

The **Transaction** **Webhooks** notify you of transaction success and failure. They're especially important for recurring and offline transactions. The transaction webhook delivers notifications for all transaction events that a merchant account performs.

### Supported transaction events

The transaction webhooks support the following events:

* Authorization
* Capture
* Sale
* Forced Sale
* Refund
* Unmatched Refund
* Void
* ACH Credit
* ACH Debit

### Webhook payload

The webhook payload is identical to the response for a transaction event, with one addition: a digital signature field for verification purposes.

#### Sample payload

{% code lineNumbers="true" %}

```json
{
    "code": "200",
    "status": "success",
    "exchange-id": "ID-clearent-cgw-1-1710772535480-0-24101130",
    "links": [
        {
            "rel": "transaction",
            "href": "/rest/v2/transactions?id=117834254",
            "id": "117834254"
        }
    ],
    "payload": {
        "transaction": {
            "amount": "100.00",
            "id": "117834254",
            "created": "2024-04-09 14:53:24.148",
            "type": "SALE",
            "result": "APPROVED",
            "billing": {
                "zip": "85284"
            },
…
   "signature": "30650230447b36ebeb3aa57faec5141ea73ee3b6f0110dadb1c16dd7fffc7c0c8815879c67f1914910b81955f8685d669e06abd502310088b0260519094aa000077ced6f9c0ad686ca955c89e19e0b5303247b71c8785b4e561f24cba66b273bfcb28f1b066314"
}
```

{% endcode %}

### Digital signature

The webhook payload for a successful transaction includes a `signature` field that contains the digital signature generated by the terminal’s key pair. This signature helps verify the terminal through which the payment was processed.

However, if bad actors obtain your callback endpoint URL, they could send fake payment responses and potentially trick your system into accepting them as valid. The `signature` field helps verify that:

* The payment response was sent by Xplor Pay.
* The transaction data wasn’t tampered with during transit.

### Verify digital signature

To verify the digital signature:

{% stepper %}
{% step %}

### Write your own verification code

Use the programming language of your choice to implement Elliptic Curve Digital Signature Algorithm (ECDSA) verification by using the public key for the terminal that processes the transaction.
{% endstep %}

{% step %}

### Use Hosted Payment Page signature verification service

Use POST method to call the `https://gateway.clearent.net/rest/v2/hpp/verify/` endpoint to verify that the transaction payload wasn’t modified between the Xplor Pay servers and your servers. 

#### Request headers

<pre class="language-json" data-overflow="wrap" data-line-numbers><code class="lang-json">Accept: application/json
Content-Type: application/json
<strong>Public-Key: YOUR-PUBLIC-KEY-GOES-HERE
</strong></code></pre>

The service returns a response that includes the transaction information without any modifications.
{% endstep %}
{% endstepper %}

### Public key

You might need the terminal’s public key to verify the digital signature for the payment. The following table provides contact information for obtaining the public key for each terminal.

<table><thead><tr><th width="268" valign="top">Where you are?</th><th valign="top">Who to contact?</th></tr></thead><tbody><tr><td valign="top">In the integration process</td><td valign="top">Contact the Xplor Pay integrations team.</td></tr><tr><td valign="top">In production</td><td valign="top">Contact the Xplor Pay support team.</td></tr></tbody></table>

{% hint style="warning" %}
Each terminal has its own public key. Use the public key that corresponds to the terminal that processed the transaction you’re verifying.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xplorpay.com/api-reference/webhooks/working-with-webhooks/transaction-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.