1. Dispute Management
TrustPay
en
  • en
  • zh
  • Integration Guide
  • Signature Calculation
  • Payment Gateway
    • Risk Control – Merchant Integration
    • Enums
    • Payment Callback Specification
    • C21 Suport Regions
      • TrustPay Supported Billing Countries and US/Canada Regions
    • Whitelist Management
      • Add Card Whitelists
      • Query Card Whitelists
      • Query Card Whitelists Task
    • Card Direct Payin
      POST
    • Cashier Payin
      POST
    • Order Refund
      POST
    • Payment Callback
      POST
    • Balance
      POST
    • Order Query
      POST
    • Fee Query
      POST
    • Refund Query
      POST
  • Dispute Management
    • Dispute Enums
    • Dispute Alert
    • Dispute Alert Callback
    • Dispute Prevention (RDR)
    • Dispute Management(Chargeback)
    • Chargeback Callback
  • Credit Card Issuer
    • Available Card
      POST
    • Open Card
      POST
    • Open/Recharge Card Callback
      POST
    • Get Card Detail
      POST
    • Card Recharge
      POST
    • Order List
      POST
    • Card List
      POST
    • Transaction List
      POST
    • Fee Query
      POST
  • Physical Card Issuer
    • Create Cardholder
    • List Cardholders
    • Assign Physical Cards
    • List Assigned Physical Cards
    • Query Card Balance
    • Query Card Transactions
    • Query Account
    • Card Charge
  • Schemas
    • VCardDetail
    • VOrderDetail
  1. Dispute Management

Dispute Alert

Customer guide | Based on the current TrustPay implementation | Updated 2026-07-30

Purpose#

A Dispute Alert is an early warning received before a cardholder complaint becomes a formal dispute. It gives the merchant time to review the transaction, stop fulfillment when appropriate, preserve evidence, or issue a normal refund under the merchant's risk policy.
A Dispute Alert is not a formal dispute and does not mean that a refund has already been completed.

Supported Alert Sources#

The current system supports:
ethoca
cdrn
RDR events use the same alert infrastructure but represent an automatic prevention result. See Dispute Prevention (RDR).

Order Matching#

TrustPay attempts to associate an alert with the original payment order:
1.
Match by ARN.
2.
If ARN matching fails, match by masked card identity, amount, currency, and transaction time.
3.
Assign the alert only when exactly one order is matched.
An unmatched or ambiguous alert is retained for internal review but is not:
displayed to a merchant;
billed to a merchant;
sent to a merchant callback URL.
Automatic matching currently covers configured C21 Markup Payin orders that support this capability.

After a Successful Match#

TrustPay:
1.
stores the alert and order association;
2.
records the configured per-alert merchant fee;
3.
sends a type = 7 callback to the original order notify_url after billing succeeds;
4.
displays the alert, fee, and notification status in the merchant portal.
The same alert is billed only once. Callback retries do not create duplicate billing.
The alert fee is deducted from the available balance. The current implementation allows the balance to become negative. A callback failure does not reverse an alert fee that was already recorded successfully.

What a Dispute Alert Does Not Do#

A Dispute Alert does not:
automatically refund the payment;
create a formal Dispute;
change the order's formal dispute status;
deduct formal dispute principal or a formal dispute processing fee;
automatically report a merchant outcome to the alert provider.
If the merchant decides to refund, use the existing refund flow and first confirm that the order has not entered a formal dispute.

Recommended Merchant Action#

1.
Review the order, amount, masked card number, ARN, reason code, and transaction time.
2.
Confirm whether goods or services have already been delivered.
3.
For clear fraud, duplicate billing, or an unrecognized transaction, decide whether to stop fulfillment and issue a normal refund.
4.
Preserve order, authorization, communication, delivery, and service-usage evidence.
5.
Process the alert callback idempotently by alert_id.

Related Documents#

Dispute Alert Callback — complete type = 7 callback contract.
Dispute Enums — alert source, category, match, fee, and notification values.
Dispute Prevention (RDR) — automatically prevented and refunded cases.
Dispute Management — formal dispute response and decision flow.
Modified at 2026-07-30 04:19:22
Previous
Dispute Enums
Next
Dispute Alert Callback
Built with