Set up webhooks

To set up a default URL for all webhooks:

1. In the Unity Portal, go to Merchant setup > Merchant groups.
2. Select a merchant group.
3. Click the Webhooks tab.
4. Enter the URL you want PXP to send notifications to and generate a hash key.
5. Click Save to confirm. Your webhooks are now set up.

ℹ️

You can also override the merchant group settings and use a different URL for a specific merchant. To do so, select a merchant and go to the Webhooks tab and enter your URL. This works at both the default (overall) level and the service level.

To set up a URL for a specific service:

1. In the Unity Portal, go to Merchant setup > Merchant groups.
2. Select a merchant group.
3. Click the Webhooks tab.
4. Enter the URL you want PXP to send notifications to.
5. Optionally, tick the box next to the types of events you want PXP to use this URL for. If no box is ticked, PXP will send all the notifications related to the service to your chosen URL.
6. Click Save to confirm. Your webhook URL is now updated.

Process a webhook

To process a webhook, you'll need to supply key data from the webhook notification that you received:

• the eventDate: the date and time that the event occurred at, in ISO 8601 format.
• the eventCategory: The specific area of payment operations that the event belongs to. One of: Authentication, Token, Transaction, or Reporting.
• the eventData: Details about the event. The structure of this object varies depending on the event. See About webhooks for more information.

Request example

The following example shows how to process a webhook notification for a Transaction authorised event.

curl --request POST \
     --url https://api.pxpfinancial.net/api/v1/merchant-webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "eventDate": "2024-10-27T08:51:04.8264455Z",
    "eventCategory": "Transaction",
    "eventData": {
      "state": "Authorised",
      "approvalCode": "123456",
      "merchant": "MERCHANT-1",
      "site": "SITE-1",
      "transactionMethod": {
        "intent": "Authorisation",
        "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",
          "addressVerificationServiceResult": "D",
          "cardVerificationCodeResult": "A",
          "schemeTransactionId": "TX1234567890123456",
          "paymentAccountReference": "PAR12345678901234567890",
          "electronicCommerceIndicatorAdjustment": "01",
          "settlementDate": "2024-01-25"
        }
      }
    }
  }
]
'

Response example

If your request is successful, you'll receive a 200 response.

{
  "state": "Success"
}

For more information about this endpoint, see the API reference.

Manage duplicates

In some cases, you might receive the same webhook event twice — so make sure that your system is able to deal with duplicates. These duplicate webhook events will have the same values in the eventCode and systemTransactionId fields, while the eventDate and other fields can be different. Your server should always use the details from the latest webhook event.