Overview

A webhook is a real-time notification triggered by a specific event. By subscribing to webhooks, you can automatically receive an update when something happens, rather than having to manually check anything.

Webhook retries

Occasionally, a webhook notification might fail to deliver. This could be because of a connection timeout occurring or a response taking too long. When this happens, we'll automatically retry the notification up to another 10 times in the 10 seconds following the initial delivery attempt.

Webhook validations

All webhooks coming from PXP include these HTTP headers:

X-Request-Id
X-Signature-Timestamp
X-Signature

To validate that a webhook was sent by PXP:

Concatenate the headers and the request body:
signedDataString = requestIdHeader + signatureTimeStampHeader + requestBody
Convert this string to bytes using UTF8 encoding:
signedData = utf8.getBytes(signedDataString).
Calculate signature by using HMAC with your HMAC key:
calculatedSignature = HMAC(signedData, key).
Validate whether the calculated signature matches the signature received in "X-Signature" as Base64:
asBase64(calculatedSignature) == signatureHeader.

ℹ️
You can configure your HMAC key in the Unity Portal by going to Merchant setups > Merchant group, selecting a merchant group, and clicking the Webhooks tab.

Structure

Each webhook event has the same overall structure:

{
  "eventCategory": "string",
  "eventDate": "date-time",
  "eventData": {object},
  "eventOwner":{ 
    "merchantGroup": "string",
    "merchant": "string",
    "site": "string"
  }
}

Parameter	Description
`eventCategory`	The specific area of payment operations that the event belongs to. This can be one of: `Authentication` `Token` `Transaction` `Reporting`
`eventDate`	The date and time when the event happened, in ISO 8601 format.
`eventData`	Details about the event. The structure of this object varies depending on the event. See the Examples section below for more information.
`eventOwner`	Details about the merchant group, merchant, and site that the event is associated with.

Supported events

Event name	Description	Event category
Challenge completed `challenge-completed`	A 3D Secure challenge was completed.	`Authentication`
Transaction authorised `transaction-authorised`	A transaction was authorised.	`Transaction`
Transaction cancelled `transaction-cancelled`	A transaction was cancelled.	`Transaction`
Transaction captured `transaction-captured`	A transaction was captured.	`Transaction`
Scheduled report generated `scheduled-report-generated`	A previously scheduled report was successfully generated and is ready to be downloaded.	`Reporting`
Scheme token created `scheme-token-created`	A scheme token was successfully created.	`Token`
Scheme token creation error `scheme-token-creation-error`	An error occurred during the creation of a scheme token.	`Token`
Scheme token card updated `scheme-token-card-updated`	A scheme token was updated.	`Token`
Scheme token disabled `scheme-token-disabled`	A scheme token was disabled.	`Token`

Example event data

Challenge completed

{
  "authenticationId": "5a13aae9-a0b1-4e3d-bcfb-1dbc90b5611f",
  "authenticationState": "AuthenticationSuccessful",
  "transactionStatus": "A",
  "transactionStatusReason": null,
  "directoryServerTransactionId": "5a4d019d-6c96-44c8-a625-636bc35ca0ac",
  "threeDSecureVersion": "2.2.0",
  "electronicCommerceIndicator": "05",
  "authenticationFlow": "Challenge",
  "challengeCancel": null,
  "challengeErrorReporting": null
}

Transaction authorised

{
  "state": "Authorised",
  "amounts": {
    "transaction": 30,
    "gratuity": 0,
    "currencyCode": "GBP"
  },
  "merchant": "Unity",
  "site": "UnityPTPOS",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Card",
    "entryType": "Instore"
  },
  "approvalCode": "138550",
  "merchantTransactionDate": "2025-04-01T11:41:02.826445+00:00",
  "merchantTransactionId": "310325_m15t9",
  "systemTransactionId": "97f664b6-f0fb-49c9-9404-dd782c0131fc",
  "providerTransactionId": null,
  "fundingData": {
    "card": {
      "cardScheme": "MasterCard",
      "gatewayTokenId": "1b59a988-ae81-45af-911a-b2ca1f199f34",
      "providerResponse": {
        "provider": "pxpfinancial",
        "code": "00",
        "merchantId": "7171910017",
        "electronicCommerceIndicatorAdjustment": "07",
        "merchantAdvice": {}
      }
    }
  }
}

Transaction cancelled

{
  "state": "Cancelled",
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Card",
    "entryType": "Ecom"
  },
  "amounts": {
    "transactionValue": 50.05,
    "currencyCode": "EUR"
  },
  "merchantOrderId": "This_is_my_merchant_order_id",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "fundingData": {
    "cardScheme": "Visa",
    "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "schemeTokenNumber": "4837261112345678",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "paymentAccountReference": "PAR12345678901234567890",
      "schemeTransactionId": "TX1234567890123456"
    }
  }
}

Transaction captured

{
  "state": "Captured",
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Card",
    "entryType": "Ecom"
  },
  "amounts": {
    "transactionValue": 50.05,
    "currencyCode": "EUR"
  },
  "merchantOrderId": "merchant_order_id",
  "merchantTransactionId": "merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "fundingData": {
    "cardScheme": "Visa",
    "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "schemeTokenNumber": "4837261112345678",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "paymentAccountReference": "PAR12345678901234567890",
      "schemeTransactionId": "TX1234567890123456",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}

Scheduled report generated

{
  "url": "https://api-gateway-transactions.qa.kube.qa/api/v1/reporting/scheduled-report-executions/d1adbc0d-d931-4775-8613-c44853c5464f/content-download-url"
}

Scheme token created

{
  "schemeTokenId": "68412215-aae5-4380-be63-c52e7868eab5",
  "schemeTokenProvider": "Visa",
  "state": "Completed",
  "externalSchemeTokenId": "7a60cfe4-df64-4e5d-b3d3-0b70713dd70b",
  "paymentAccountReference": "V0010013024080362079202015296",
  "expiryMonth": 4,
  "expiryYear": 2030,
  "maskedPrimaryAccountNumber": "47158511****6438"}
}

Scheme token creation error

{
  "schemeTokenId": "fc8aa727-ec3c-4cf1-9c2b-26e4f78ce7b7",
  "schemeTokenProvider": "Visa",
  "state": "Error",
  "externalSchemeTokenId": null,
  "paymentAccountReference": null,
  "expiryMonth": 3,
  "expiryYear": 2033,
  "maskedPrimaryAccountNumber": "41000000******0001"
}

Scheme token card updated

{
  "schemeTokenId": "bf53d5d5-6481-4c6b-9a99-deb4a319fb06",
  "schemeTokenProvider": "Mastercard",
  "state": "Completed",
  "externalSchemeTokenId": "1c871554-d90d-4676-89a6-e11a1bed3999",
  "paymentAccountReference": "50010P4G3SYR1Q9RJVY18EDBHWQZT",
  "expiryMonth": 12,
  "expiryYear": 2030,
  "maskedPrimaryAccountNumber": "52660010****0025"
}

Scheme token disabled

{
  "schemeTokenId": "bd420b08-00bc-4cfe-9b6b-84e52176c5b7",
  "schemeTokenProvider": "Mastercard",
  "state": "Completed",
  "externalSchemeTokenId": "a43d958e-e7a9-47b0-9a37-2f923744f59e",
  "paymentAccountReference": "50010P4G3SYR1Q9RJVY18EDBHWQZT",
  "expiryMonth": 4,
  "expiryYear": 2027,
  "maskedPrimaryAccountNumber": "52660010****0026"
}