Checkify
Dokumentacja dla programistów

Zweryfikuj swoje zaplecze

Po zakończeniu osadzania w przeglądarce serwer musi zweryfikować wynik za pomocą klucza witryny API przed umożliwieniem rejestracji, realizacji transakcji lub wykonania jakiejkolwiek chronionej czynności.

Weryfikacja serwera w 5 minut

  1. Dodaj osadzoną w przeglądarce funkcję Checkify do swojej strony.
  2. Osadzenie rozpoczyna sesję Checkify i zapisuje odniesienie weryfikacyjne w formularzu.
  3. Twój serwer odczytuje wartość ukrytego pola.
  4. Twój serwer wysyła tę wartość do POST /v1/qr/results/verify jako request_id.
  5. Jeżeli wymagane roszczenia zostaną zatwierdzone, zezwól na chronioną akcję.
  6. Nigdy nie ufaj wyłącznie stanowi front-endu.

Ukryte pole formularza może nazywać się checkify_token, ale jego wartością jest Checkify request_id.

Przepływ od końca do końca

1. Utwórz klucz witryny API

W panelu swojej firmy otwórz Wywoływacz i utwórz klucz API dla witryny, którą integrujesz. Przechowuj go tylko w zmiennych środowiskowych serwera — nigdy nie wysyłaj go do przeglądarki.

Używasz front-endu SDK?

Nie musisz ręcznie wywoływać polecenia GET /v1/qr/pass/{PASS_ID}/start. Funkcja osadzania Checkify JavaScript uruchamia sesję, odbiera request_id i automatycznie zapisuje go w formularzu.

Twoje zaplecze musi tylko:

2. Odbierz request_id na swoim serwerze

Interfejs użytkownika SDK zapisuje request_id Checkify w ukrytym polu formularza po zakończeniu weryfikacji. Domyślna nazwa pola to checkify_token — jest to nazwa pola, a nie oddzielny typ tokena. Wartość pola należy wysłać do punktu końcowego weryfikacji jako request_id.

Przekazanie aplikacji mobilnej może zwrócić checkify_request_id w adresie URL strony. SDK odczytuje go podczas ładowania; serwer nadal weryfikuje tę samą wartość request_id.

Formularz POST z Twojego front-endu

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

Zweryfikuj żądanie z zaplecza

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

Tylko ręczna integracja front-endu

3. Testowanie ręczne z cURL

Programiści back-endu zazwyczaj nie wywołują /start. Używaj tej sekcji tylko podczas tworzenia niestandardowego front-endu lub testowania bez wbudowanego modułu. W zsh/bash podawaj adresy URL w cudzysłowie, więc znak ? nie jest traktowany jako glob.

Nagłówek źródłowy jest wymagany dla /start

Pass start działa tylko z zarejestrowanej domeny witryny. Przeglądarki wysyłają Origin automatycznie; cURL nie. Wyślij Origin (lub X-Checkify-Site-Url) z nazwą hosta z listy w sekcji Witryny → dozwolone domeny. Nazwa hosta musi być identyczna — checkify.me i www.checkify.me to różne domeny.

Najczęstszy problem testowy

Jeśli polecenie /start zwróci błąd HTTP 403, Twój identyfikator hasła może być nadal prawidłowy. Zazwyczaj przyczyną jest to, że domena żądania nie znajduje się na liście dozwolonych domen lub że zarejestrowano domenę www.example.com, ale użyto example.com (lub odwrotnie).

Użyj dedykowanej witryny testowej i przekaż ją w panelu Checkify do testów integracyjnych. Klucze witryny API używają prefiksu csk_; nie ma oddzielnego formatu klucza testowego. Nie testuj w środowisku produkcyjnym, dopóki nie potwierdzisz zarówno przepływu pomyślnego, jak i odrzuconego.

# 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
  }'

Używaj klucza API tylko podczas połączenia weryfikacyjnego. Przed połączeniem weryfikacyjnym zakończ weryfikację w aplikacji — w przeciwnym razie otrzymasz status oczekujący.

Wymagane roszczenia według przypadku użycia

Ustaw wymagane_roszczenia tak, aby odpowiadały dowodowi wymaganemu przez Twoje działanie chronione. Nazwy roszczeń muszą być zgodne z tym, co Checkify zatwierdził dla danej sesji weryfikacji. Weryfikacja wieku używa age_over_{N} (na przykład age_over_18). Dynamiczne progi od 10 do 110 są obsługiwane, gdy osadzanie żąda pasującego typu żądania.

