About webhooks

Learn about PXP webhooks and supported events.

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. Possible values: `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 Example event data 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 card transaction was authorised.	`Transaction`
Transaction cancelled `transaction-cancelled`	A card transaction was cancelled.	`Transaction`
Transaction captured `transaction-captured`	A card transaction was captured.	`Transaction`
PayPal transaction created `paypal-transaction-created`	A PayPal, Pay Later, or Venmo transaction was created.	`Transaction`
PayPal transaction approved `paypal-transaction-approved`	A PayPal, Pay Later, or Venmo transaction was approved.	`Transaction`
PayPal transaction captured `paypal-transaction-captured`	A PayPal, Pay Later, or Venmo transaction was captured.	`Transaction`
PayPal transaction confirmed `paypal-transaction-confirmed`	A PayPal, Pay Later, or Venmo transaction was confirmed.	`Transaction`
PayPal transaction refunded `paypal-transaction-refunded`	A PayPal, Pay Later, or Venmo transaction was refunded.	`Transaction`
PayPal transaction voided `paypal-transaction-voided`	A PayPal, Pay Later, or Venmo transaction was voided.	`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"
    }
  }
}

PayPal transaction created

{
  "state": "Pending",
  "amounts": {
    "transaction": 100,
    "currencyCode": "USD"	
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445+00:00",
  "merchantTransactionId": "Create test 2",
  "systemTransactionId": "cb6c3fb9-fb0f-4924-b301-798d4606a3a8",
  "providerTransactionId": "8TV523960U3224341",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",	
      "paymentSource": "Paypal",
      "experienceContext": {
        "paymentDescription": "Louis Vuitton bag QC Test",
        "userAction": "PAY_NOW",
        "orderType": "Authorisation",
        "shippingPreference": "GET_FROM_FILE"
      }
    }
  }
}

PayPal transaction approved

{
  "state": "Approved",
  "amounts": {
    "transaction": 16.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445",
  "merchantTransactionId": "Create test 2",
  "systemTransactionId": "cb6c3fb9-fb0f-4924-b301-798d4606a3a8",
  "providerTransactionId": "8TV523960U3224341",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Paypal"
    }
  }
}

PayPal transaction captured

{
  "state": "Captured",
  "amounts": {
    "transaction": 10.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "shippingAddress": {
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "postalCode": "12345",
    "countryCode": "US",
    "city": "New York",
    "county": "Manhattan"
  },
  "merchantTransactionDate": "2025-06-20T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_id_007",
  "systemTransactionId": "e155b186-c6ea-4cb9-9a6c-590ef6daeeed",
  "providerTransactionId": "52K24494FC626730T",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "payee@mail.com",
      "paymentSource": "Paypal",
      "experienceContext": {
        "paymentDescription": "Purchase from test site",
        "userAction": "pay_now",
        "orderType": "goods",
        "shippingPreference": "set_provided_address"
      },
      "shippingSelected": {
        "id": "shipping_id",
        "label": "shipping_label",
        "selected": true,
        "amounts": {
          "shipping": 1.00,
          "currencyCode": "USD"
        },
        "type": "shipping"
      }
    }
  }
}

PayPal transaction confirmed

{
  "state": "Confirmed",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Confirm",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_id_0001",
  "systemTransactionId": "38e1cc67-b1c9-4b46-abda-03ec5caeae8d",
  "providerTransactionId": "95488117F3090464T",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Paypal"
    }
  }
}

PayPal transaction refunded

{
  "state": "Refunded",
  "amounts": {
    "transaction": 0.1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Refund",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_refund_id_0001",
  "systemTransactionId": "875f36e7-dbd9-44a1-be71-46bd97bc5efc",
  "providerTransactionId": "8UE54115C2538705D",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}

PayPal transaction voided

{
  "state": "Cancelled",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_void_id_0003",
  "systemTransactionId": "43326543-6956-469d-a1a0-64e6d9bb54c7",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}

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