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

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:

1

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.

2

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

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

The service returns a response that includes the transaction information without any modifications.

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.

Where you are?	Who to contact?
In the integration process	Contact the Xplor Pay integrations team.
In production	Contact the Xplor Pay support team.

Each terminal has its own public key. Use the public key that corresponds to the terminal that processed the transaction you’re verifying.