Chargeback Callback

Purpose

TrustPay sends a signed JSON callback to the original payment order notify_url when a formal dispute enters a merchant-relevant funds state:

opened and funds held;

lost;

won.

Formal dispute callbacks are independent from type = 7 Dispute Alert callbacks.

Request

Method: POST

Content-Type: application/json

URL: the notify_url submitted with the original order

Notification type: type = 4

Delivery and Idempotency

TrustPay treats only HTTP 200 as successful delivery.

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

Verify the signature before applying business changes.

Durably accept the event before returning HTTP 200.

Process repeated events idempotently using dispute_id together with dispute_status.

Fields

Field	Type	Required	Description
`type`	integer	Yes	Always `4`
`merchant_id`	integer	Yes	TrustPay merchant ID
`order_no`	string	Yes	Original merchant order number
`order_amount`	number	Yes	Formal dispute principal
`balance_amount`	number	Yes	Merchant balance movement for this lifecycle event
`reason`	string	Yes	TrustPay lifecycle description
`dispute_status`	string	Yes	`chargeback_pending`, `chargeback_lost`, or `chargeback_won`
`dispute_id`	string	No	TrustPay formal dispute ID when available
`response_status`	string	No	Current merchant response state
`dispute_fee`	number	Yes	Processing fee charged in this event; zero for lost/won finalization
`expiration_date`	string	No	Response deadline in `YYYY-MM-DD` format
`sign`	string	Yes	Lowercase hexadecimal MD5 signature

Payment-only fields such as status, paid_amount, refund_amount, merchant_refund_no, fee, and pay_time are omitted from a formal dispute callback.

Funds Semantics

`dispute_status`	`balance_amount`	`dispute_fee`	Meaning
`chargeback_pending`	Negative	Configured fee	Principal and fee held when the case is created
`chargeback_lost`	`0`	`0`	Funds were already held; final loss does not create another debit
`chargeback_won`	Positive principal	`0`	Previously held principal returned; the processing fee is not returned

Pending Example

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": -115,
  "reason": "Chargeback opened: funds held pending dispute decision",
  "dispute_status": "chargeback_pending",
  "dispute_id": "dsp_example_001",
  "response_status": "needs_response",
  "dispute_fee": 15,
  "expiration_date": "2026-08-15",
  "sign": "SIGNATURE_VALUE"
}

Lost Example

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": 0,
  "reason": "Chargeback lost: dispute refund confirmed",
  "dispute_status": "chargeback_lost",
  "dispute_id": "dsp_example_001",
  "response_status": "no_response_allowed",
  "dispute_fee": 0,
  "sign": "SIGNATURE_VALUE"
}

Won Example

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": 100,
  "reason": "Chargeback won: held funds released",
  "dispute_status": "chargeback_won",
  "dispute_id": "dsp_example_001",
  "response_status": "responded",
  "dispute_fee": 0,
  "sign": "SIGNATURE_VALUE"
}

The chargeback_* values and current English reason messages are machine-contract values. Customer-facing documentation refers to the lifecycle as a formal dispute.

Signature Verification

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

Remove sign.

Remove 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.

Recommended Processing

Parse the JSON body.

Verify sign.

Validate type = 4, merchant_id, dispute_id, and dispute_status.

Store the event idempotently by dispute_id and dispute_status.

Apply the funds movement represented by balance_amount only once.

Return HTTP 200.

Dispute Management

Dispute Enums

Signature Calculation

Chargeback Callback

Purpose#

Request#

Delivery and Idempotency#

Fields#

Funds Semantics#

Pending Example#

Lost Example#

Won Example#

Signature Verification#

Recommended Processing#

Related Documents#