Merchant webhooks service API (1.0.0)

This is an API reference for the merchant webhooks service.

Download OpenAPI description

merchant-webhook.json

merchant-webhook.yaml

Servers

Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

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.

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""Token""Transaction"

Example: "Transaction"

eventDataauthenticationData (object) or transactionData (object) or tokenData (object)required

One of:

eventData.authenticationIdstring

Unique reference provided by PXP for the authentication request, represented as a GUID.

Example: "71e2698f-10ec-44d4-8302-dcff7bdcfe90"

eventData.statestring(authenticationState)

The state of authentication indicating the outcome or current status of the authentication process.

Enum"PendingClientData""AuthenticationSuccessful""AuthenticationFailed""AuthenticationRejected""AuthenticationError""PendingCustomerChallenge"

Example: "AuthenticationCompleted"

eventData.transactionStatusstring(transactionStatus)

The status of the transaction.

Enum"Y""N""U""A""C""D""R""I"

Example: "Y"

eventData.transactionStatusReasonstring

Reason for the current transaction status.

eventData.directoryServerTransactionIdstring

Unique identifier for the directory server transaction.

Example: "71e2698f-10ec-44d4-8302-dcff7bdcfe90"

eventData.threeDSecureVersionstring

Version of the 3D Secure protocol.

Example: "2.2.0"

eventData.electronicCommerceIndicatorstring

Indicator used to signify the level of security used in the authentication, often used in electronic commerce transactions.

Example: "01"

eventData.authenticationFlowstring(authenticationFlow)

Flow of the authentication process.

Enum"Frictionless""Challenge"

Example: "Challenge"

eventData.challengeCancelstring

Indicator informing the ACS and the DS that the authentication has been cancelled.

Possible values:

01: Cardholder selected “Cancel”
02: Reserved for EMVCo future use (values invalid until defined by EMVCo).
03: Transaction Timed Out - Decoupled Authentication
04: Transaction Timed Out at ACS - other timeouts
05: Transaction Timed Out at ACS - First CReq not received by ACS
06: Transaction Error
07: Unknown
08: Transaction Timed Out at 3DS SDK
09: Error Message in response to the CRes message sent by the ACS
10: Error Message in response to the CReq message received by the ACS

Example: "01"

eventData.challengeErrorReportingstring

A copy of the error message sent or received by the ACS in case of error in the CReq/CRes messages.

curl -i -X POST \
  https://merchantendpoint/merchant-webhooks \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "eventDate": "2021-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"
          }
        }
      }
    }
  ]'

Responses

Webhook response

Bodyapplication/json

statestringrequired

The current state of the response.

Value"Success"

Example: "Success"

Response

application/json

{
  "state": "Success"
}

Merchant webhooks service API (1.0.0)

Process a merchant webhook

RequestExpand all

Responses

Was this helpful?

Request