Fraud & Dispute Webhook Notifications

Overview

In addition to standard payment lifecycle webhooks, the Lesspay2 platform also processes fraud decline and bank dispute event notifications from the upstream payment channel.

These event notifications are forwarded to the merchant's notify_url with additional event and event_data fields, allowing merchants to take appropriate action (e.g., flag the transaction, update internal records).

Important: These event notifications do not change the order status on the Lesspay2 platform. The order remains in its current state (e.g., SUCCEED). The purpose is purely informational — to alert the merchant about risk events.

Supported Event Types

Event Type	Trigger	Description
`payment_declined`	The upstream channel detects a payment decline with response code `30034` (Suspected Fraud) or `4xxxx` (Risk Blocked)	The payment was declined due to suspected fraud or risk rules
`dispute_received`	The upstream channel receives a dispute notification from the card scheme	A cardholder has disputed the payment with their bank (chargeback initiated)

Response Code Reference

Fraud Decline (payment_declined)

Response Code	Description
`30034`	Suspected fraud - Pick up. The issuer declined the payment due to suspected fraud.
`41101`	Risk Blocked Transaction (client-level risk rule)
`41201`	Decline list - Card number (client-level)
`41301`	Fraud score exceeds threshold
`42101`	Risk Blocked Transaction (entity-level risk rule)
`42201`	Decline list - Card number (entity-level)
`42301`	Fraud score exceeds threshold (entity-level)

For a full list of 4xxxx risk response codes, contact Lesspay Operations.

Bank Dispute (dispute_received)

Category	Description
`fraudulent`	The cardholder claims they did not authorize the transaction
`unrecognized`	The cardholder does not recognize the transaction
`product_service_not_received`	The cardholder claims they did not receive the product/service
`product_service_not_as_described`	The product/service was not as described
`credit_not_processed`	The cardholder claims a refund/credit was not processed
`duplicate`	The cardholder claims they were charged more than once
`other`	Other reasons

Webhook Callback Format

When a fraud decline or dispute event is received from the upstream channel, the Lesspay2 platform sends a POST request to the merchant's notify_url with the following payload. The format is consistent with the standard Create Payin, with two additional fields: event and event_data.

Parameters

Field Name	Type	Description
`request_id`	String	Merchant's unique Request ID
`pay_order_id`	String	Lesspay's unique Order ID
`order_status`	String	Current order status (unchanged, e.g., `SUCCEED`)
`order_status_int`	Integer	Current order status (numeric)
`target_currency`	String	Transaction currency
`target_amount`	String	Transaction amount
`product_name`	String	Product name
`description`	String	Order description
`api_version`	String	API Version
`channel_biz_data`	Object	Additional channel parameters
`event`	String	Event type: `payment_declined` or `dispute_received`
`event_data`	Object	Event-specific data (see below)

How to distinguish event notifications from payment notifications: If the event field is present and non-null, it is an event notification. Standard payment success/failure webhooks do not contain the event field.

Authentication

The same signature mechanism applies as described in Payin webhook. The x-auth-signature header is included and should be verified using the same process.

Event 1: Payment Declined (Fraud)

`event_data` Structure

Field	Type	Description
`response_code`	String	Channel response code (e.g., `"30034"`, `"41101"`)
`response_summary`	String	Human-readable decline reason (e.g., `"Suspected fraud - Pick up"`)
`risk_flagged`	Boolean	Whether the transaction was flagged by the channel risk engine
`checkout_payment_id`	String	Channel payment ID (e.g., `"pay_xxxxxxxxxxxx"`)

Example Callback Payload

{
    "pay_order_id": "P2011789219984105474",
    "request_id": "M20260228150001",
    "order_status": "SUCCEED",
    "order_status_int": 2,
    "target_currency": "USD",
    "target_amount": "100.00",
    "product_name": "Test Product",
    "description": "Test Order",
    "api_version": "V2",
    "success_url": "https://merchant.example.com/success",
    "fail_url": "https://merchant.example.com/fail",
    "event": "payment_declined",
    "event_data": {
        "response_code": "30034",
        "response_summary": "Suspected fraud - Pick up",
        "risk_flagged": true,
        "checkout_payment_id": "pay_xxxxxxxxxxxxxxxxxxxxx"
    }
}

Recommended Merchant Actions

Log the event for internal fraud monitoring and reporting.

Flag the transaction in your system for manual review.

Do not fulfill orders that have not been successfully paid.

For 4xxxx codes (risk-blocked), consider adding the cardholder to your internal watchlist.

For 30034 (suspected fraud), do not retry the payment with the same card.

Event 2: Dispute Received (Chargeback)

