Việc xác minh danh tính thực của người dùng là một trong những nhiệm vụ trông có vẻ đơn giản trên bảng trắng nhưng lại biến thành một dự án kéo dài hàng tháng ngay khi bạn bắt đầu xây dựng nó. Bạn cần chụp tài liệu, OCR, đối sánh khuôn mặt, phát hiện sự sống, tín hiệu gian lận và hỗ trợ hàng chục loại giấy tờ tùy thân ở nhiều quốc gia. API Stripe Identity gói tất cả những điều đó vào một tích hợp duy nhất, vì vậy bạn có thể thiết lập một quy trình xác minh ID sẵn sàng sản xuất chỉ trong một buổi chiều thay vì một quý.
Hướng dẫn này sẽ trình bày mọi bước mà một nhà phát triển cần để triển khai Stripe Identity: bật nó trong bảng điều khiển, tạo một VerificationSession, lựa chọn giữa chuyển hướng được lưu trữ và thành phần Stripe.js được nhúng, xử lý webhook và đọc các kết quả đã xác minh. Bạn sẽ thấy các ví dụ về curl và Node, các mẫu xử lý lỗi và cách kiểm tra toàn bộ luồng cục bộ với Apidog. Nếu bạn đang đánh giá các lựa chọn thay thế trước tiên, hãy xem qua tổng hợp của chúng tôi về các API KYC tốt nhất trước khi cam kết.
Stripe Identity rất phù hợp với các nhóm đã sử dụng Stripe để thanh toán, nhưng nó cũng hoạt động như một sản phẩm độc lập. Tài liệu chính thức của Stripe Identity bao gồm bề mặt sản phẩm, và bài viết này bổ sung những khoảng trống trong trải nghiệm nhà phát triển: những gì xảy ra trên đường dây, những trường nào quan trọng và những lỗi thường gặp ở đâu.
Tóm tắt
- Stripe Identity xác minh người dùng bằng giấy tờ tùy thân do chính phủ cấp cộng với kiểm tra sự sống bằng ảnh selfie; giá bắt đầu từ 1,50 đô la mỗi lần xác minh ở Hoa Kỳ.
- Thành phần cốt lõi là đối tượng
VerificationSession; bạn tạo một phiên ở phía máy chủ, sau đó chuyển hướng người dùng hoặc gắn thành phần Stripe.js. - Yêu cầu các trường bạn cần thông qua
options.document.require_matching_selfie,require_id_numbervàallowed_types. - Lắng nghe các webhook
identity.verification_session.verifiedvàidentity.verification_session.requires_inputđể điều khiển trạng thái ứng dụng của bạn. - Các kết quả đã xác minh (tên, ngày sinh, địa chỉ, số ID) chỉ được hiển thị khi bạn đặt
verified_outputskhi tạo phiên. - Stripe Identity hỗ trợ hơn 35 quốc gia với hỗ trợ tài liệu bản địa hóa.
API Stripe Identity là gì?
Stripe Identity là một sản phẩm xác minh ID được xây dựng trên nền tảng API cốt lõi của Stripe. Nó cung cấp cho bạn một nhóm điểm cuối duy nhất (/v1/identity/verification_sessions) để điều phối việc chụp tài liệu, trích xuất dữ liệu, đối sánh khuôn mặt và tính điểm gian lận. Kết quả là một bản ghi có cấu trúc, được ký mà bạn có thể tin cậy: tên đầy đủ đã xác minh, ngày sinh, địa chỉ và số ID tùy chọn, cùng với các hình ảnh tài liệu gốc được lưu trữ trong kho của Stripe.
Về cơ bản, Stripe sử dụng cùng một mẫu phiên cộng với webhook mà bạn đã biết từ Checkout và Payment Intents. Bạn tạo một phiên ở phía máy chủ, Stripe xử lý giao diện người dùng để chụp thông tin, và bạn sẽ được thông báo khi kết quả sẵn sàng. Nếu bạn đã từng xây dựng một luồng Checkout trước đây, Identity sẽ cảm thấy quen thuộc trong vài phút.
Xác thực và thiết lập
Trước khi bạn gọi API, hãy bật Stripe Identity trong bảng điều khiển. Đi tới Bảng điều khiển > Cài đặt > Identity, chấp nhận các điều khoản và điền thông tin chi tiết về doanh nghiệp mà Stripe cần để tuân thủ KYC về phía mình. Chuyển đổi này kích hoạt Identity cho cả chế độ thử nghiệm và chế độ thực trên tài khoản của bạn.
Xác thực sử dụng khóa bí mật Stripe tiêu chuẩn của bạn. Khóa thử nghiệm bắt đầu bằng sk_test_, và khóa thực bắt đầu bằng sk_live_. Stripe Identity không yêu cầu một thông tin xác thực riêng biệt, giúp giữ cho bề mặt tích hợp nhỏ gọn.
Cài đặt Node SDK:
npm install stripe
Sau đó khởi tạo một client. Gắn phiên bản API để Stripe không bao giờ làm bạn bất ngờ với một thay đổi schema:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Bây giờ bạn có thể gọi mọi điểm cuối trong stripe.identity.verificationSessions.
Các điểm cuối cốt lõi
Tạo một VerificationSession
VerificationSession là đối tượng duy nhất bạn tạo cho mỗi lần thử xác minh người dùng. Nó kiểm soát loại tài liệu nào được chấp nhận, liệu có yêu cầu ảnh selfie hay không và những trường nào được trả về backend của bạn.
Với curl:
curl https://api.stripe.com/v1/identity/verification_sessions \
-u "$STRIPE_SECRET_KEY:" \
-d "type=document" \
-d "options[document][require_matching_selfie]=true" \
-d "options[document][require_id_number]=true" \
-d "options[document][allowed_types][]=driving_license" \
-d "options[document][allowed_types][]=passport" \
-d "verified_outputs[]=first_name" \
-d "verified_outputs[]=last_name" \
-d "verified_outputs[]=dob" \
-d "verified_outputs[]=address" \
-d "verified_outputs[]=id_number" \
-d "metadata[user_id]=usr_7f3k2"
Với Node SDK:
const session = await stripe.identity.verificationSessions.create({
type: "document",
options: {
document: {
require_matching_selfie: true,
require_id_number: true,
allowed_types: ["driving_license", "passport", "id_card"],
},
},
verified_outputs: [
"first_name",
"last_name",
"dob",
"address",
"id_number",
],
metadata: { user_id: "usr_7f3k2" },
});
// Gửi một trong số này đến client:
// session.url -> chuyển hướng được lưu trữ
// session.client_secret -> thành phần nhúng Stripe.js
Một vài trường đáng chú ý. type: "document" cho Stripe biết để chạy kiểm tra tài liệu; thay thế, id_number, thực hiện tra cứu kiểu SSN chỉ ở Hoa Kỳ mà không thu thập ID. allowed_types hạn chế các loại tài liệu mà người dùng có thể tải lên, điều này quan trọng đối với các chương trình tuân thủ chỉ chấp nhận ID ảnh do chính phủ cấp. verified_outputs là danh sách các trường bạn muốn trả về; Stripe sẽ không tiết lộ bất kỳ dữ liệu nào bạn không yêu cầu, điều này giữ cho chính sách giảm thiểu dữ liệu của bạn sạch sẽ.
Chuyển hướng xác minh được lưu trữ so với Stripe.js được nhúng
Stripe cung cấp cho bạn hai hình thức tích hợp. Chuyển hướng được lưu trữ là con đường nhanh nhất: gửi người dùng đến session.url, Stripe xử lý toàn bộ trải nghiệm chụp trên miền stripe.com, và người dùng quay lại return_url của bạn. Bạn viết khoảng mười dòng mã.
Luồng nhúng sử dụng Stripe.js và gói @stripe/stripe-js để gắn một hộp thoại xác minh bên trong ứng dụng của riêng bạn. Bạn chuyển session.client_secret tới frontend và gọi stripe.verifyIdentity(clientSecret). Điều này giữ người dùng trong sản phẩm của bạn và cho phép bạn kiểm soát thiết kế của trang xung quanh. Chọn cách này khi xác minh diễn ra giữa luồng trong một bước đăng ký hoặc KYC; chọn chuyển hướng khi xác minh là một tác vụ riêng biệt.
Webhook
Không bao giờ dựa vào chuyển hướng client để biết xác minh thành công; luôn xác nhận ở backend thông qua webhook. Đăng ký một điểm cuối tại Dashboard > Developers > Webhooks và đăng ký các sự kiện sau:
identity.verification_session.verifiedkích hoạt khi tất cả các kiểm tra được thông qua và dữ liệu đã xác minh sẵn sàng.identity.verification_session.requires_inputkích hoạt khi người dùng không vượt qua một kiểm tra hoặc tải lên một tài liệu không đọc được. Bạn có thể chuyển hướng họ quay lại để thử lại.identity.verification_session.processingkích hoạt trong khi Stripe chạy các kiểm tra không đồng bộ; hữu ích để hiển thị các trạng thái chờ.identity.verification_session.canceledkích hoạt nếu bạn hủy phiên theo chương trình.
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
const event = stripe.webhooks.constructEvent(
req.body,
req.headers["stripe-signature"],
process.env.STRIPE_WEBHOOK_SECRET
);
if (event.type === "identity.verification_session.verified") {
const session = event.data.object;
await markUserVerified(session.metadata.user_id, session.id);
}
if (event.type === "identity.verification_session.requires_input") {
await notifyUserToRetry(event.data.object.metadata.user_id);
}
res.json({ received: true });
});
Truy xuất kết quả đã xác minh
Payload của webhook cho bạn biết phiên đã được xác minh, nhưng nó không bao gồm các trường nhạy cảm. Để đọc các kết quả đã xác minh, hãy gọi verificationSessions.retrieve với expand: ["verified_outputs"]:
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
Stripe chỉ trả về id_number một lần; hãy lưu trữ nó được mã hóa ở phía bạn ngay lập tức. Các hình ảnh tài liệu tự chúng vẫn nằm trong kho của Stripe và có thể truy cập thông qua bảng điều khiển để kiểm tra.
Các lỗi thường gặp và giới hạn tỷ lệ
Lỗi thường xuyên nhất là verification_session.requires_input với mã như document_unverified_other hoặc selfie_face_mismatch. Xử lý các lỗi này bằng cách hiển thị một giao diện thử lại thân thiện; cùng một phiên có thể được sử dụng lại bằng cách gọi verificationSessions.cancel và tạo một phiên mới, hoặc bằng cách chuyển hướng đến cùng session.url khi nó vẫn đang mở.
Stripe áp dụng giới hạn tỷ lệ API tiêu chuẩn là 100 yêu cầu mỗi giây ở chế độ thực và 25 yêu cầu mỗi giây ở chế độ thử nghiệm. Các điểm cuối /identity/verification_sessions thuộc cùng một nhóm với phần còn lại của API. Nếu bạn đạt đến giới hạn, bạn sẽ thấy HTTP 429 với tiêu đề Retry-After; hãy sử dụng chiến lược lùi mũ và tuân thủ tiêu đề.
Các lỗi khác cần lưu ý: unsupported_document_type khi người dùng tải lên một ID không nằm trong danh sách allowed_types của bạn, và country_not_supported khi ai đó cố gắng sử dụng tài liệu từ một trong những quốc gia mà Stripe Identity chưa hỗ trợ.
Giá Stripe Identity
Stripe Identity có giá 1,50 đô la mỗi lần xác minh tại Hoa Kỳ. Giá quốc tế khác nhau; hầu hết các nước châu Âu dao động khoảng 1,50 đô la đến 2,00 đô la, và Stripe công bố chi tiết đầy đủ giá theo từng quốc gia trên trang giá của mình. Một lần thử xác minh kết thúc với requires_input không được tính là một sự kiện có thể thanh toán; chỉ các phiên verified hoàn tất mới được lập hóa đơn.
Đối với các khách hàng có số lượng lớn, Stripe cung cấp giá tùy chỉnh có thể giảm đáng kể phí mỗi lần kiểm tra. Nếu bạn xử lý hơn 10.000 xác minh mỗi tháng, hãy liên hệ với bộ phận bán hàng.
Kiểm thử Stripe Identity với Apidog
Các môi trường API tốt hơn rất nhiều so với việc tự viết các lệnh curl, đặc biệt khi bạn đang lặp lại trên các payload webhook. Apidog nhập trực tiếp đặc tả OpenAPI của Stripe, vì vậy mọi trường trên đối tượng VerificationSession đều hiển thị với tài liệu nội tuyến. Bạn có thể gửi các yêu cầu thực đến môi trường thử nghiệm của Stripe, kiểm tra phản hồi và phát lại bao nhiêu lần tùy thích.
Phần kiểm thử webhook là nơi Apidog tiết kiệm nhiều thời gian nhất. Bạn có thể mô phỏng các sự kiện identity.verification_session.verified cục bộ, gửi chúng đến máy chủ phát triển của bạn và xem qua trình xử lý của bạn mà không cần phải hoàn thành một xác minh thực. Nếu bạn đang so sánh các quy trình làm việc, hướng dẫn của chúng tôi về kiểm thử API không cần Postman vào năm 2026 có hướng dẫn chi tiết hơn. Tải xuống Apidog để có ứng dụng khách trên máy tính.
Câu hỏi thường gặp
Sự khác biệt giữa Stripe Identity và KYC thông thường của Stripe là gì? KYC tích hợp sẵn của Stripe xác minh các chủ doanh nghiệp cho tài khoản Connect và Payments. Stripe Identity là một API độc lập để xác minh người dùng cuối của bạn; hai hệ thống không chia sẻ kết quả xác minh.
Tôi có thể tái sử dụng một danh tính đã xác minh trên nhiều phiên không? Có. Một khi một phiên đã được xác minh, các verified_outputs là vĩnh viễn trên đối tượng phiên đó. Nếu bạn cần xác minh lại cho một sự kiện mới, hãy tạo một phiên mới và liên kết nó với bản ghi người dùng ở phía bạn.
Stripe Identity có hoạt động ngoài thanh toán không? Chắc chắn rồi. Nhiều khách hàng sử dụng nó đơn thuần như một lớp KYC và không bao giờ chạm đến bề mặt thanh toán của Stripe. Nếu bạn cần sàng lọc trừng phạt rộng hơn bên cạnh xác minh ID, hãy kết hợp nó với một API sàng lọc AML chuyên dụng.
Stripe Identity so sánh với Plaid Identity Verification như thế nào? Stripe tập trung vào tài liệu cộng với ảnh selfie; Plaid hướng đến dữ liệu danh tính được ngân hàng xác minh. Xem hướng dẫn API Plaid của chúng tôi để biết cách tiếp cận khác.
Kiểm tra sự sống bằng ảnh selfie có bắt buộc không? Không. Đặt options.document.require_matching_selfie thành false nếu bạn chỉ cần kiểm tra tài liệu. Hầu hết các nhóm chống gian lận vẫn bật tính năng này, vì phát hiện sự sống thụ động bắt được rất nhiều cuộc tấn công ít công sức.
Stripe Identity hỗ trợ những quốc gia nào? Hơn 35 quốc gia trên Bắc Mỹ, Châu Âu và một phần Châu Á-Thái Bình Dương, với các trình phân tích tài liệu được bản địa hóa cho từng khu vực. Stripe công bố danh sách các quốc gia đang hoạt động trong tài liệu của mình và thường xuyên bổ sung các thị trường mới.