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.

Webhook Payload Structure

This webhook is sent to the Merchant’s configured webhook URL when a transaction is created and/or when its state changes.

Event Metadata

Field	Type	Required	Description	Example
name	string	Yes	Webhook event name in the format `transaction.<status>`. The `<status>` part indicates the transaction state at the moment the webhook was emitted.	`transaction.charged`
merchantId	string	Yes	Unique identifier of the merchant account in Plexy.	`35f3569c-a328-4b41-ba04-e0cfb0ca4d5d`
data	object	Yes	Transaction payload.	`{ ... }`

Transaction Details

Field	Type	Description	Example
id	string	Unique transaction identifier generated by Plexy.	`f0394412-2fe8-4467-a4a8-cfd41a68dc7e`
amount	number	Transaction amount in the smallest currency unit (e.g., cents) or in the API’s standard numeric representation for the given currency (depends on your integration setup).	`1000`
balance	number	Merchant balance after applying this transaction (if provided by the system for this event).	`9000`
currency	string	ISO 4217 currency code of the transaction.	`USD`
type	string	Transaction operation type (e.g., payment, refund, reversal), depending on the product flow.	`payment`
last4	string	Last 4 digits of the payment card (if the payment method is a card).	`6789`
paymentMethod	string	Payment method used for the transaction (e.g., `card`).	`card`
payerIp	string	IP address of the payer/customer at the time of initiating the payment (if captured).	`192.168.1.1`
merchantReference	string	Merchant’s own internal reference for the transaction (the same as orderRefernce).	`INV-1001`
description	string	Free-text description provided by the merchant for reconciliation or UI display.	`Order payment`
createdAt	string	Timestamp when the transaction was created (ISO 8601, UTC).	`2024-04-01T12:00:00Z`
updatedAt	string	Timestamp when the transaction was last updated (ISO 8601, UTC).	`2024-04-01T12:05:00Z`
authedAt	string	Timestamp when the transaction was authorized (ISO 8601, UTC), if authorization step exists in the flow.	`2024-04-01T12:02:00Z`
confirmedAt	string	Timestamp when the transaction was confirmed (ISO 8601, UTC), if confirmation step exists in the flow.	`2024-04-01T12:03:00Z`
processedAt	string	Timestamp when the transaction was processed/settled by the platform (ISO 8601, UTC), if applicable.	`2024-04-01T12:04:00Z`
processedAmount	number	Final processed amount. May differ from `amount` due to partial processing, rounding, fees, or adjustments depending on the product flow.	`1000`
storeId	string	Identifier of the store (sub-entity under a merchant) associated with this transaction.	`f08b3695-a632-4594-b89d-f40730420557`
terminalId	string	Identifier of the terminal/channel where the payment was initiated.	`5f2a1c13-99d8-4eb1-873a-563b1304e0a9`
secure3d	boolean	Indicates whether 3-D Secure was used/required for this card transaction (when applicable).	`true`
parentTransactionId	string	Identifier of the parent transaction, used when this transaction is derived from another one (e.g., follow-up action, recurring, refund chain).	`97870f4f-edc7-4f7e-830f-52c371bf6c32`
recurringType	string	Recurring payment classification (e.g., subscription/unscheduled) if the transaction is part of a recurring/merchant-initiated payment flow.	`subscription`
retrievalReferenceNumber	string	Acquirer reference (RRN) used for reconciliation with the bank/acquirer, if available.	`RRN987654321`
paymentLinkId	object	Payment Link identifier associated with the transaction (present when payment was initiated via Pay-by-Link). Wrapper object contains `Value`.	`{ "Value": "pl_..." }`
paymentSessionId	object	Payment Session identifier associated with the transaction (present for session-based flows). Wrapper object contains `Value`.	`{ "Value": "019a2a22-..." }`
cardTokenId	object	Saved card token identifier used for tokenized/recurring flows. Wrapper object contains `Value`.	`{ "Value": "4400437244977189" }`
customerId	object	Customer identifier in Plexy (if your integration creates/uses customers). Wrapper object contains `Value`.	`{ "Value": "01989f41-..." }`

Webhooks

Authorization#

Structure#

Transaction Statuses#

Webhook Payload Structure#

Event Metadata#

Transaction Details#

Authorization

Structure

Transaction Statuses

Webhook Payload Structure

Event Metadata

Transaction Details