Payment Fraud at Checkout

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // The browser does NOT compute the Risk Score. Keep result.requestID:
  // join key to the webhook.
  mod.forceCheckAuthenticatedUser('a1b2c3d4hasheduserid', {
    onInitialized: (result) => {
      if (result.status !== 'initialized') return;
      document.getElementById('shieldlabs-request-id').value = result.requestID;
    },
  });
</script>

<form id="checkout-form" method="POST" action="/api/checkout">
  <input type="hidden" id="shieldlabs-request-id" name="shieldlabsRequestId" />
  <!-- payment fields -->
  <button type="submit">Pay</button>
</form>

// Inside /api/checkout, once you have `risk` for this payment.
// accountView reads the account's newest 100 identifications by user_hid,
// without this payment and without the 999 rate-limit marker.
// account.worstBand: 'Dangerous' means the account has been risky before,
// whatever this payment scores (null when it has no earlier identifications).
// accountView throws when the History read fails; the full handler below
// routes that payment to review.
const account = await accountView(userHid, { excludeRequestId: risk.request_id });

// A device new to an established account: the account completed verified actions
// on other devices, not on this one. trustedDevices is your own store, filled by
// rememberTrustedDevice (Returning Visitor Recognition) after a verified action.
const knownDevices = await trustedDevices.list(userId); // a Set of Device IDs
const newDevice = knownDevices.size > 0 && !knownDevices.has(risk.device_id);

app.post('/api/checkout', async (req, res) => {
  const { shieldlabsRequestId, paymentData, userId } = req.body;
  // The same hashing you apply before passing the id to the snippet; null for a guest checkout.
  const userHid = userId ? hashAccountId(userId) : null;

  // Wait up to ~2s for the webhook; falls back to the History API.
  const risk = await waitForScore(shieldlabsRequestId, 2000);

  // No identification for this payment: hold rather than charge on missing data.
  if (!risk) {
    return res.status(202).json({ status: 'review', reason: 'no_identification' });
  }
  // A signed-in buyer's identification must be theirs. Guests send "anonymous".
  if (userHid && risk.user_hid !== userHid) {
    return res.status(202).json({ status: 'review', reason: 'identification_mismatch' });
  }
  // The 999 rate-limit marker, or no usable Device ID: hold for review.
  if (risk.risk_score > 100 || !risk.device_id || risk.device_id === NIL_DEVICE) {
    return res.status(202).json({ status: 'review', reason: 'unverified_device' });
  }
  const score = risk.risk_score;
  const flags = risk.detection_flags ?? {}; // used by the hard rules below

  // The buyer's account, without this payment, and its trusted devices (previous step).
  // A guest checkout has neither. A failed History read is unverified: hold for review.
  let account = null;
  if (userHid) {
    try {
      account = await accountView(userHid, { excludeRequestId: risk.request_id });
    } catch {
      return res.status(202).json({ status: 'review', reason: 'history_unavailable' });
    }
  }
  const knownDevices = userHid ? await trustedDevices.list(userId) : new Set();
  const newDevice = knownDevices.size > 0 && !knownDevices.has(risk.device_id);
  // Accounts you marked after a High-Risk Event reached you through the API,
  // webhooks or the analytics dashboard.
  const marked = userHid ? await markedAccounts.has(userHid) : false; // your own store

  // Dangerous payment, a Dangerous history or a marked account: hold for review.
  if (score >= 60 || account?.worstBand === 'Dangerous' || marked) {
    await flagForReview(userId, risk);
    return res.status(202).json({ status: 'review', reason: 'dangerous_or_marked' });
  }

  // Suspicious payment, or a device new to an established account: step up.
  if (score >= 30 || newDevice) {
    return res.status(202).json({ status: 'step_up', method: '3ds' });
  }

  // Trusted payment on a device from the account's trust list (or a trust list that is
  // still empty): charge in your own flow. After a successful charge, add the device
  // with rememberTrustedDevice(userId, risk).
  return processPayment(paymentData, userId, res);
});