XPay Webhooks Integration

Webhooks Documentation & Setup Guide

Follow the steps below to configure the webhook URL in XPay:

Step 1: Log in to the XPay Portal

Access your XPay account using your credentials.

Step 2: Navigate to Webhook Settings

Go to XAP (XPay Admin Panel).
Click on Store Info.
Select Keys Details.
Locate the Webhook URL section.

Step 3: Copy the Webhook URL

Find the Webhook URL provided in the section.
Click Copy to save it to your clipboard.

Step 4: Add the Webhook URL

Paste the copied Webhook URL into the required field.
Ensure the changes are saved successfully.

After adding the URL, you will start receiving the webhook events on payments, subscriptions, etc.

Step 5: Signature Verification

You can copy the Webhook HMAC secret and create a SHA-256 signature using the received webhook payload and match it against the signature provided in webhook headers.

Sample Payload

json

{
  type: "PAYMENT_INTENT_NOTIFICATION",
  payment_intent_id:
    "xpay_pi_1573edc2074d54b60eb265e448cdf1eb5c09bfad5cac10153b107b0c780515fb",
  refund_id: null,
  amount: 10,
  currency: "PKR",
  status: "succeeded",
  customer: { name: "", email: "", phone: null },
  shipping: {},
  payment_method_types: "card",
  product: {},
  transaction_details: {
    _id: "",
    order: {
      customer: { name: "", email: "", phone: null },
      name: "",
      type: "headless",
    },
    status: "CAPTURED",
    secure: "3DS2",
    refunded_amount: 0,
    gateway: "bank-alfalah",
    response_from_bank: "The payment was completed successfully",
    status_message_from_bank: "PAYMENT_CAPTURED",
    activity: [
      {
        status: "AUTHENTICATION_SUCCESSFUL",
        amount: 10,
        timestamp: "2025-09-11T07:13:12.639Z",
        createdAt: "2025-09-11T07:13:21.349Z",
        token: "",
        card: {
          bin: "512345",
          last4digits: "0008",
          name: "Ali Raza",
          funding_method: "DEBIT",
          type: "MASTERCARD",
          issuer_details: {
            card_issuer: "Bank Alfalah Limited",
            card_network: "MASTERCARD",
            card_type: "DEBIT",
          },
        },
        "3ds": { authorization_code: "", secure: "3DS2", eci: "02" },
        processing: { acquirer_transaction_id: "trans-L7nyOnAvYu" },
      },
      {
        status: "CAPTURED",
        amount: 10,
        timestamp: "2025-09-11T07:13:20.826Z",
        createdAt: "2025-09-11T07:13:21.349Z",
        token: "",
        card: {
          hash: "ff847108d1912c7e4d9fe2da72c12952639cba4c8dbeecc5b2af806c874a84df",
          bin: "512345",
          last4digits: "0008",
          name: "Ali Raza",
          funding_method: "DEBIT",
          type: "MASTERCARD",
          issuer_details: {
            card_issuer: "Bank Alfalah Limited",
            card_network: "MASTERCARD",
            card_type: "DEBIT",
          },
        },
        "3ds": { authorization_code: "248935", secure: "3DS2", eci: "02" },
        processing: { acquirer_transaction_id: "trans-OksBWWiVur" },
      },
    ],
  },
  metadata: { order_reference: "" }, //metadata passed n create PI payload
  store_id: "",
  mode: "live",
  account_id: "",
};