Webhooks allow Plexy Pay to instantly notify a merchant’s system about critical events such as: Payment success or failure; Refund completion; Chargeback or dispute notification; Status change (e.g., pending - success). Instead of requiring the merchant to constantly poll for updates, webhooks push event data securely and immediately to a pre-defined URL on the merchant’s server.

Authorization

Each webhook is secured with a dedicated request header.

Authorization: Bearer <your-api-token>

You can contact your integration manager to issue the API key. Your webhook handler must verify the exact value of this header against the locally stored secret (kept in environment variables or a secure storage) and reject requests if it does not match. The key is only transmitted in the header (not in the URL or body), it is case-sensitive, and can be rotated without downtime.

It is recommended to complement the key check with additional measures: IP/ASN allowlisting, strict timeouts, logging all invalid attempts, and returning 401 Unauthorized without extra details. Upon a valid check, respond with 200 OK and handle the event asynchronously so webhook delivery is not blocked.

Structure

Webhooks are used to notify merchants about transaction updates in real-time. When a transaction status changes, a webhook event is triggered and sent to the merchant's configured endpoint.

Each payment webhook event contains the following structure:


{

  "name": "transaction.<status>",
  "merchantId": "123456",
  "data": {
    "id": "txn_abcdef123456",
    "amount": 1000,
    "balance": 9000,
    "currency": "USD",
    "status": "charged",
    "type": "payment",
    "last4": "6789",
    "paymentMethod": "card",
    "payerIp": "192.168.1.1",
    "merchantReference": "INV-1001",
    "description": "Order payment",
    "createdAt": "2024-04-01T12:00:00Z",
    "updatedAt": "2024-04-01T12:05:00Z",
    "authedAt": "2024-04-01T12:02:00Z",
    "confirmedAt": "2024-04-01T12:03:00Z",
    "processedAt": "2024-04-01T12:04:00Z",
    "processedAmount": 1000,
    "storeId": "store_1234",
    "terminalId": "term_5678",
    "secure3d": true,
    "parentTransactionId": "txn_parent1234",
    "recurringType": "subscription",
    "retrievalReferenceNumber": "RRN987654321",
    "paymentLinkId": {
      "Value": "pl_019a2a21f46f706ea202a75adabcbb80"
    },
    "paymentSessionId": {
      "Value": "019a2a22-1b0d-7732-9672-134baf97b06c"
    },,
    "cardTokenId": {
      "Value": "4400437244977189"
    },
    "customerId": {
      "Value": "01989f41-a6eb-77d4-a666-9361fb25bec6"
    },
  }
}

Merchants should implement webhook listeners to handle these events and update their system accordingly. It is recommended to:

Log incoming events for debugging.

Process event data and update the order status.

Respond with a 200 OK to acknowledge receipt of the webhook.

Transaction Statuses

Transaction Created

transaction.created — A new transaction has been created and is pending authorization.

Payment Successful

🟢 transaction.authorized — The payment has been successfully authorized — funds on the customer’s card are reserved (blocked) and waiting for capture. You can consider this transaction successful: the bank confirmed the availability of funds, and the payment will be captured automatically or manually from the dashboard.

Payment Failed

transaction.rejected — The transaction was rejected by the bank (for example, insufficient funds or incorrect card data).

transaction.failed — The transaction failed due to a system or network error. You may retry the payment or contact support if this persists.

Finalized Statuses

transaction.charged — The transaction has been successfully charged — funds have been finally debited from the customer’s account.
Use this status if you are integrated via manual clearing flow and handle captures yourself.

transaction.cancelled — The transaction was successfully cancelled before capture.
This notification confirms that the authorization hold has been released and the customer’s funds are no longer reserved.

transaction.refunded — The transaction was successfully refunded.
This notification indicates that a refund transaction was created.

Webhooks

Authorization#

Structure#

Transaction Statuses#

Authorization

Structure

Transaction Statuses