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.
Det dolda formulärfältet kan heta checkify_token, men dess värde är Checkify request_id.
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.
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:
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
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.
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.
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. |
Webbläsarens begärandetyp måste matcha det anspråk som du verifierar på serversidan.
| Typ av inbäddningsförfrågan | obligatoriska_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) |
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.
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.
# 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
}'
import express from "express";
const app = express();
app.use(express.json());
const CHECKIFY_API_KEY = process.env.CHECKIFY_API_KEY;
const CHECKIFY_BASE_URL = process.env.CHECKIFY_BASE_URL || "https://checkify.me";
async function verifyCheckifyResult(requestId, requiredClaims = ["human_verified"]) {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);
try {
const res = await fetch(`${CHECKIFY_BASE_URL}/v1/qr/results/verify`, {
method: "POST",
headers: {
Authorization: `Bearer ${CHECKIFY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
request_id: requestId,
required_claims: requiredClaims,
consume: true,
}),
signal: controller.signal,
});
let body = null;
try {
body = await res.json();
} catch {
body = null;
}
if (!res.ok) {
const details = body?.error?.details || {};
console.warn("Checkify verification failed", {
requestId,
code: body?.error?.code,
missingClaims: details.missing_claims,
missingFields: details.missing_fields,
reason: details.reason,
});
return {
allow: false,
reason: body?.error?.code || "verification_failed",
userMessage: "Verification could not be completed for this action.",
};
}
if (!body || body.status === "pending" || body.success === false) {
return {
allow: false,
reason: body?.status || "pending",
userMessage: "Verification could not be completed for this action.",
};
}
const approved = requiredClaims.every(
(claim) => body.approved_claims?.[claim] === true
);
return {
allow: approved,
reason: approved ? "approved" : "verification_failed",
userMessage: approved
? null
: "Verification could not be completed for this action.",
result: body,
};
} finally {
clearTimeout(timeout);
}
}
app.post("/signup", async (req, res) => {
const requestId = (req.body.checkify_token || "").trim();
if (!requestId) {
return res.status(403).json({ error: "Verification required" });
}
try {
const verdict = await verifyCheckifyResult(requestId);
if (!verdict.allow) {
return res.status(403).json({ error: verdict.userMessage });
}
return res.json({ ok: true });
} catch (err) {
console.error("Checkify verification unavailable", err);
return res.status(403).json({
error: "Verification is temporarily unavailable. Please try again.",
});
}
});
import { Checkify } from "@checkify/server";
const checkify = new Checkify({
apiKey: process.env.CHECKIFY_SITE_API_KEY,
});
app.post("/signup", async (req, res) => {
const requestId = String(req.body.checkify_token || "").trim();
if (!requestId) {
return res.status(403).json({ error: "Verification required" });
}
try {
const result = await checkify.verifyHuman({ requestId, consume: true });
if (!result.success || !result.approved) {
return res.status(403).json({
error: "Verification could not be completed for this action.",
});
}
return res.json({ ok: true });
} catch (err) {
console.error("Checkify verification failed", err);
return res.status(403).json({
error: "Verification is temporarily unavailable. Please try again.",
});
}
});
import os
import httpx
from fastapi import FastAPI, HTTPException
app = FastAPI()
CHECKIFY_API_KEY = os.environ["CHECKIFY_API_KEY"]
CHECKIFY_BASE_URL = os.getenv("CHECKIFY_BASE_URL", "https://checkify.me")
USER_MESSAGE = "Verification could not be completed for this action."
UNAVAILABLE = "Verification is temporarily unavailable. Please try again."
def verify_checkify_result(request_id: str, required_claims=None) -> dict:
required_claims = required_claims or ["human_verified"]
try:
response = httpx.post(
f"{CHECKIFY_BASE_URL}/v1/qr/results/verify",
headers={
"Authorization": f"Bearer {CHECKIFY_API_KEY}",
"Content-Type": "application/json",
},
json={
"request_id": request_id,
"required_claims": required_claims,
"consume": True,
},
timeout=10.0,
)
except httpx.RequestError as exc:
print("Checkify verification unavailable", exc)
return {"allow": False, "reason": "unavailable", "user_message": UNAVAILABLE}
try:
body = response.json()
except ValueError:
body = None
if response.status_code >= 400:
error = (body or {}).get("error") if isinstance(body, dict) else None
details = (error or {}).get("details", {})
print(
"Checkify verification failed",
{
"request_id": request_id,
"code": (error or {}).get("code"),
"missing_claims": details.get("missing_claims"),
"missing_fields": details.get("missing_fields"),
"reason": details.get("reason"),
},
)
return {
"allow": False,
"reason": (error or {}).get("code", "verification_failed"),
"user_message": USER_MESSAGE,
}
if not isinstance(body, dict) or body.get("status") == "pending" or body.get("success") is False:
return {"allow": False, "reason": "pending", "user_message": USER_MESSAGE}
approved = all((body.get("approved_claims") or {}).get(claim) is True for claim in required_claims)
return {
"allow": approved,
"reason": "approved" if approved else "verification_failed",
"user_message": None if approved else USER_MESSAGE,
"result": body,
}
@app.post("/signup")
def signup(email: str, checkify_token: str):
request_id = (checkify_token or "").strip()
if not request_id:
raise HTTPException(status_code=403, detail="Verification required")
verdict = verify_checkify_result(request_id)
if not verdict["allow"]:
raise HTTPException(status_code=403, detail=verdict["user_message"])
return {"ok": True}
<?php
$checkifyApiKey = getenv('CHECKIFY_API_KEY');
$baseUrl = getenv('CHECKIFY_BASE_URL') ?: 'https://checkify.me';
function verify_checkify_result(string $requestId, array $requiredClaims = ['human_verified']): array {
global $checkifyApiKey, $baseUrl;
$payload = json_encode([
'request_id' => $requestId,
'required_claims' => $requiredClaims,
'consume' => true,
]);
$ch = curl_init($baseUrl . '/v1/qr/results/verify');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $checkifyApiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $payload,
CURLOPT_TIMEOUT => 10,
]);
$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($raw === false) {
error_log('Checkify verification unavailable');
return ['allow' => false, 'user_message' => 'Verification is temporarily unavailable. Please try again.'];
}
$body = json_decode($raw ?: 'null', true);
if ($status >= 400) {
$error = is_array($body) ? ($body['error'] ?? null) : null;
$details = is_array($error) ? ($error['details'] ?? []) : [];
error_log('Checkify verification failed: ' . json_encode([
'code' => is_array($error) ? ($error['code'] ?? null) : null,
'missing_claims' => $details['missing_claims'] ?? null,
]));
return ['allow' => false, 'user_message' => 'Verification could not be completed for this action.'];
}
if (!is_array($body) || ($body['status'] ?? '') === 'pending' || ($body['success'] ?? true) === false) {
return ['allow' => false, 'user_message' => 'Verification could not be completed for this action.'];
}
foreach ($requiredClaims as $claim) {
if (($body['approved_claims'][$claim] ?? false) !== true) {
return ['allow' => false, 'user_message' => 'Verification could not be completed for this action.'];
}
}
return ['allow' => true, 'result' => $body];
}
$requestId = trim($_POST['checkify_token'] ?? '');
if ($requestId === '') {
http_response_code(403);
echo json_encode(['error' => 'Verification required']);
exit;
}
$verdict = verify_checkify_result($requestId);
if (!$verdict['allow']) {
http_response_code(403);
echo json_encode(['error' => $verdict['user_message']]);
exit;
}
// continue protected action...
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"strings"
"time"
)
type verifyResponse struct {
Success bool `json:"success"`
Status string `json:"status"`
Message string `json:"message"`
ApprovedClaims map[string]bool `json:"approved_claims"`
}
type errorResponse struct {
Error struct {
Code string `json:"code"`
Message string `json:"message"`
Details map[string]interface{} `json:"details"`
} `json:"error"`
}
func verifyCheckifyResult(requestID string, requiredClaims []string) (bool, string, error) {
apiKey := os.Getenv("CHECKIFY_API_KEY")
baseURL := os.Getenv("CHECKIFY_BASE_URL")
if baseURL == "" {
baseURL = "https://checkify.me"
}
payload, _ := json.Marshal(map[string]interface{}{
"request_id": requestID,
"required_claims": requiredClaims,
"consume": true,
})
req, err := http.NewRequest(http.MethodPost, baseURL+"/v1/qr/results/verify", bytes.NewReader(payload))
if err != nil {
return false, "", err
}
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 10 * time.Second}
res, err := client.Do(req)
if err != nil {
return false, "", err
}
defer res.Body.Close()
if res.StatusCode >= 400 {
var errBody errorResponse
_ = json.NewDecoder(res.Body).Decode(&errBody)
fmt.Printf("Checkify verification failed code=%s details=%v\n", errBody.Error.Code, errBody.Error.Details)
return false, "Verification could not be completed for this action.", nil
}
var body verifyResponse
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
return false, "Verification could not be completed for this action.", nil
}
if body.Status == "pending" || !body.Success {
return false, "Verification could not be completed for this action.", nil
}
for _, claim := range requiredClaims {
if !body.ApprovedClaims[claim] {
return false, "Verification could not be completed for this action.", nil
}
}
return true, "", nil
}
func signupHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
if err := r.ParseForm(); err != nil {
http.Error(w, "invalid form", http.StatusBadRequest)
return
}
requestID := strings.TrimSpace(r.FormValue("checkify_token"))
if requestID == "" {
http.Error(w, "Verification required", http.StatusForbidden)
return
}
allowed, message, err := verifyCheckifyResult(requestID, []string{"human_verified"})
if err != nil {
fmt.Println("Checkify verification unavailable", err)
http.Error(w, "Verification is temporarily unavailable. Please try again.", http.StatusForbidden)
return
}
if !allowed {
http.Error(w, message, http.StatusForbidden)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(`{"ok":true}`))
}
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
var apiKey = Environment.GetEnvironmentVariable("CHECKIFY_API_KEY");
var baseUrl = Environment.GetEnvironmentVariable("CHECKIFY_BASE_URL") ?? "https://checkify.me";
async Task<(bool Allow, string UserMessage)> VerifyCheckifyAsync(string requestId)
{
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
using var req = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/v1/qr/results/verify");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
req.Content = new StringContent(JsonSerializer.Serialize(new
{
request_id = requestId,
required_claims = new[] { "human_verified" },
consume = true,
}), Encoding.UTF8, "application/json");
HttpResponseMessage res;
try
{
res = await client.SendAsync(req);
}
catch (Exception ex)
{
Console.Error.WriteLine($"Checkify verification unavailable: {ex.Message}");
return (false, "Verification is temporarily unavailable. Please try again.");
}
var raw = await res.Content.ReadAsStringAsync();
using var doc = JsonDocument.Parse(string.IsNullOrWhiteSpace(raw) ? "{}" : raw);
var root = doc.RootElement;
if (!res.IsSuccessStatusCode)
{
if (root.TryGetProperty("error", out var err) && err.TryGetProperty("details", out var details))
{
Console.WriteLine($"Checkify verification failed details={details}");
}
return (false, "Verification could not be completed for this action.");
}
if (root.TryGetProperty("status", out var status) && status.GetString() == "pending")
{
return (false, "Verification could not be completed for this action.");
}
if (root.TryGetProperty("approved_claims", out var claims)
&& claims.TryGetProperty("human_verified", out var human)
&& human.GetBoolean())
{
return (true, string.Empty);
}
return (false, "Verification could not be completed for this action.");
}
// In your signup endpoint:
// var requestId = form["checkify_token"];
// var (allow, message) = await VerifyCheckifyAsync(requestId);
// if (!allow) return Results.Forbid();
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
public class CheckifyVerify {
private static final String API_KEY = System.getenv("CHECKIFY_API_KEY");
private static final String BASE_URL =
System.getenv().getOrDefault("CHECKIFY_BASE_URL", "https://checkify.me");
private static final ObjectMapper MAPPER = new ObjectMapper();
static boolean verifyCheckifyResult(String requestId) {
String payload = "{\"request_id\":\"" + requestId + "\","
+ "\"required_claims\":[\"human_verified\"],\"consume\":true}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "/v1/qr/results/verify"))
.timeout(Duration.ofSeconds(10))
.header("Authorization", "Bearer " + API_KEY)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
try {
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
JsonNode root = MAPPER.readTree(response.body() == null ? "{}" : response.body());
if (response.statusCode() >= 400) {
System.err.println("Checkify verification failed: " + root);
return false;
}
if ("pending".equals(root.path("status").asText()) || !root.path("success").asBoolean(false)) {
return false;
}
return root.path("approved_claims").path("human_verified").asBoolean(false);
} catch (Exception ex) {
System.err.println("Checkify verification unavailable: " + ex.getMessage());
return false;
}
}
}
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.
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.",
});
}
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.
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.
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.
HÄMTA /v1/qr/status?token={poll_token}HÄMTA /v1/qr/status/request/{request_id}?status_token={status_token}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"
}
}
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ält | Menande |
|---|---|
success | true när verifieringen är klar och kraven uppfyllda |
status | completed eller pending |
approved_claims | Godkända påståenden Checkify, t.ex. human_verified: true |
signed_result | Valfri signerad nyttolast för revisionsspår |
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_authorization | 401 | Ingen auktoriseringsrubrik skickades. | Skicka auktorisering: Bärare YOUR_SITE_API_KEY endast från serverkod. |
invalid_token | 401 | Bearer-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_token | 401 | Webbplatsens nyckel API har återkallats. | Skapa en ny webbplatsnyckel API och rotera den på dina servrar. |
missing_required_field | 400 / 422 | request_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_id | 400 | Referensen 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_found | 404 | Det 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_expired | 410 | Verifieringen 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_failed | 403 / 409 | Verifieringen ä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_claims | 403 | developers_server.err_missing_required_claims_meaning | developers_server.err_missing_required_claims_action |
missing_required_fields | 403 | developers_server.err_missing_required_fields_meaning | developers_server.err_missing_required_fields_action |
unknown_required_attributes | 400 | developers_server.err_unknown_required_attributes_meaning | developers_server.err_unknown_required_attributes_action |
business_not_operational | 403 | Fö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_errors | 422 | Schemavalideringen 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_limited | 429 | Fö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_error | 500+ | 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. |
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.
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.