Chargeback disputes

Show the device history behind a disputed order.

10 minutes

"I never ordered that." Trace keeps the device history behind each account, so you can show the same browser placed earlier orders the customer did not dispute.

What you will build: a check on the action you protect that allows normal users, asks doubtful ones to verify, and blocks the clear cases. See the chargeback disputes overview for the attack in pictures.

Before you start

Finish one Web quickstart (for example JavaScript or React) and one Server quickstart (for example Node.js). The decision code below is TypeScript; every server SDK returns the same event.

How the attack works

  • Friendly fraud. A real order, disputed after delivery.
  • Family purchases. Someone else in the house used the card.
  • Weak evidence. An IP address alone rarely wins a dispute.

What to look at

FieldWhy it matters here
visitorIdThe same browser across orders. Stable id of this browser, through private windows and cleared cookies.
historyGET /v1/visitors/:id lists past events. Past events of a visitor: GET /v1/visitors/:visitorId.
  1. 1

    Identify on the action

    Call the browser SDK when the user performs the action, not on page load, and send the eventId with the request.

    TypeScript
    const { eventId } = await trace.get({ tags: { action: 'chargebacks' } });
  2. 2

    Verify on your server

    import { verifyEvent } from '@trace-id/sdk-node';
    
    const event = await verifyEvent(eventId, { secretKey: process.env.TRACE_SECRET_KEY!, endpoint, timeoutMs: 1500 }).catch(() => null);

    Events can be verified for 60 minutes. If verification fails, decide whether to fail open or closed; for most of this flow, fail open.

  3. 3

    Decide

    TypeScript
    // at checkout: keep the visitor with the order
    const event = await trace.verify(eventId);
    await db.orders.update(orderId, { visitorId: event.visitorId });
    
    // on a dispute: past orders from the same browser
    const sameDevice = await db.orders.find({ visitorId: order.visitorId, disputed: false });

    trace.verify() is the embedded call; with a server SDK, use the event from step 2 instead. The thresholds are yours. Trace scores and explains; event.reasons lists which signals added how much, so log it with every decision.

Example decisions

Orders on one disputed account, illustrative:

OrderDeviceDecisionWhy
#10214Device AAllowDelivered, not disputed
#10560Device AAllowDelivered, not disputed
#11032Device AVerifyDisputed: same visitorId as past orders

Roll it out

  1. Ship steps 1 to 3 with logging only: record the decision, block nothing.
  2. After a week, look at who would have been blocked or asked to verify. Shared computers, offices and privacy tools are the usual false positives.
  3. Turn on Verify first, then Block for the clearest cases.
Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.