Przypadek użycia Sugerowane wymagane_roszczenia Notatki
Zamiennik bota / CAPTCHA ["human_verified"] Potwierdza, że prawdziwy użytkownik ukończył przepływ Checkify.
Treści 13+ lub produkty skierowane do młodzieży ["age_over_13"] Użyj, gdy Twój Karnet wymaga podania wieku powyżej 13 lat.
Treści dla osób powyżej 16 roku życia lub regionalne zasady dotyczące wieku ["age_over_16"] Użyj, gdy Twój Karnet wymaga podania wieku powyżej 16 lat.
Vape, alkohol lub kasa dla osób powyżej 18 roku życia ["age_over_18"] Dopasuj próg wiekowy do swojego produktu i rynku.
21+ produktów objętych ograniczeniami (jeśli dotyczy) ["age_over_21"] Użyj, gdy Twój Karnet wymaga podania wieku powyżej 21 lat.
Wyzwanie 25 lub bardziej rygorystyczna polityka detaliczna ["age_over_25"] Użyj, gdy Twój Karnet wymaga podania wieku powyżej 25 lat.
Niestandardowy próg wiekowy ["age_over_N"] Użyj age_over_N, gdzie N wynosi 10–110, zgodnie z typem żądania osadzenia.

Osadź typ żądania → roszczenie serwera

Typ żądania przeglądarki musi odpowiadać żądaniu weryfikowanemu po stronie serwera.

Osadź typ żądaniawymagane_roszczenia
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)

Opcjonalne wymagane pola

Oprócz wymaganych_roszczeń, możesz wymagać określonych zatwierdzonych pól tożsamości (na przykład kraju lub przedziału wiekowego) podczas ich gromadzenia przez integrację. Przekaż nazwy pól w wymaganych_polach — jeśli w zatwierdzonym wyniku brakuje jakichkolwiek pól, weryfikacja zwróci verification_failed z missing_fields w error.details.

4. Wywołaj weryfikację na swoim serwerze

Wywołaj polecenie POST /v1/qr/results/verify z kluczem API swojej witryny przed udzieleniem dostępu. Traktuj odwołanie do przeglądarki (request_id lub starszy token sondy) jako niezaufane, dopóki Checkify nie potwierdzi wyniku.

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
}

Możesz również wysłać token zamiast request_id. Klucz API ma zakres ograniczony do witryny Checkify — w treści żądania nie wysyłasz parametru site_id.

Przykłady implementacji

# 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
  }'

Kiedy stosować spożycie

Użyj „consume: true” dla ostatecznych chronionych akcji — kasa, rejestracja, resetowanie hasła, zakup z ograniczeniem wiekowym, dostęp do treści chronionych

Użyj „consume: false” tylko dla — testowanie, debugowanie lub kontrole nieostateczne, w których wynik musi zostać później ponownie zweryfikowany

W przypadku działań regulowanych lub wysokiego ryzyka należy ustawić wartość consume: true, aby ten sam wynik weryfikacji nie mógł zostać wykorzystany ponownie do wielu chronionych decyzji.

Zamknięto dla regulowanych działań

Jeśli Twoje zaplecze nie może osiągnąć poziomu Checkify, nie zezwalaj na dokonywanie płatności z ograniczeniami wiekowymi, dostęp do gier hazardowych, dostęp do treści dla dorosłych, zakup e-papierosów lub alkoholu ani na inne chronione działania bez potwierdzonego wyniku po stronie serwera.

Stosuj krótkie limity czasu HTTP (na przykład 10 sekund). Ponów próbę raz lub dwa razy w przypadku przejściowych błędów 5xx lub sieciowych, a następnie odmów dostępu. Rejestruj incydenty po stronie serwera i wyświetlaj komunikaty bezpieczne dla użytkownika. Nie ujawniaj klientom wewnętrznych szczegółów błędu Checkify.

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.",
  });
}

Serwer SDKs i narzędzia

Użyj @checkify/server (npm) lub checkify-server (Python) dla typowych funkcji pomocniczych do weryfikacji lub wywołaj bezpośrednio polecenie POST /v1/qr/results/verify. Nie opublikowano jeszcze specyfikacji OpenAPI — skorzystaj z przykładów na tej stronie.

Pakiet @checkify/server w wersji 1.0.0 został opublikowany na platformie npm. Pakiet Python checkify-server znajduje się w monorepozytorium Checkify SDK.

Okno wygaśnięcia wyników

Zakończone weryfikacje tracą ważność po upływie QR_RESULT_MAX_AGE_SECONDS (domyślnie 900 sekund / 15 minut). Po upływie tego czasu funkcja weryfikacyjna zwraca wartość result_expired — prosząc użytkownika o ponowną weryfikację.

Punkty końcowe sondowania statusu (niestandardowe interfejsy użytkownika)

JavaScript SDK obsługuje stan sesji dla standardowych osadzeń. Używaj ich tylko wtedy, gdy tworzysz niestandardowy front-end, który ręcznie wywołuje GET /v1/qr/pass/{pass_id}/start.

Obsługa odpowiedzi

W przypadku powodzenia Checkify zwraca HTTP 200 z wartością success: true i statusem: completed. Zezwalaj na dostęp tylko wtedy, gdy występują wymagane oświadczenia (na przykład 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"
  }
}