`event_data` Structure

Field	Type	Description
`dispute_id`	String	Channel dispute ID (e.g., `"dsp_xxxxxxxxxxxxxxxxxxxx"`)
`category`	String	Dispute category (e.g., `"fraudulent"`, `"unrecognized"`)
`amount`	Long	Disputed amount in minor units (e.g., `8150` = 81.50 GBP)
`currency`	String	Dispute currency (e.g., `"GBP"`)
`reason_code`	String	Card scheme reason code (e.g., `"10.4"` for Visa fraud)
`payment_method`	String	Card scheme (e.g., `"VISA"`, `"MASTERCARD"`)
`date`	String	Dispute date in ISO 8601 format
`checkout_payment_id`	String	Channel payment ID linked to this dispute

Example Callback Payload

{
    "pay_order_id": "P2011789219984105474",
    "request_id": "M20260228150001",
    "order_status": "SUCCEED",
    "order_status_int": 2,
    "target_currency": "GBP",
    "target_amount": "81.50",
    "product_name": "Test Product",
    "description": "Test Order",
    "api_version": "V2",
    "success_url": "https://merchant.example.com/success",
    "fail_url": "https://merchant.example.com/fail",
    "event": "dispute_received",
    "event_data": {
        "dispute_id": "dsp_xxxxxxxxxxxxxxxxxxxx",
        "category": "fraudulent",
        "amount": 8150,
        "currency": "GBP",
        "reason_code": "10.4",
        "payment_method": "VISA",
        "date": "2025-12-15T15:20:31Z",
        "checkout_payment_id": "pay_xxxxxxxxxxxxxxxxxxxxx"
    }
}

Recommended Merchant Actions

Log the dispute and create an internal dispute record.

Review the transaction — gather evidence such as delivery receipts, customer communication, and transaction logs.

Prepare evidence for potential dispute defense.

Contact Lesspay Operations if you need assistance with the dispute process.

Monitor dispute rates — high dispute rates can lead to penalties from card schemes.

Dispute Lifecycle

The initial dispute_received event is the starting point. The dispute may progress through the following stages:

Payment Disputed → Evidence Required → Evidence Under Review → Won / Lost
                                     → Expired (no response)
                                     → Accepted (merchant accepted)
                                     → Canceled (issuer canceled)

Note: Currently only the dispute_received event is forwarded to merchants. Future updates may include additional dispute lifecycle events (e.g., dispute_won, dispute_lost, dispute_evidence_required).

Integration Checklist

Update your webhook handler to check for the event field in incoming notifications

Handle payment_declined events — log fraud information and flag transactions

Handle dispute_received events — create dispute records and alert your operations team

Ensure your webhook endpoint returns HTTP 2xx for all event notifications (including events you choose not to act on)

Verify the x-auth-signature header as described in Payin webhook

Code Example (Java)

FAQ

Q: Will these event notifications change my order status?
A: No. The order status remains unchanged. These events are informational only.

Q: Can I receive both a payment_declined and a dispute_received for the same order?
A: Yes. A payment may first succeed (order_status=SUCCEED), and later receive a dispute_received when the cardholder disputes the charge. Separately, a payment_declined event indicates a failed payment attempt due to fraud detection — this is typically for transactions that were never successfully completed.

Q: What if I don't handle these events?
A: Your webhook endpoint should still return HTTP 2xx to acknowledge receipt. If it does not, Lesspay2 will retry the notification. Unhandled events will not affect your payment processing.

Q: Is the dispute_received amount always in minor units?
A: Yes. The amount field in event_data uses minor units (e.g., 8150 for GBP 81.50, 10000 for USD 100.00). The target_amount field in the top-level payload uses standard decimal format (e.g., "81.50").

Fraud & Dispute Webhook Notifications

Overview#

Supported Event Types#

Response Code Reference#

Webhook Callback Format#

Parameters#

Authentication#

Event 1: Payment Declined (Fraud)#

event_data Structure#

Example Callback Payload#

Recommended Merchant Actions#

Event 2: Dispute Received (Chargeback)#

event_data Structure#

Example Callback Payload#

Recommended Merchant Actions#

Dispute Lifecycle#

Integration Checklist#

Code Example (Java)#

FAQ#

Overview

Supported Event Types

Response Code Reference

Webhook Callback Format

Parameters

Authentication

Event 1: Payment Declined (Fraud)

`event_data` Structure

Example Callback Payload

Recommended Merchant Actions

Event 2: Dispute Received (Chargeback)

`event_data` Structure

Example Callback Payload

Recommended Merchant Actions

Dispute Lifecycle

Integration Checklist

Code Example (Java)

FAQ