Process a merchant webhook

Request

The /merchant-webhooks endpoint is designed for real-time notifications about transaction events, enabling you to automatically receive updates on transaction statuses such as authorisations, captures, and cancellations. Supported products include card payments, PayPal (including Pay Later and Venmo), Aeropay pay-by-bank events (including user suspended and user activated), and SPEI pay-by-bank events (purchase, payout, and refund outcomes).

Security

PXP-UST1

Bodyapplication/jsonrequired

Merchant webhooks

eventDatestring, (date-time)(eventDate)required

The date and time when the event occurred, sent to the merchant as part of the webhook payload. This timestamp is crucial for tracking the timing of specific events, such as transaction authorisations, captures, or any other significant activity related to the merchant's operations. The format adheres to ISO 8601 standards, ensuring consistency and ease of parsing for system integration.

Example:"2021-10-27T08:51:04.826Z"

eventCategorystring(eventCategory)required

The category of the webhook event sent from PXP to you. This field classifies the nature of the event being notified, facilitating targeted processing by your system. Event categories encompass a range of types, including but not limited to transactions (such as purchases, authorisations, captures), chargebacks, disputes, and more. Each category signifies a specific area of payment operations, enabling merchants to listen for and respond to relevant events effectively.

Enum:"authentication""reporting""token""transaction"

Example:"transaction"

eventOwnerobject(eventOwner)

The entity that owns the event.

eventDataauthenticationData (object) or transactionData (object) or aeropayTransactionData (object) or speiTransactionData (object) or tokenData (object) or reportingData (object) or userInfoData (object) or aeropayUserStatusData (object)required

One of:

POST

/merchant-webhooks

curl -i -X POST \
  https://merchantEndpoint/merchant-webhooks \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventDate": "2021-10-27T08:51:04.8264455Z",
    "eventCategory": "transaction",
    "eventData": {
      "state": "Authorised",
      "stateData": {
        "code": "CRD000",
        "message": "Approved"
      },
      "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"
        }
      }
    }
  }'

Responses

Webhook response

Bodyapplication/json

statestringrequired

The current state of the response.

Value:"Success"

Example:"Success"

Response

{
  "state": "Success"
}