DEV Community

Cover image for Hướng Dẫn Lập Trình Viên: Xác Minh ID với Stripe Identity API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Lập Trình Viên: Xác Minh ID với Stripe Identity API

Việc xác minh danh tính thực của người dùng nghe có vẻ đơn giản cho đến khi bạn triển khai thực tế: bạn phải xử lý việc chụp tài liệu, nhận diện ký tự (OCR), đối chiếu khuôn mặt, kiểm tra sự sống, phát hiện gian lận và hỗ trợ hàng chục loại giấy tờ khác nhau trên nhiều quốc gia. Stripe Identity đóng gói tất cả quy trình này vào một API duy nhất, cho phép thiết lập xác minh ID sẵn sàng sản xuất chỉ trong vài giờ thay vì vài tháng.

Dùng thử Apidog ngay hôm nay

Bài viết này hướng dẫn chi tiết từng bước để tích hợp Stripe Identity: kích hoạt trên Stripe Dashboard, tạo VerificationSession, chọn giữa chuyển hướng lưu trữ và thành phần nhúng Stripe.js, xử lý webhook và lấy dữ liệu xác minh. Bạn sẽ có các ví dụ curl, Node.js, xử lý lỗi, và cách kiểm thử toàn bộ luồng xác minh cục bộ với Apidog. Nếu cần đánh giá giải pháp khác, hãy tham khảo tổng hợp các API KYC tốt nhất trước khi quyết định.

Stripe Identity phù hợp với đội ngũ đã dùng Stripe cho thanh toán, nhưng cũng hoạt động độc lập. Bài viết này tập trung vào trải nghiệm phát triển: quy trình API, trường dữ liệu quan trọng, lỗi thường gặp và mẹo kiểm thử thực tế.

Tóm tắt

  • Stripe Identity xác minh người dùng qua giấy tờ tùy thân và kiểm tra sự sống bằng ảnh selfie; giá từ $1.50/lần xác minh tại Mỹ.
  • Đối tượng cốt lõi: VerificationSession; tạo phiên ở backend, sau đó redirect người dùng hoặc nhúng Stripe.js.
  • Yêu cầu các trường cần thiết qua options.document.require_matching_selfie, require_id_number, allowed_types.
  • Lắng nghe webhook identity.verification_session.verified và identity.verification_session.requires_input để cập nhật trạng thái ứng dụng.
  • Kết quả xác minh (tên, ngày sinh, địa chỉ, số ID) chỉ trả về khi bạn khai báo verified_outputs lúc tạo phiên.
  • Hỗ trợ 35+ quốc gia, xử lý giấy tờ bản địa hóa.

API Stripe Identity là gì?

Stripe Identity là sản phẩm xác minh ID dựa trên API Stripe, sử dụng endpoint chính /v1/identity/verification_sessions để điều phối quy trình chụp giấy tờ, trích xuất dữ liệu, so khớp khuôn mặt và đánh giá gian lận. Kết quả trả về là bản ghi đã xác minh (họ tên, ngày sinh, địa chỉ, số ID), cùng ảnh tài liệu gốc lưu trên Stripe.

Quy trình sử dụng mô hình session và webhook quen thuộc từ Stripe Checkout: backend tạo session, Stripe xử lý giao diện xác minh, sau đó trả kết quả qua webhook. Nếu từng tích hợp Stripe Checkout, bạn có thể làm quen với Identity chỉ trong vài phút.

Xác thực và thiết lập

Đầu tiên, bật Stripe Identity trên Dashboard: vào Cài đặt > Identity, đồng ý điều khoản và khai báo thông tin doanh nghiệp.

Xác thực bằng khóa bí mật Stripe như bình thường: sk_test_ cho môi trường test, sk_live_ cho production. Không cần thông tin xác thực riêng.

Cài đặt Stripe Node SDK:

npm install stripe

Khởi tạo client, chỉ định API version để tránh lỗi schema:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

Bạn đã sẵn sàng gọi các endpoint stripe.identity.verificationSessions.

Các điểm cuối cốt lõi

Tạo VerificationSession

Mỗi lần xác minh người dùng, bạn tạo một VerificationSession. Đối tượng này xác định loại giấy tờ được chấp nhận, có yêu cầu ảnh selfie hay không, và các trường trả về backend.

Ví dụ 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"

Hoặc 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 hai thuộc tính này đến client:
// session.url              // chuyển hướng lưu trữ
// session.client_secret    // để nhúng Stripe.js

Lưu ý: type: "document" dùng cho xác minh giấy tờ. allowed_types chỉ định loại giấy tờ chấp nhận (ví dụ: bằng lái, hộ chiếu). verified_outputs là danh sách trường bạn muốn nhận về — Stripe sẽ chỉ trả về đúng trường bạn yêu cầu.

Chuyển hướng lưu trữ vs Stripe.js nhúng

