@mystoq/fakeshield

COD fraud screening for Algerian e-commerce. Score an order before you ship it.

In cash-on-delivery, a fake order costs you the outbound freight, the return freight, the packaging and your team's time. FakeShield checks the buyer's number against a shared network ledger and gives you one of three answers: ship, call first, or don't.

Works with any stack. You do not need a Mystoq store.

👉 Get your instant beta API key: https://mystoq.com/fakeshield/beta

npm i @mystoq/fakeshield

Quickstart

import { FakeShield } from '@mystoq/fakeshield';

const fs = new FakeShield(process.env.FAKESHIELD_KEY!);

const { score, tier, recommend, signals } = await fs.check({
  phone: '0555123456',
  name: 'سامية بن يحيى',
  address: 'حي الشهداء، عمارة 4، عنابة',
  wilaya: 23,
  amount: 8400,
});

if (tier === 'reject') {
  // The network has real evidence against this buyer.
  return refuse();
}
if (tier === 'call') {
  return queueForPhoneConfirmation();
}
await ship();

signals explains the verdict — every weight that moved the score:

[
  { "k": "الشبكة", "v": "3 توصيلات عبر متجرين", "c": "ok", "w": -18 },
  { "k": "IP", "v": "سكني", "c": "ok", "w": 0 },
  { "k": "العنوان", "v": "مبهم", "c": "warn", "w": 6 }
]

Report what happened

This is the part that matters. The network is only as good as the outcomes fed back into it — and delivered outcomes count as much as refusals, because they are what keeps an honest buyer out of a bad tier.

await fs.reportOutcome({
  phone: '0555123456',
  order_ref: 'ORD-2291',   // your own reference
  outcome: 'delivered',    // delivered | returned | cancelled | refused
});

Idempotent on order_ref — replaying it is a no-op, so it is safe to call from a webhook or a retrying queue.

Never ship a key to the browser

An API key identifies you, and buyer records are personal data. Call FakeShield from your server, never from checkout JavaScript.

// app/api/check/route.ts — server side
const fs = new FakeShield(process.env.FAKESHIELD_KEY!);

Errors

import { FakeShieldError } from '@mystoq/fakeshield';

try {
  await fs.check({ phone });
} catch (err) {
  if (err instanceof FakeShieldError) {
    if (err.isQuotaExceeded) {
      // Daily free-tier limit reached — ship on your own policy, don't block the order.
    }
    console.error(err.status, err.code, err.message);
  }
}

Network errors and 5xx are retried twice with backoff. 4xx is not retried — the answer will not change.

Fail open. If FakeShield is unreachable, do not block the sale. Screening is an assist, not a gate.

Options

new FakeShield({
  apiKey: process.env.FAKESHIELD_KEY!,
  timeoutMs: 8000,   // default
  retries: 2,        // default
  baseUrl: 'https://mystoq.com/api',
});

What it will not do

• It will not invent a score for a number it has never seen. Unknown means unknown; a new buyer starts clean.
• A single merchant's report never brands a buyer. Flags require independent corroboration, and reporters who contradict the network lose their weight.
• It exposes no buyer's order history. You get a verdict, not someone's life.

Links

• Get an API key (instant): https://mystoq.com/fakeshield/beta
• API reference: https://mystoq.com/fakeshield/docs
• Methodology, signal reference and appeals: https://mystoq.com/fakeshield/methodology

Licence

MIT — TKAWEN, Annaba, Algeria.