Dispute Alert Callback

Purpose

After a Dispute Alert is uniquely matched to a merchant order and the merchant alert fee is recorded successfully, TrustPay sends a signed JSON callback to the original order notify_url.

A Dispute Alert is a pre-dispute notification. It is not a formal dispute, does not change the payment order status, and does not mean that a refund or formal dispute action has been completed.

Request

Method: POST

Content-Type: application/json

URL: the notify_url submitted with the original order

Notification type: type = 7

Delivery Semantics

Delivery is asynchronous and at least once.

TrustPay treats only HTTP 200 as successful delivery.

Network errors, timeouts, and non-200 responses may be retried.

The merchant must process duplicate callbacks idempotently by alert_id.

Return HTTP 200 only after the payload has been verified and durably accepted.

A failed callback does not reverse an alert fee that was already recorded successfully.

Wire Compatibility

The customer-facing name is Dispute Alert. The current implementation retains these legacy JSON identifiers:

event_type = chargeback_alert.created

chargeback_alert_fee

Receivers must not rename them. Changing these identifiers requires a versioned API and code change.

Fields

Field	Type	Required	Description
`type`	integer	Yes	Always `7`
`merchant_id`	integer	Yes	TrustPay merchant ID
`order_no`	string	Yes	Original merchant order number
`order_amount`	number	Yes	Original order amount
`paid_amount`	number	Yes	Original paid amount
`reason`	string	Yes	Provider reason code when supplied; may be empty
`event_type`	string	Yes	Current compatibility value: `chargeback_alert.created`
`alert_id`	string	Yes	TrustPay Dispute Alert ID and merchant idempotency key
`provider_alert_id`	string	Yes	Alert identifier supplied by the provider
`platform_order_no`	string	No	TrustPay platform order number
`warning_type`	string	Yes	`ethoca`, `rdr`, or `cdrn`
`alert_type`	string	Yes	`fraud` or `dispute`
`match_method`	string	Yes	`arn` or `card_amount_time`
`currency`	string	Yes	Original order currency, uppercase ISO 4217 code
`chargeback_amount`	number	Yes	Provider dispute amount; falls back to `paid_amount` when missing or zero
`chargeback_currency`	string	Yes	Provider dispute currency; falls back to order currency
`chargeback_alert_fee`	number	Yes	Compatibility field containing the merchant Dispute Alert fee
`masked_card_number`	string	No	Masked card number; full PAN is never included
`arn`	string	No	Acquirer Reference Number
`chargeback_reason_code`	string	No	Provider dispute reason code
`source`	string	No	Provider event source
`alert_timestamp`	string	No	Alert time in UTC RFC 3339 format
`transaction_timestamp`	string	No	Original transaction time in UTC RFC 3339 format
`received_at`	string	Yes	Time TrustPay received the alert, in UTC RFC 3339 format
`sign`	string	Yes	Lowercase hexadecimal MD5 signature

Optional fields may be omitted when unavailable. Amounts are JSON numbers and may contain up to four decimal places. Do not assume fixed trailing zeros.

The callback does not include:

full PAN or CVV;

provider account credentials;

raw provider payloads;

channel cost or platform profit;

internal errors or retry counters.

Example

{
  "type": 7,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 352.99,
  "paid_amount": 352.99,
  "reason": "10.4",
  "event_type": "chargeback_alert.created",
  "alert_id": "cba_example_001",
  "provider_alert_id": "2L07DBRFGBDLIW7SH59V969JG",
  "platform_order_no": "TP202607270001",
  "warning_type": "ethoca",
  "alert_type": "fraud",
  "match_method": "arn",
  "currency": "USD",
  "chargeback_amount": 352.99,
  "chargeback_currency": "USD",
  "chargeback_alert_fee": 4.5299,
  "masked_card_number": "800012******6824",
  "arn": "12345678901234567890123",
  "chargeback_reason_code": "10.4",
  "source": "ethoca",
  "alert_timestamp": "2026-07-27T12:00:00Z",
  "transaction_timestamp": "2026-07-26T12:00:00Z",
  "received_at": "2026-07-27T12:00:01Z",
  "sign": "SIGNATURE_VALUE"
}

Signature Verification

All non-empty fields in the actual callback participate in the signature, excluding sign.

Remove sign.

Remove fields with empty values.

Sort field names lexicographically.

Join as key1=value1&key2=value2.

Append &secret=YOUR_SECRET.

Calculate lowercase hexadecimal MD5.

Do not round or reformat numeric values before verification. See Signature Calculation for reference implementations.

Recommended Processing

Parse the JSON body.

Verify sign.

Validate type = 7, event_type, merchant_id, and the expected currency.

Insert the event using alert_id as a unique key.

Apply internal alert handling in an idempotent transaction.

Return HTTP 200.

Do not treat this callback as automatic permission to refund the payment.

Dispute Alert

Dispute Prevention (RDR)

Dispute Enums

Signature Calculation

Dispute Alert Callback

Purpose#

Request#

Delivery Semantics#

Wire Compatibility#

Fields#

Example#

Signature Verification#

Recommended Processing#

Related Documents#