Có hai cách tích hợp:

  • Chuyển hướng lưu trữ: chuyển người dùng đến session.url (giao diện Stripe), sau xác minh sẽ trở về return_url bạn cấu hình. Đơn giản, chỉ cần vài dòng code.
  • Nhúng Stripe.js: dùng @stripe/stripe-js trên frontend, truyền session.client_secret và gọi stripe.verifyIdentity(clientSecret). Người dùng không rời khỏi trang, phù hợp khi xác minh nằm trong luồng đăng ký.

Webhook

Không nên dựa vào redirect trên client để xác định trạng thái xác minh. Luôn xác thực từ backend qua webhook. Thiết lập webhook tại Dashboard > Developers > Webhooks và đăng ký sự kiện:

  • identity.verification_session.verified: xác minh thành công, dữ liệu sẵn sàng.
  • identity.verification_session.requires_input: người dùng thất bại ở bước nào đó, cần thử lại.
  • identity.verification_session.processing: Stripe đang xử lý, có thể hiển thị trạng thái chờ.
  • identity.verification_session.canceled: phiên bị hủy.
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

Webhook chỉ báo trạng thái, không trả về dữ liệu nhạy cảm. Để lấy kết quả xác minh, 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;

Lưu ý: id_number chỉ trả về một lần; cần mã hóa và lưu trữ ngay nếu cần sử dụng sau. Ảnh tài liệu chỉ xem được trên Stripe Dashboard.

Các lỗi thường gặp và giới hạn tỷ lệ

Lỗi phổ biến: verification_session.requires_input với mã như document_unverified_other hoặc selfie_face_mismatch. Xử lý: cho phép người dùng thử lại, có thể dùng lại phiên hiện tại hoặc tạo phiên mới.

Stripe áp dụng giới hạn 100 request/s (production) và 25 request/s (test). Nếu bị giới hạn, nhận HTTP 429 với header Retry-After — hãy sử dụng retry với backoff hợp lý.

Lỗi khác: unsupported_document_type (tải lên giấy tờ không nằm trong allowed_types), country_not_supported (giấy tờ không thuộc quốc gia Stripe hỗ trợ).

Giá Stripe Identity

Giá: $1.50/lần xác minh tại Mỹ. Quốc tế dao động từ $1.50–$2.00/lần, Stripe công bố chi tiết trên trang giá. Phiên xác minh thất bại (requires_input) không bị tính phí, chỉ tính khi thành công (verified).

Khách hàng lớn (>10,000 xác minh/tháng) có thể liên hệ Stripe để nhận giá tùy chỉnh.

Kiểm thử Stripe Identity với Apidog

Để thử nghiệm API nhanh và hiệu quả hơn thay vì tự viết lệnh curl, bạn nên dùng Apidog. Apidog nhập trực tiếp OpenAPI spec của Stripe — mọi trường của VerificationSession đều có mô tả và kiểm thử inline. Có thể gửi request thật đến Stripe test, kiểm tra và lặp lại payload dễ dàng.

Đặc biệt, kiểm thử webhook với Apidog giúp bạn mô phỏng sự kiện identity.verification_session.verified và gửi về máy chủ dev để kiểm tra logic mà không cần thực hiện xác minh thật. Tham khảo thêm: Hướng dẫn kiểm thử API không cần Postman. Tải Apidog để có desktop client.

Câu hỏi thường gặp

Stripe Identity khác gì KYC mặc định của Stripe? KYC gốc dùng để xác minh chủ tài khoản Stripe Connect/Payments; Stripe Identity là API riêng cho xác minh người dùng cuối, hai hệ thống không chia sẻ dữ liệu xác minh.

Có tái sử dụng được danh tính đã xác minh không? Có, output xác minh là vĩnh viễn với từng session. Nếu cần xác minh lại cho một sự kiện mới, hãy tạo session mới và liên kết với user.

Stripe Identity có dùng ngoài thanh toán được không? Được. Nhiều khách chỉ dùng nó để xác minh KYC mà không dùng thanh toán Stripe. Nếu cần sàng lọc AML, hãy kết hợp với API AML chuyên dụng.

Stripe Identity khác gì Plaid Identity Verification? Stripe xác minh giấy tờ và selfie; Plaid dựa vào thông tin ngân hàng xác thực. Tham khảo hướng dẫn Plaid API nếu muốn tiếp cận khác.

Có bắt buộc kiểm tra selfie không? Không. Đặt require_matching_selfie=false nếu chỉ cần kiểm tra giấy tờ. Tuy nhiên, nhiều nhóm chống gian lận luôn bật vì phát hiện sự sống giúp chặn nhiều rủi ro.

Stripe Identity hỗ trợ quốc gia nào? Hơn 35 quốc gia ở Bắc Mỹ, Châu Âu và một số quốc gia APAC, với phân tích giấy tờ được bản địa hóa. Xem danh sách cập nhật trên tài liệu Stripe, Stripe thường bổ sung quốc gia mới liên tục.

Top comments (0)