Checkify
Utvecklardokumentation

Verifiera på din backend

När webbläsarinbäddningen är klar måste din server verifiera resultatet med en webbplatsnyckel API innan registrering, utcheckning eller någon skyddad åtgärd tillåts.

Serververifiering på 5 minuter

  1. Lägg till webbläsarinbäddningen Checkify på din sida.
  2. Inbäddningen startar Checkify-sessionen och skriver verifieringsreferensen i ditt formulär.
  3. Din backend läser det dolda fältvärdet.
  4. Din backend skickar det värdet till POST /v1/qr/results/verify som request_id.
  5. Om de nödvändiga anspråken godkänns, tillåt den skyddade åtgärden.
  6. Lita aldrig enbart på frontend-tillstånd.

Det dolda formulärfältet kan heta checkify_token, men dess värde är Checkify request_id.

Flöde från början till slut

1. Skapa en webbplatsnyckel API

I din företagsöversikt öppnar du Framkallare och skapa en webbplatsnyckel API för webbplatsen du integrerar. Lagra den endast i servermiljövariabler – skicka den aldrig till webbläsaren.

Använder du gränssnittet SDK?

Du behöver inte manuellt anropa GET /v1/qr/pass/{PASS_ID}/start. Checkify JavaScript inbäddningen startar sessionen, tar emot request_id och skriver det automatiskt till ditt formulär.

Din backend behöver bara:

2. Ta emot request_id på din server

Frontend-programmet SDK skriver Checkify request_id till ett dolt formulärfält efter att användaren har slutfört verifieringen. Standardfältnamnet är checkify_token — det vill säga fältnamnet, inte en separat tokentyp. Skicka fältvärdet till verifieringsslutpunkten som request_id.

Mobilappshandoff kan returnera checkify_request_id i sidans URL. SDK läser den vid laddning; din server verifierar fortfarande samma request_id-värde.

Formulär POST från ditt frontend

{
  "email": "user@example.com",
  "checkify_token": "56a57761-ff5b-42f0-9c97-6c13e223e017"
}

Verifiera begäran från din backend

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "required_fields": [],
  "consume": true
}

Endast manuell frontend-integration

3. Manuell testning med cURL

Backend-utvecklare anropar normalt inte /start. Använd endast det här avsnittet när du bygger ett anpassat frontend eller testar utan inbäddningen. Citera URL:er i zsh/bash så att ? inte behandlas som en glob.

Ursprungsrubrik krävs för /start

Pass start fungerar bara från en registrerad webbplatsdomän. Webbläsare skickar Origin automatiskt; cURL gör inte det. Skicka Origin (eller X-Checkify-Site-Url) med ett värdnamn som anges under Webbplatser → tillåtna domäner. Värdnamnet måste matcha exakt — checkify.me och www.checkify.me är olika.

Vanligaste testproblemet

Om /start returnerar HTTP 403 kan ditt lösenords-ID fortfarande vara giltigt. Den vanliga orsaken är att den begärda domänen inte finns med i listan över tillåtna domäner, eller att www.example.com registrerades men example.com användes (eller vice versa).

Använd en dedikerad testplats och kör Pass i din Checkify-instrumentpanel för integrationstestning. Platsens API-nycklar använder prefixet csk_; det finns inget separat testnyckelformat. Testa inte mot produktionsutcheckningen förrän du har bekräftat både lyckade och nekade flöden.

# Step A — start a session (replace PASS_ID and YOUR_REGISTERED_DOMAIN)
curl -sS \
  -H "Accept: application/json" \
  -H "Origin: https://YOUR_REGISTERED_DOMAIN" \
  "https://checkify.me/v1/qr/pass/chk_live_YOUR_PASS_ID/start?request_type=human"

# Response includes request_id and qr_url — open qr_url and complete verification

# Step B — verify on your server (after the user completes verification)
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "PASTE_request_id_FROM_STEP_A",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Använd endast din webbplats API-nyckel i verifieringssamtalet. Slutför verifieringen i appen innan du ringer verifieringssamtalet – annars får du statusen väntande.

Obligatoriska anspråk per användningsfall

Ställ in required_claims så att det matchar det bevis som din skyddade åtgärd behöver. Anspråksnamn måste matcha vad Checkify godkände för den verifieringssessionen. Ålderskontroller använder age_over_{N} (till exempel age_over_18). Dynamiska tröskelvärden från 10 till 110 stöds när inbäddningen begär matchande begärandetyp.

