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, PayPal, Pay Later, or Venmo transaction was authorised.	`Transaction`
Transaction cancelled `transaction-cancelled`	A card, PayPal, Pay Later, or Venmo transaction was cancelled.	`Transaction`
Transaction captured `transaction-captured`	A card, PayPal, Pay Later, or Venmo transaction was captured.	`Transaction`
Transaction created `transaction-created`	A PayPal, Pay Later, or Venmo transaction was created.	`Transaction`
Transaction executed `transaction-executed`	A PayPal, Pay Later, or Venmo transaction was approved and executed.	`Transaction`
Transaction refunded `transaction-refunded`	A card, PayPal, Pay Later, or Venmo transaction was refunded.	`Transaction`
Payout authorised `payout-authorised`	A payout was authorised.	`Transaction`
User info created `user-info-created`	Customer information was created and verified.	`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 because a card was replaced or renewed.	`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",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "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",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "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",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "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"
    }
  }
}

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

Transaction executed

{
  "state": "Executed",
  "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"
    }
  }
}

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

Payout authorised

{
  "state": "Authorised",
  "amount": {
    "transaction": 100.0,
    "currencyCode": "USD"
  },
  "transactionMethod": "Payout",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z",
  "merchantTransactionId": "PAYOUT_001",
  "systemTransactionId": "787ebfee-c0ce-497a-82c3-265d1bf19b0c",
  "providerTransactionId": "PAYPAL_PAYOUT_ITEM_ID",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}

User info created

{
  "merchant": "merchant-1",
  "site": "site-1",
  "customerInformation": {
    "id": "a7cd91cd-1bb8-4f82-af24-350d6d0b8680",
    "name": "John Doe",
    "email": "sb-oejwh44573747@business.example.com",
    "verified": true,
    "payerId": "BLLXSEJZ9B7ZA",
    "address": {
      "streetAddress": "1 Main St",
      "locality": "San Jose",
      "region": "CA",
      "postalCode": "95131",
      "countryCode": "US"
    },
    "verifiedAccount": true,
    "emailVerified": true
  },
  "eventCode": "TXNPP_UIC"
}

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