Wynajem i zarządzanie nieruchomościami
Proszę wysłać hostowany link w tym samym e-mailu co wniosek najmu. Webhook zmienia status wnioskodawcy na zweryfikowanego w Państwa systemie, zanim przejrzą Państwo dokumentację.
Webhooki i integracje
Webhooki weryfikacji tożsamości, strona hostowana i widget.
Proszę skierować wnioskodawcę na hostowaną stronę weryfikacji lub osadzić widget we własnym procesie, otrzymać podpisany webhook w chwili, gdy wynik jest gotowy, i pozwolić każdemu, kto ma link, potwierdzić go na publicznej stronie sprawdzania poświadczeń. Integracja API KYC stworzona tak, by uruchomić ją w jedno popołudnie.
- Podpisane wywołania zwrotne HMAC-SHA256
- Przekazanie przez QR z komputera na telefon
- Sesje sandbox nigdy nie są rozliczane
Hostowana strona weryfikacji
Jeden link obsługuje cały proces.
Po utworzeniu sesji przez API otrzymają Państwo adres URL weryfikacji. Można go wysłać e-mailem, SMS-em lub w własnej aplikacji — resztą zajmie się strona.
Komputer
Wnioskodawca otwiera link przy swoim biurku.
Przekazanie przez kod QR
Strona wyświetla kod QR i krótką kartę z instrukcją.
Rejestracja na telefonie
Zeskanowanie kodu przełącza tę samą sesję na przechwycenie dokumentu i selfie.
Zweryfikowano
Sesja osiąga stan VERIFIED, nadal na telefonie.
Z powrotem do Państwa
Przekierowanie na Państwa adres powrotny oraz podpisany webhook, w obu przypadkach.
Działa jak przekierowanie płatności
Wnioskodawca trafia na stronę pod własnym adresem URL Państwa sesji. Bez konta, bez instalowania aplikacji.
Przekazanie przez kod QR, z komputera na telefon
Po otwarciu na komputerze strona wyświetla kod QR i krótką kartę z instrukcją zamiast prosić o dostęp do kamery. Zeskanowanie kodu otwiera ten sam link na telefonie, który przechodzi od razu do przechwytywania dokumentu i selfie.
Wraca do Państwa, z odpowiedzią
Gdy sesja osiągnie status VERIFIED, strona przekierowuje na Państwa adres zwrotny, dołączając ID sesji i status, dzięki czemu Państwa aplikacja wie, co się stało, bez czekania na cokolwiek innego.
Z Państwa marką, w kwalifikujących się planach
Nazwa Państwa firmy, logo, kolor wiodący oraz linki do regulaminu i polityki prywatności, zastosowane na stronie hostowanej i na stronie sprawdzania poświadczeń.
Webhooki
Podpisane wywołanie zwrotne, gdy tylko wynik jest gotowy.
Podają nam Państwo adres URL webhooka przy tworzeniu sesji, a my wysyłamy na niego wynik zaraz po zakończeniu sesji, bez konieczności odpytywania.
Podpisane, a nie tylko wysłane
Każde dostarczenie zawiera nagłówek X-Bio-Signature: HMAC-SHA256 treści żądania, dzięki czemu mogą Państwo potwierdzić, że pochodzi od nas, zanim mu zaufają.
Ponawiane, a nie „wyślij i zapomnij”
Nieudane dostarczenie jest ponawiane trzykrotnie, z coraz dłuższym oczekiwaniem przed każdą próbą.
Każda próba jest rejestrowana
Sukces czy porażka — po naszej stronie zachowujemy zapis próby.
Wkrótce Dziennik dostarczeń w portalu, w którym samodzielnie zobaczą Państwo każdą próbę, pojawi się wkrótce.
Najnowszy status VERIFIED należy traktować jako wiążący
Ponowienia oznaczają, że w rzadkich przypadkach dostarczenie może dotrzeć w nieprawidłowej kolejności. Nie należy opierać logiki na samym odebraniu webhooka — należy oprzeć ją na ID sesji i pozwolić, by późniejszy VERIFIED nadpisał wcześniejszy. Jeśli prowadzą Państwo własny stan, proszę usuwać duplikaty według ID sesji, a nie według odebrania webhooka.
Weryfikacja podpisu
Proszę sprawdzić ładunek (payload), zanim na jego podstawie podejmą Państwo działanie.
Proszę ponownie obliczyć HMAC-SHA256 dla surowej treści żądania i porównać wynik z X-Bio-Signature, zanim Państwo cokolwiek sparsują.
javascript
const crypto = require("crypto");
function verifySignature(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signatureHeader || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Read the raw body — don't let a JSON body-parser touch it first.
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("X-Bio-Signature") || "";
if (!verifySignature(req.body, signature, process.env.SHIELDID_WEBHOOK_SECRET)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body);
// Treat the latest VERIFIED status as authoritative; de-duplicate by session_id.
res.status(200).send("ok");
});Widżet JS
Hostowany proces, osadzony na Państwa własnej stronie.
Widżet tworzy sesję i renderuje ten sam hostowany proces bezpośrednio na stronie, w elemencie iframe, dzięki czemu wnioskodawcy nigdy nie opuszczają Państwa witryny.
- Renderowany w iframe z dostępem do kamery i mikrofonu, dopasowany rozmiarem do kontenera.
- Odczytuje status sesji tak samo jak strona hostowana: przez Państwa adres zwrotny (return URL) i webhook, po zakończeniu sesji.
Wkrótce Wywołania zwrotne ukończenia na stronie (onComplete, onCancel, onStep, automatyczna zmiana rozmiaru) będą dostępne wkrótce. Do tego czasu proszę używać return_url i webhooków, aby dowiedzieć się o zakończeniu sesji — działają już dziś.
Zanim wdrożą Państwo to na produkcję
Widget obecnie akceptuje klucz API bezpośrednio w przeglądarce. Proszę traktować to jako udogodnienie w sandbox, a nie wzorzec produkcyjny: sesję należy tworzyć z własnego backendu, z kluczem przechowywanym po stronie serwera, a widgetowi przekazywać wyłącznie powstałą sesję, nigdy aktywny klucz, który może odczytać przeglądarka użytkownika.
html
<script src="https://cdn.shieldid.ca/sdk/v1/widget.js"></script>
<div id="shieldid-verify"></div>
<script>
TLVerify.init({
apiKey: "vk_sand_your_key", // sandbox only — see the note above for production
containerId: "shieldid-verify",
returnUrl: "https://yourapp.example/verified",
webhookUrl: "https://yourapp.example/hooks/shieldid",
locale: "en",
});
</script>Strona sprawdzania poświadczeń
Publiczna strona dla zweryfikowanej sesji.
Gdy sesja osiągnie status VERIFIED, jej własny link do sprawdzenia poświadczeń wyświetla potwierdzenie w prostym języku: imię i nazwisko wnioskodawcy, typ dokumentu i status. Każdy, kto ma ten link — współporęczyciel, pracownik recepcji, kontrahent — może potwierdzić wynik bez logowania się do Państwa panelu.
Jordan Reyes
Dane przykładowePrawo jazdy z Ontario
Zweryfikowano
- Do jej wyświetlenia nie jest wymagane logowanie.
- Nigdy nie pojawia się na niej surowy obraz dokumentu ani wynik pewności — tylko status i tożsamość, nic więcej.
- Z taką samą marką jak strona hostowana, w kwalifikujących się planach.
Wzorce integracji
Jak sześć rodzajów firm to wdraża.
Elementy składowe są wszędzie takie same: sesja, link lub widget, webhook. Odpowiedni wzorzec zależy od tego, jak i kiedy potrzebują Państwo odpowiedzi.
Branża prawnicza i kancelarie
Proszę wysłać link podczas przyjmowania klienta i zapisać potwierdzenie webhooka w aktach, aby identyfikacja klienta była udokumentowana, zanim rozpocznie się świadczenie usług.
Korporacje kondominialne
Link z formularza rejestracji właściciela lub najemcy, z którego zarząd już korzysta; wynik trafia do systemu, zanim lokal zostanie wpisany do ewidencji.
Fintech i kredyty
Webhook automatycznie uruchamia Państwa własny etap oceny ryzyka (underwriting), dzięki czemu wnioskodawca nigdy nie czeka, aż ktoś zauważy, że wynik nadszedł.
Marketplace’y i platformy gig
Osadzenie widżetu w procesie wdrażania sprzedawców lub kierowców zapewnia przepływ, który nigdy nie opuszcza Państwa aplikacji; sesję należy tworzyć z poziomu backendu, zgodnie z powyższym zaleceniem.
E-signature
Proszę uruchomić hostowany proces przed rozpoczęciem ceremonii podpisania, a udostępnianie dokumentów uzależnić od webhooka, a nie od samego zapewnienia wnioskodawcy.
Pytania
Rzeczowe odpowiedzi o integracji.
Rozpocznij
Podłączenie webhooka. Obserwowanie jego działania.
Proszę utworzyć sesję sandbox z adresem URL webhooka, przeprowadzić weryfikację na własnym telefonie i odczytać podpisane wywołanie zwrotne, które zostanie wysłane.