Användningsfall Föreslagna obligatoriska_anspråk Anteckningar
Bot / CAPTCHA ersättning ["human_verified"] Bekräftar att en riktig användare har slutfört Checkify-flödet.
13+ innehåll eller ungdomsinriktade produkter ["age_over_13"] Använd när ditt pass begär age_over_13.
Innehåll för personer över 16 år eller regionala åldersregler ["age_over_16"] Använd när ditt pass begär age_over_16.
Vape, alkohol eller 18+ utcheckning ["age_over_18"] Matcha åldersgränsen med din produkt och marknad.
21+ begränsade produkter (i förekommande fall) ["age_over_21"] Använd när ditt pass begär age_over_21.
Utmaning 25 eller strängare detaljhandelspolicy ["age_over_25"] Använd när ditt pass begär age_over_25.
Anpassad åldersgräns ["age_over_N"] Använd age_over_N där N är 10–110, i linje med din typ av inbäddningsförfrågan.

Bädda in begäran → serveranspråk

Webbläsarens begärandetyp måste matcha det anspråk som du verifierar på serversidan.

Typ av inbäddningsförfråganobligatoriska_anspråk
human["human_verified"]
age_over_13["age_over_13"]
age_over_16["age_over_16"]
age_over_18["age_over_18"]
age_over_21["age_over_21"]
age_over_25["age_over_25"]
age_over_N["age_over_N"] (N = 10–110)

Valfria obligatoriska fält

Förutom required_claims kan du kräva specifika godkända identitetsfält (till exempel land eller åldersgrupp) när din integration samlade in dem. Skicka fältnamn i required_fields — om några saknas i det godkända resultatet, returnerar verification_failed med missing_fields i error.details.

4. Anropa verifiering på din server

Anropa POST /v1/qr/results/verify med din webbplats API-nyckel innan du beviljar åtkomst. Behandla webbläsarreferensen (request_id eller äldre poll-token) som otillförlitlig tills Checkify bekräftar resultatet.

POST https://checkify.me/v1/qr/results/verify
Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "consume": true
}

Du kan också skicka token istället för request_id. Nyckeln API är begränsad till din Checkify-webbplats — du skickar inte site_id i begäran.

Implementeringsexempel

# checkify_token from your form POST is sent as request_id
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
    "required_claims": ["human_verified"],
    "consume": true
  }'

När man ska använda konsumera

Använd consume: true för slutliga skyddade åtgärder — utcheckning, registrering, lösenordsåterställning, åldersbegränsat köp, åtkomst till skyddat innehåll

Använd konsumera: falskt endast för — testning, felsökning eller icke-slutgiltiga kontroller där resultatet måste verifieras igen senare

För reglerade åtgärder eller åtgärder med hög risk, föredra consume: true så att samma verifieringsresultat inte kan återanvändas för flera skyddade beslut.

Fel stängt för reglerade åtgärder

Om din server inte kan nå Checkify, tillåt inte åldersbegränsad utcheckning, åtkomst till spel, åtkomst till vuxeninnehåll, köp av vape eller alkohol eller andra skyddade åtgärder utan ett bekräftat resultat på serversidan.

Använd korta HTTP-timeouts (till exempel 10 sekunder). Försök igen en eller två gånger för övergående 5xx- eller nätverksfel och neka sedan åtkomst. Logga incidenter på serversidan och visa användarsäkra meddelanden. Exponera inte interna Checkify-feldetaljer för kunder.

try {
  const verdict = await verifyCheckifyResult(requestId);

  if (!verdict.allow) {
    return res.status(403).json({ error: "Verification required" });
  }

  // Continue protected action
} catch (err) {
  console.error("Checkify verification unavailable", err);

  return res.status(403).json({
    error: "Verification is temporarily unavailable. Please try again.",
  });
}

Server SDKs och verktyg

Använd @checkify/server (npm) eller checkify-server (Python) för typskrivna verifieringshjälpare, eller anropa POST /v1/qr/results/verify direkt. Det finns ingen publicerad OpenAPI-specifikation ännu — använd exemplen på den här sidan.

@checkify/server v1.0.0 publiceras på npm. Python-paketet checkify-server levereras i monorepo Checkify SDK.

Resultatets utgångsfönster

Slutförda verifieringar upphör att gälla efter QR_RESULT_MAX_AGE_SECONDS (standard 900 sekunder / 15 minuter). Efter utgången returnerar verifieringen result_expired — ber användaren att verifiera igen.

Statusavsökningsslutpunkter (anpassade gränssnitt)

JavaScript SDK hanterar sessionsstatus för standardinbäddningar. Använd dessa endast när du bygger ett anpassat gränssnitt som anropar GET /v1/qr/pass/{pass_id}/start manuellt.

Svarshantering

Vid lyckat resultat returnerar Checkify HTTP 200 med success: true och status: completed. Tillåt endast åtkomst när obligatoriska anspråk finns (till exempel human_verified: true).