Podpisany wynik

Obiekt signed_result pozwala Twojemu zapleczu przechowywać zabezpieczony przed manipulacją rekord audytu, który potwierdza, że Checkify zatwierdził wymagane roszczenie w momencie weryfikacji. Większość integracji wymaga jedynie approved_claims. Firmy regulowane lub wysokiego ryzyka mogą również przechowywać signed_result na potrzeby audytu. Nie przechowuj więcej danych osobowych niż to konieczne.

Jeśli klient nie zakończył jeszcze działania w aplikacji, Checkify zwraca HTTP 200 z komunikatem „sukces: fałsz” i statusem „oczekujący”. Odrzuca chronione akcje i prosi użytkownika o dokończenie weryfikacji.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
PoleOznaczający
successtrue po zakończeniu weryfikacji i spełnieniu wymagań
statuscompleted Lub pending
approved_claimsZatwierdzono roszczenia Checkify, np. human_verified: true
signed_resultOpcjonalny podpisany ładunek dla śladów audytu

JSON ładunki błędów

Gdy weryfikacja nie może być kontynuowana, Checkify zwraca HTTP 4xx/5xx ze strukturą JSON. Sprawdź kod błędu i zaloguj szczegóły błędu po stronie serwera. Zwróć użytkownikom końcowym ogólne komunikaty.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
Kod HTTP Oznaczający Zalecane działanie
missing_authorization401Nagłówek autoryzacyjny nie został wysłany.Wyślij autoryzację: Nośnik YOUR_SITE_API_KEY tylko z kodu po stronie serwera.
invalid_token401Brak tokenu nośnika, jest on źle sformatowany lub nie jest prawidłowym kluczem witryny API.Zweryfikuj klucz w panelu biznesowym i zapisz go w zmiennych środowiskowych.
expired_token401Klucz witryny API został unieważniony.Utwórz nowy klucz witryny API i rotacyjnie go stosuj na swoich serwerach.
missing_required_field400 / 422Brak identyfikatora żądania lub tokenu w treści JSON.Przekaż request_id z ukrytego pola formularza lub token ankiety, jeśli Twoja integracja nadal go używa.
invalid_request_id400Nie można przeanalizować odniesienia lub jest ono puste po normalizacji.Upewnij się, że Twój interfejs użytkownika przesyła żądanie Checkify bez zmian.
result_not_found404Dla tego odniesienia nie istnieje prośba o weryfikację.Odrzuć akcję. Użytkownik mógł zmodyfikować ukryte pole lub przesłać starą sesję.
result_expired410Weryfikacja została ukończona zbyt dawno temu, aby można było zaufać tej akcji.Poproś użytkownika o ponowne skanowanie i wywołanie verify z nowym request_id.
verification_failed403 / 409Weryfikacja została zakończona, ale nie spełniła wymagań/pól, należy do innej witryny lub została już wykorzystana.Odmów dostępu. Sprawdź szczegóły błędu pod kątem brakujących roszczeń, brakujących pól lub przyczyny.
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_operational403Konto firmowe jest zablokowane, zarchiwizowane lub nie działa.Skontaktuj się z właścicielem firmy lub działem pomocy technicznej Checkify. Nie zezwalaj na akcje chronione, dopóki konto nie będzie aktywne.
validation_errors422Treść JSON nie przeszła walidacji schematu (HTTP 422).Sprawdź error.details.validation_errors pod kątem komunikatów na poziomie pola. Przed ponowieniem próby popraw typy request_id, required_claims lub required_fields.
rate_limited429Zbyt wiele połączeń weryfikacyjnych w krótkim czasie.Spróbuj ponownie z wycofywaniem wykładniczym. Weryfikuj tylko w przypadku akcji chronionych, a nie przy każdym wyświetleniu strony.
server_error500+Checkify nie mógł dokończyć weryfikacji z powodu tymczasowego problemu z serwerem.Spróbuj ponownie raz lub dwa razy, następnie zakończ akcję niepowodzeniem i zarejestruj incydent.

Webhooki i weryfikacja asynchroniczna

Obecnie weryfikacja serwera jest synchroniczna: system zaplecza weryfikuje request_id, gdy użytkownik wysyła chronioną akcję. Jest to zalecane podejście w przypadku procesów płatności, rejestracji i kontroli dostępu. Standardowe integracje nie wymagają webhooków weryfikacyjnych ogólnego przeznaczenia. Integracje GoHighLevel i innych partnerów mogą korzystać z oddzielnej konfiguracji webhooków wychodzących w panelu biznesowym.

Typowe błędy

Przypomnienie o bezpieczeństwie

Traktuj ukryte pole jako niezaufane odniesienie, a nie dowód. Zawsze weryfikuj klucz API swojej witryny na serwerze przed udzieleniem dostępu. consume: true do jednorazowych czynności, np. rejestracji lub resetowania hasła.

Następne kroki