Transaction Webhooks

The Transaction webhooks notify your application when transaction events occur. They provide asynchronous notifications for transaction results, including successful and failed transactions, and are especially useful for recurring and offline transactions.

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 transaction webhook includes the same transaction response returned by the corresponding transaction API, with an additional signature field that you can use to verify the authenticity and integrity of the webhook payload.

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"
}

For information about verifying the webhook signature, see Digital signature.

Digital Signature

Each supported transaction webhook includes a signature field that helps you verify the webhook payload.

Verifying the digital signature helps confirm that:

• The webhook notification was sent by Xplor Pay.
• The webhook payload was not modified during transmission.

If you receive a webhook that can't be verified, treat it as untrusted and don't process the transaction.

Verify digital signature

You can verify the webhook signature in either of the following ways.

1

Verify locally (recommended)

Verify the webhook signature in your application by using the public key for the terminal that processed the transaction.

Local verification is recommended for production integration because it does not require an additional API request.

If you need implementation guidance, contact our Integration Specialist to verify the signature.

2

Use Hosted Payment Page signature verification service

Alternatively, you can use POST method with the /rest/v2/hpp/verify endpoint to validate the webhook signature and returns the verification result indicating whether the webhook payload is valid.

Include the complete webhook payload in the request body. For complete endpoint details, see HPP signature verification service.

The signature verification service returns only the verification result. It does not return the original transaction payload.

Request headers

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

Public key

Use the public key associated with the terminal that processed the transaction when verifying webhook signatures.

Environment	Contact
Integration (INT)	Contact to Xplor Pay Integrations team
Production	Contact to Xplor Pay Support team

Each terminal has a unique public key. Always use the public key associated with the terminal that generated the webhook you're verifying.