{
  "success": true,
  "status": "completed",
  "message": "Verification result confirmed",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "site_id": "YOUR_SITE_ID",
  "business_id": "YOUR_BUSINESS_ID",
  "approved_claims": {
    "human_verified": true
  },
  "approved_fields": [],
  "signed_result": {
    "payload": { "...": "..." },
    "signature": "...",
    "signature_algorithm": "EdDSA",
    "key_id": "checkify:default"
  }
}

Signerat resultat

Objektet signed_result låter din backend föra en manipulationssäker revisionspost som visar att Checkify godkände det obligatoriska anspråket vid verifieringstillfället. De flesta integrationer behöver bara approved_claims. Reglerade eller högriskföretag kan också lagra signed_result för revision. Lagra inte mer personlig information än nödvändigt.

Om kunden inte är klar i appen än returnerar Checkify HTTP 200 med framgång: falskt och status: väntande. Neka skyddade åtgärder och be användaren att slutföra verifieringen.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
FältMenande
successtrue när verifieringen är klar och kraven uppfyllda
statuscompleted eller pending
approved_claimsGodkända påståenden Checkify, t.ex. human_verified: true
signed_resultValfri signerad nyttolast för revisionsspår

JSON felnyttolaster

När verifieringen inte kan fortsätta returnerar Checkify HTTP 4xx/5xx med en strukturerad JSON-text. Kontrollera error.code och logga error.details på serversidan. Returnera generiska meddelanden till slutanvändare.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
Koda HTTP Menande Rekommenderad åtgärd
missing_authorization401Ingen auktoriseringsrubrik skickades.Skicka auktorisering: Bärare YOUR_SITE_API_KEY endast från serverkod.
invalid_token401Bearer-token saknas, är felaktigt utformad eller inte en giltig webbplats-API-nyckel.Verifiera nyckeln i din affärsinstrumentpanel och lagra den i miljövariabler.
expired_token401Webbplatsens nyckel API har återkallats.Skapa en ny webbplatsnyckel API och rotera den på dina servrar.
missing_required_field400 / 422request_id eller token saknas i JSON-texten.Skicka request_id från ditt dolda formulärfält, eller poll-token om din integration fortfarande använder det.
invalid_request_id400Referensen kunde inte tolkas eller är tom efter normalisering.Se till att ditt användargränssnitt skickar in Checkify request_id oförändrat.
result_not_found404Det finns ingen verifieringsbegäran för den referensen.Avvisa åtgärden. Användaren kan ha manipulerat det dolda fältet eller skickat in en gammal session.
result_expired410Verifieringen slutfördes för länge sedan för att kunna litas på den här åtgärden.Be användaren att skanna igen och anropa verifiering med det nya request_id.
verification_failed403 / 409Verifieringen är klar men uppfyllde inte dina obligatoriska anspråk/fält, tillhör en annan webbplats eller har redan förbrukats.Neka åtkomst. Kontrollera error.details för missing_claims, missing_fields eller orsak.
missing_required_claims403developers_server.err_missing_required_claims_meaningdevelopers_server.err_missing_required_claims_action
missing_required_fields403developers_server.err_missing_required_fields_meaningdevelopers_server.err_missing_required_fields_action
unknown_required_attributes400developers_server.err_unknown_required_attributes_meaningdevelopers_server.err_unknown_required_attributes_action
business_not_operational403Företagskontot är låst, arkiverat eller inte i bruk.Kontakta företagsägaren eller Checkify-supporten. Tillåt inte skyddade åtgärder förrän kontot är aktivt.
validation_errors422Schemavalideringen av JSON-texten misslyckades (HTTP 422).Kontrollera error.details.validation_errors för meddelanden på fältnivå. Åtgärda typerna request_id, required_claims eller required_fields innan du försöker igen.
rate_limited429För många verifieringssamtal inom ett kort tidsfönster.Försök igen med exponentiell backoff. Verifiera endast vid skyddade åtgärder, inte vid varje sidvisning.
server_error500+Checkify kunde inte slutföra verifieringen på grund av ett tillfälligt serverproblem.Försök igen en eller två gånger, stäng sedan felet och logga incidenten.

Webhooks och asynkron verifiering

Idag är serververifiering synkron: din backend verifierar request_id när användaren skickar den skyddade åtgärden. För utcheckning, registrering och åtkomstkontrollflöden är detta den rekommenderade metoden. Webhooks för allmän verifiering krävs inte för standardintegrationer. GoHighLevel och andra partnerintegrationer kan använda separat utgående webhook-konfiguration i affärsinstrumentpanelen.

Vanliga misstag

Säkerhetspåminnelse

Behandla det dolda fältet som en opålitlig referens, inte ett bevis. Verifiera alltid med din webbplats API-nyckel på servern innan du beviljar åtkomst. consume: true för engångsåtgärder som registrering eller lösenordsåterställning.

Nästa steg