Lumaktaw sa pangunahing nilalaman
ShieldID

Quickstart

Ang quickstart para sa identity verification.

Mula sandbox key hanggang unang signed webhook, ayon sa pagkakasunod-sunod. May gumaganang halimbawa ang bawat hakbang — kopyahin ito, palitan ng sarili mong key at mga URL, at patakbuhin.

Humiling ng sandbox keyBuong API reference

Hakbang-hakbang

Pitong hakbang, isang hapon.

  1. Kumuha ng sandbox key

    Ang mga sandbox key (prefix na vk_sand_) ay ibinibigay kapag hiniling habang binubuo pa ang self-serve signup. Humiling sa pamamagitan ng contact form — karamihan ng request ay naaasikaso sa parehong business day. Hindi kailanman sinisingil ang mga sandbox session, kaya walang dahilan para maghintay bago magsimula.

  2. Gawin ang iyong unang session

    Isang call lang. Magpadala ng return_url (kung saan mapupunta ang applicant pagkatapos nila) at ng webhook_url (kung saan ipapadala ang naka-sign na resulta). Makakatanggap ka ng session_id at verification_url.

    bash
    curl -X POST https://api.shieldid.ca/v1/sessions \
  -H "X-Api-Key: vk_sand_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.example/verified",
    "webhook_url": "https://yourapp.example/hooks/shieldid",
    "expected_name": "Jordan Smith",
    "locale": "en",
    "metadata": { "application_id": "app_9182" }
  }'

  3. Ibigay sa applicant ang link

    Buksan ang verification_url at makikita mo ang hosted page. Sa desktop browser, may QR code na lalabas — kapag ini-scan ito, mapupunta ang eksaktong parehong link sa phone, kung saan nagaganap ang aktwal na photo ng dokumento, liveness challenge at selfie. Subukan ito sa sarili mong phone ngayon din.

  4. Mag-set up ng webhook endpoint

    Ituro ang webhook_url sa isang route na tumatanggap ng POST, bumabasa ng raw request body (kailangan itong hindi pa naka-parse para ma-check ang signature), at nagbabalik ng 2xx status. Kapag iba ang naging tugon, susubukan ulit ng ShieldID ang delivery hanggang tatlong beses.

    javascript
    import express from "express";
const app = express();

app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  // Verify the signature before you trust this body — see the next step.
  console.log("Received a webhook:", req.body.toString());
  res.status(200).send("ok");
});

app.listen(3000);

  5. I-verify ang signature

    Huwag kumilos batay sa webhook body hangga't hindi mo nakukumpirmang tunay itong galing sa ShieldID. Mag-compute ng HMAC-SHA256 sa raw body gamit ang iyong webhook secret at ihambing ito sa X-Bio-Signature header.

    javascript
    import crypto from "node:crypto";

function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader || "";
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
  if (!ok) return res.status(401).send("invalid signature");

  const result = JSON.parse(req.body);
  // result.session_id, result.status, result.checks, …
  res.status(200).send("ok");
});

  6. Basahin ang resulta

    Nasa webhook payload na ang lahat ng kailangan mo. Kung mas gusto mong kunin mismo ang resulta — halimbawa, pagkatapos ng redirect — tawagin nang direkta ang result endpoint.

    bash
    curl https://api.shieldid.ca/v1/sessions/ses_9f2c1a/result \
  -H "X-Api-Key: vk_sand_your_key"

# → { "session_id": "ses_9f2c1a", "status": "VERIFIED", "checks": { "document": "PASS", … }, … }

  7. Paghawak sa FAILED at sa retry

    Ang session na umabot sa FAILED ay may kasamang failure_reason. Magpakita sa applicant ng kapaki-pakinabang na mensahe. Malapit na: ang pag-retry ng FAILED na session para ibalik ito sa PENDING. Sa ngayon, ituring na terminal ang FAILED at gumawa ng bagong session kung nais ng applicant na subukan ulit.

Bago mo i-activate

Mag-production na.

Hindi nagbabago ang hugis ng request sa pagitan ng sandbox at production — ang key lang. Tiyakin ang mga ito bago magpadaan ng totoong applicant sa isang vk_live_ session.

  • Palitan ang vk_sand_ ng vk_live_ key. Wala nang ibang magbabago sa request.
  • Ituro ang webhook_url sa totoong endpoint na laging naka-on at nagve-verify ng signature — hindi sa request-bin o laptop.
  • Asikasuhin ang lahat ng tatlong terminal state sa iyong app: VERIFIED, FAILED at EXPIRED, hindi lang ang masayang resulta.
  • Tiyaking binabasa ng iyong return_url ang mga query parameter na session_id at status na idinadagdag ng ShieldID sa redirect.
  • Tingnan ang kasalukuyang presyo gamit ang GET /v1/pricing/{country} o ang pricing page, para hindi ka magulat sa singil sa production.
  • Ilayo ang mga sandbox key sa anumang maaabot ng totoong applicant — libre ang sandbox session dahil hindi ito totoo.

Mga Tanong

FAQ ng Quickstart.

Magsimula

Patakbuhin na ngayon ang unang hakbang.

Humiling ng sandbox key, i-paste ang unang cURL command sa terminal, at nauuna ka na sa karamihan ng mga integration.

Humiling ng sandbox keyBuong API reference