squadbenchjs

Official JavaScript SDK for Benchmark — secure escrow, vendor trust verification, and payment infrastructure for e-commerce platforms.

Installation

npm install squadbenchjs

Quick Start

const Benchmark = require('squadbenchjs');

const benchmark = new Benchmark({
  apiKey: process.env.BENCHMARK_API_KEY,
  baseUrl: 'https://api.benchmark.dev',
  webhookSecret: process.env.BENCHMARK_WEBHOOK_SECRET,
});

Getting Started

For Marketplaces and Platforms

1. Create a developer account
2. Generate your API key
3. Initialize the SDK
4. Start creating escrow transactions and verifying vendors

const Benchmark = require('squadbenchjs');

const benchmark = new Benchmark({
  apiKey: process.env.BENCHMARK_API_KEY,
  baseUrl: 'https://api.benchmark.dev',
});

For Vendors

const Benchmark = require('squadbenchjs');

const benchmark = new Benchmark({
  baseUrl: 'https://api.benchmark.dev',
});

const { vendor, token } = await benchmark.vendors.register({
  business_name: 'Chukwu Electronics',
  category: 'Electronics',
  phone: '+2348012345678',
  payout_account_number: '0123456789',
  payout_bank_code: '000013',
  location_state: 'Lagos',
});

SDK Initialization

const Benchmark = require('squadbenchjs');

const benchmark = new Benchmark({
  apiKey: process.env.BENCHMARK_API_KEY,
  baseUrl: 'https://api.benchmark.dev',
  webhookSecret: process.env.BENCHMARK_WEBHOOK_SECRET,
  timeout: 30000,
});

Configuration Options

| Option | Type | Required | Description | | --------------- | ------ | ------------- | ---------------------------- | | apiKey | string | Platform only | Your Benchmark API key | | baseUrl | string | Yes | Benchmark backend URL | | webhookSecret | string | Webhooks only | Squad webhook secret | | timeout | number | No | HTTP timeout in milliseconds |

Vendors API

Register Vendor

const { vendor, token, api_key } = await benchmark.vendors.register({
  business_name: 'Chukwu Electronics',
  category: 'Electronics',
  phone: '+2348012345678',
  nin: '12345678901',
  payout_account_number: '0123456789',
  payout_bank_code: '000013',
  location_state: 'Lagos',
});

Response

{
  "vendor": {
    "id": "vendor-uuid",
    "business_name": "Chukwu Electronics",
    "trust_score": 72
  },
  "token": "jwt-token",
  "api_key": "vendor-api-key"
}

Start Verification

const { session_id, instructions } =
  await benchmark.vendors.startVerification();

Submit Verification Frame

const result = await benchmark.vendors.submitFrame(
  session_id,
  base64Frame
);

console.log(result.progress);
console.log(result.blink_detected);
console.log(result.face_distance);

Complete Verification

const result = await benchmark.vendors.completeVerification(session_id);

console.log(result.verification_status);
console.log(result.confidence_percent);
console.log(result.trust_score);
console.log(result.score_tier);

Get Vendor Score

const score = await benchmark.vendors.getScore('vendor-uuid');

console.log(score);

Example Response

{
  "business_name": "Chukwu Electronics",
  "trust_score": 82,
  "score_tier": "Trusted Seller"
}

Get Current Vendor Score

const myScore = await benchmark.vendors.myScore();

List Vendors

const { vendors, count } = await benchmark.vendors.list({
  category: 'Fashion',
  location_state: 'Lagos',
  badge: 'Trusted Seller',
  page: 1,
  limit: 20,
});

Get Vendor Badge

const svgMarkup = await benchmark.vendors.getBadge('vendor-uuid');

document.getElementById('badge').innerHTML = svgMarkup;

Get Supported Banks

const { banks } = await benchmark.vendors.banks();

console.log(banks);

Example Response

[
  {
    "code": "000013",
    "name": "GTBank"
  }
]

