Chargeback Fraud and Disputes

// Inside your order-confirmation handler, after the charge succeeds.
// `risk` is what the shared waitForScore helper returns: the webhook `data`
// object, a History row mapped to the same field names when the webhook was late,
// or null. `userHid` is the hashed id you pass to the snippet; null for a guest.
async function recordOrder(order, requestId, risk, userHid) {
  // No identification: keep the request ID only.
  if (!risk) {
    await db.orders.update(order.id, { shieldlabs_request_id: requestId || null });
    return;
  }
  // Another account's identification: stamp nothing, so a dispute never replays it.
  if (userHid && risk.user_hid !== userHid) return;
  await db.orders.update(order.id, {
    // The identity stamp you will replay if this charge is ever disputed.
    shieldlabs_request_id:    requestId,                      // the exact identification
    shieldlabs_user_hid:      risk.user_hid,                  // the hashed account id you passed in
    shieldlabs_device_id:     risk.device_id,                 // holds through cleared cookies and incognito
    shieldlabs_score:         risk.risk_score,                // 0 to 100 at buy time
    shieldlabs_country:       risk.public_ip?.country,        // public IP country at buy time
    shieldlabs_local_country: risk.local_ip?.country || null, // Local IP country, webhook only
    // Named risk signals at buy time: webhook only, null on the History fallback.
    shieldlabs_signals:       risk.signals ? risk.signals.map((s) => s.name) : null,
  });
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// `dispute` carries the order id your processor (Stripe, Adyen, etc.) reported.
async function buildEvidence(dispute) {
  const order = await db.orders.get(dispute.orderId);
  // Every order this account placed, the disputed one included, from your own store.
  // Guest orders carry "anonymous", which is not an account: gather them by device
  // instead, and keep the disputed order alone when it has no usable Device ID.
  const hid = order.shieldlabs_user_hid;
  const dev = order.shieldlabs_device_id;
  const isAccount = hid && hid !== 'anonymous';
  const orders = isAccount
    ? await db.orders.byUserHid(hid)
    : dev && dev !== NIL_DEVICE
      ? await db.orders.byDeviceId(dev)
      : [order];

  const rows = [];
  for (const o of orders) {
    if (!o.shieldlabs_request_id) continue; // no identification stamped for this order
    await sleep(100); // the History API allows 15 requests per second per domain
    let s;
    try {
      // Each order's own identification, by the request_id stamped at purchase.
      [s] = await shieldlabsHistory('request_id', o.shieldlabs_request_id, 1);
    } catch {
      continue; // a failed read (a 429, for example): leave this order out, keep building
    }
    if (!s) continue;
    rows.push({
      order:       o.id,
      disputed:    o.id === order.id,
      when:        s.created_at,
      account:     s.user_hid,
      device:      s.device_id,
      country:     s.country,
      score:       s.score,              // History rows carry `score`
      browser:     s.browser,
      device_type: s.device_type,
      signals:     o.shieldlabs_signals, // named risk signals stamped at buy time
      // Same device as the disputed order. The all-zero Device ID carries
      // no device continuity, so it never counts.
      same_device: s.device_id === order.shieldlabs_device_id && s.device_id !== NIL_DEVICE,
    });
  }
  return rows;
}

async function accountIdentifications(userHid) {
  if (!userHid || userHid === 'anonymous') return []; // not an account
  const all = [];
  for (let offset = 0; ; offset += 100) {
    const page = await shieldlabsHistory('user_hid', userHid, 100, offset);
    all.push(...page);
    if (page.length < 100) return all; // the last page
    await sleep(100);
  }
}