API Reference

Complete documentation for the Benchmark API and squadbenchjs SDK.

npm install squadbenchjs

Vendors API

Endpoints for vendor registration, verification, and trust score management.

POST/vendors/register

Register a new vendor and initiate the verification process.

// Request Body
{
  "business_name": "Chukwu Electronics",    // required
  "category": "Electronics",                // required
  "phone": "+2348012345678",                // required
  "nin": "12345678901",                     // required
  "payout_account_number": "0123456789",    // required
  "payout_bank_code": "000013",             // required
  "location_state": "Lagos"                 // required
}

// Response
{
  "vendor": {
    "id": "vendor_uuid",
    "business_name": "Chukwu Electronics",
    "trust_score": 72,
    "score_tier": "Verified Seller"
  },
  "token": "jwt_token",
  "api_key": "vendor_api_key"
}
POST/vendors/verification/start

Start the AI liveness verification session. Returns a session ID for frame submission.

// Request (requires vendor JWT token)
{
  "redirect_url": "https://your-app.com/verification-callback"
}

// Response
{
  "session_id": "sess_123456",
  "instructions": {
    "blink_required": true,
    "head_turn_required": true
  }
}
GET/vendors/:id/score

Get a vendor's current trust score and badge tier.

// Response
{
  "business_name": "Chukwu Electronics",
  "trust_score": 82,
  "score_tier": "Trusted Seller",
  "badge_svg_url": "https://api.benchmark.dev/badges/trusted-seller.svg"
}

Escrow API

Endpoints for creating and managing escrow transactions powered by Squad virtual accounts.

POST/escrow/create

Create a new escrow transaction. Generates a Squad checkout URL.

// Request Body
{
  "vendor_id": "vendor_uuid",           // required
  "amount": 45000,                      // required (in NGN)
  "item_description": "Samsung Galaxy A54", // required
  "buyer_phone": "+2348099999999",      // required
  "buyer_email": "buyer@example.com"    // optional
}

// Response
{
  "transaction_id": "txn_123456",
  "checkout_url": "https://checkout.squadco.com/pay/...",
  "confirmation_token": "confirm_token",
  "squad_va_account": "1234567890",
  "expires_at": "2026-05-20T12:00:00Z"
}
POST/escrow/confirm-delivery

Confirm delivery and trigger fund release to vendor via Squad Transfer API.

// Request Body
{
  "confirmation_token": "confirm_token",  // required
  "delivery_proof_url": "https://..."     // optional
}

// Response
{
  "escrow_status": "released",
  "transfer_reference": "trf_789012",
  "released_at": "2026-05-16T14:30:00Z"
}
POST/escrow/dispute

Submit a dispute. AI (distilBERT) classifies and auto-resolves if confidence >85%.

// Request Body
{
  "transaction_id": "txn_123456",        // required
  "reason": "I never received my package. Seller stopped responding."  // required
}

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

B2B API

For marketplaces and platforms — manage vendors and escrow programmatically.

POST/b2b/escrow/create

Create an escrow on behalf of a verified vendor (requires platform API key).

// Request Body
{
  "vendor_id": "vendor_uuid",           // required
  "amount": 25000,                      // required
  "item_description": "Order #12345",   // required
  "buyer_phone": "+2348088888888",      // required
  "buyer_email": "buyer@marketplace.com" // optional
}

// Response (same as /escrow/create)
{
  "transaction_id": "txn_789012",
  "checkout_url": "https://checkout.squadco.com/pay/...",
  "confirmation_token": "confirm_token"
}
GET/b2b/vendors

List verified vendors with optional filters.

// Query Parameters
?category=Electronics
&location_state=Lagos
&badge=Trusted Seller
&page=1
&limit=20

// Response
{
  "vendors": [...],
  "count": 47,
  "page": 1,
  "total_pages": 3
}

Webhooks

Squad webhooks forwarded by Benchmark. Always validate signatures.

POST /webhook (configured in your dashboard)
// Event: charge.successful (payment received into escrow)
{
  "event": "charge.successful",
  "transaction_id": "txn_123456",
  "amount": 45000,
  "currency": "NGN",
  "squad_reference": "sq_ref_123",
  "customer_phone": "+2348099999999"
}

// Event: transfer.success (funds released to vendor)
{
  "event": "transfer.success",
  "transaction_id": "txn_123456",
  "transfer_reference": "trf_789012",
  "amount": 45000,
  "vendor_account": "0123456789"
}

// Event: dispute.resolved (AI decision made)
{
  "event": "dispute.resolved",
  "dispute_id": "disp_123",
  "transaction_id": "txn_123456",
  "resolution": "buyer_wins",
  "confidence": 0.91,
  "auto_resolved": true
}

⚠️ Always validate webhook signatures:

const isValid = benchmark.webhooks.validate(rawBody, req.headers['x-squad-signature']);

SDK Methods Summary

benchmark.vendors.register() — Register vendor
benchmark.vendors.startVerification() — Start AI liveness
benchmark.vendors.submitFrame() — Submit face frame
benchmark.vendors.completeVerification() — Complete check
benchmark.vendors.getScore() — Get trust score
benchmark.vendors.getBadge() — Get SVG badge
benchmark.escrow.create() — Create escrow
benchmark.escrow.confirmDelivery() — Release funds
benchmark.escrow.dispute() — Submit dispute (AI)
benchmark.b2b.createEscrow() — Platform escrow
benchmark.b2b.listVendors() — List vendors
benchmark.webhooks.validate() — Verify signatures