Transaction Webhook

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 webhook supports 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": "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"
}

Digital signature

Xplor Pay digitally signs each transaction payload using the private key of the public/private key pair associated with the terminal that processed the transaction. This signature appears as a "signature" field in the transaction webhook.

Why the signature matters

The webhook callback comes from Xplor Pay servers, not from the end user, so it’s generally considered safe. However, if a bad actor obtained your callback endpoint URL, they could post fake payment responses, potentially tricking your system into thinking that real payments have been made. The digital signature gives you a way to confirm that:

• The callback originated from Xplor Pay.

• The transaction data hasn’t been tampered with in transit.

Verify the digital signature

You have two options for verifying the digital signature:

Option 1: Write your own verification code

Implement ECDSA signature verification using the programming language of your choice. Use the public key for the terminal that processed the transaction.

Option 2: Use the HPP Signature Verification Service

Call the HPP Signature Verification Service to confirm that the transaction payload hasn’t been modified between Xplor Pay servers and your servers.

Endpoint: POST https://gateway.clearent.net/rest/v2/hpp/verify/

Request headers

Accept: application/json
Content-Type: application/json
Public-Key: YOUR-PUBLIC-KEY-GOES-HERE

Request body

Send the complete callback message you received, without any modifications.

Get your public key

You need the public key for each terminal to verify signatures. How you get it depends on where you are in the process:

Where you are	Who to contact
In the integration process	Contact the Xplor Pay integrations team. They can provide the public key for each terminal.
In production	Contact the Xplor Pay support team. They can provide the public key for each terminal.

Note: Each terminal has its own public key. Make sure you use the key that corresponds to the terminal that processed the transaction you’re verifying.