Escrow API

Create Escrow Transaction

const escrow = await benchmark.escrow.create({
  vendor_id: 'vendor-uuid',
  amount: 45000,
  item_description: 'Samsung Galaxy A54',
  buyer_phone: '+2348099999999',
  buyer_email: '[email protected]',
});

console.log(escrow.checkout_url);
console.log(escrow.transaction_id);

Example Response

{
  "transaction_id": "txn_123456",
  "checkout_url": "https://checkout.squadco.com/pay/...",
  "confirmation_token": "confirm_token",
  "squad_va_account": "1234567890"
}

Get Escrow Transaction

const transaction = await benchmark.escrow.get(
  confirmationToken
);

console.log(transaction);

Confirm Delivery

const result = await benchmark.escrow.confirmDelivery(
  confirmationToken
);

console.log(result.escrow_status);

Submit Dispute

const dispute = await benchmark.escrow.dispute(
  transactionId,
  'I never received my package. Seller stopped responding.'
);

console.log(dispute.category);
console.log(dispute.status);

Example Response

{
  "dispute_id": "disp_123",
  "category": "non-delivery",
  "confidence": 0.91,
  "status": "auto-resolved"
}

B2B API

Get Vendor Score

const score = await benchmark.b2b.getVendorScore('vendor-uuid');

List Verified Vendors

const vendors = await benchmark.b2b.listVendors({
  category: 'Electronics',
  location_state: 'Lagos',
  page: 1,
  limit: 20,
});

Create Escrow on Behalf of Vendor

const escrow = await benchmark.b2b.createEscrow({
  vendor_id: 'vendor-uuid',
  amount: 25000,
  item_description: 'Order #12345',
  buyer_phone: '+2348088888888',
  buyer_email: '[email protected]',
});

Release Escrow Programmatically

await benchmark.b2b.releaseEscrow(
  transactionId,
  confirmationToken
);

Webhooks

Validate Webhook Signature

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = benchmark.webhooks.validate(
    req.body.toString(),
    req.headers['x-squad-signature']
  );

  if (!valid) {
    return res.status(401).send('Invalid signature');
  }

  const event = benchmark.webhooks.parse(req.body);

  console.log(event);

  res.sendStatus(200);
});

Parse Webhook Event

const event = benchmark.webhooks.parse(req.body);

switch (event.event) {
  case benchmark.webhooks.events.CHARGE_SUCCESSFUL:
    console.log(`Payment successful: NGN ${event.amount}`);
    break;

  case benchmark.webhooks.events.TRANSFER_SUCCESS:
    console.log(`Transfer sent: ${event.transactionRef}`);
    break;
}

Escrow Lifecycle

pending
  → funded
  → released

OR

pending
  → disputed
  → refunded

Error Handling

All SDK methods throw structured errors.

try {
  await benchmark.escrow.create({
    amount: 50000,
  });
} catch (err) {
  console.error(err.message);
  console.error(err.status);
  console.error(err.errors);
  console.error(err.raw);
}

Common Status Codes

| Status | Meaning | | ------ | ----------------------------------- | | 401 | Invalid or missing API key | | 403 | Access denied or plan limit reached | | 422 | Validation failed | | 429 | Rate limit exceeded | | 502 | Payment provider error |

Security Best Practices

Use Environment Variables

const benchmark = new Benchmark({
  apiKey: process.env.BENCHMARK_API_KEY,
});

Always Validate Webhooks

if (!benchmark.webhooks.validate(rawBody, signature)) {
  return res.status(401).send('Invalid signature');
}

Rate Limits

| Plan | API Calls | | ---------- | --------------- | | Free | 10,000/month | | Starter | 100,000/month | | Growth | 1,000,000/month | | Enterprise | Unlimited |

Support

• Documentation: https://docs.benchmark.dev
• npm Package: https://www.npmjs.com/package/squadbenchjs
• Email: [email protected]

License

MIT