วิธีใช้ Stripe Identity API: คู่มือนักพัฒนาเพื่อยืนยันตัวตน

การยืนยันตัวตนจริงของผู้ใช้เป็นหนึ่งในภารกิจที่ดูเรียบง่ายบนไวท์บอร์ด แต่กลับกลายเป็นโปรเจกต์ที่กินเวลานานหลายเดือนทันทีที่คุณเริ่มสร้างมัน คุณต้องมีระบบจับภาพเอกสาร, OCR, การจับคู่ใบหน้า, การตรวจจับความมีชีวิต (liveness detection), สัญญาณการฉ้อโกง, และการรองรับเอกสารระบุตัวตนหลายสิบประเภทในหลายประเทศ Stripe Identity API ได้รวมทั้งหมดนั้นไว้ในการรวมระบบเดียว เพื่อให้คุณสามารถสร้างขั้นตอนการยืนยันตัวตนที่พร้อมใช้งานจริงได้ภายในบ่ายวันเดียว แทนที่จะใช้เวลาเป็นไตรมาส

คู่มือนี้จะอธิบายทุกขั้นตอนที่นักพัฒนาจำเป็นต้องใช้ในการนำ Stripe Identity ไปใช้งาน: การเปิดใช้งานในแดชบอร์ด, การสร้าง VerificationSession, การเลือกระหว่างการเปลี่ยนเส้นทางแบบโฮสต์ (hosted redirect) และคอมโพเนนต์ Stripe.js แบบฝัง (embedded), การจัดการ webhook, และการอ่านผลลัพธ์ที่ยืนยันแล้ว คุณจะได้เห็นตัวอย่างคำสั่ง curl และ Node, รูปแบบการจัดการข้อผิดพลาด, และวิธีการทดสอบขั้นตอนทั้งหมดในเครื่องของคุณด้วย Apidog หากคุณกำลังประเมินทางเลือกอื่นก่อน เราแนะนำให้อ่านสรุป API KYC ที่ดีที่สุด ของเราก่อนตัดสินใจ

Stripe Identity เหมาะสมอย่างยิ่งสำหรับทีมที่ใช้ Stripe สำหรับการชำระเงินอยู่แล้ว แต่ก็สามารถทำงานเป็นผลิตภัณฑ์แบบสแตนด์อโลนได้เช่นกัน เอกสารอย่างเป็นทางการของ Stripe Identity ครอบคลุมพื้นผิวของผลิตภัณฑ์ และโพสต์นี้จะเติมเต็มช่องว่างประสบการณ์ของนักพัฒนา: เกิดอะไรขึ้นในระบบ, ฟิลด์ใดที่สำคัญ, และจุดที่มักเกิดปัญหาทั่วไป

สรุป (TL;DR)

• Stripe Identity ยืนยันผู้ใช้ด้วยบัตรประจำตัวที่ออกโดยรัฐบาลพร้อมกับการตรวจสอบความมีชีวิตด้วยการถ่ายเซลฟี่; ราคาเริ่มต้นที่ 1.50 ดอลลาร์สหรัฐฯ ต่อการยืนยันในสหรัฐอเมริกา
• องค์ประกอบหลักคืออ็อบเจกต์ VerificationSession; คุณสร้างมันทางฝั่งเซิร์ฟเวอร์ จากนั้นเปลี่ยนเส้นทางผู้ใช้หรือติดตั้งคอมโพเนนต์ Stripe.js
• ร้องขอฟิลด์ที่คุณต้องการผ่าน options.document.require_matching_selfie, require_id_number, และ allowed_types.
• ฟัง webhook identity.verification_session.verified และ identity.verification_session.requires_input เพื่อขับเคลื่อนสถานะแอปของคุณ
• ผลลัพธ์ที่ยืนยันแล้ว (ชื่อ, วันเกิด, ที่อยู่, หมายเลขประจำตัว) จะถูกเปิดเผยเฉพาะเมื่อคุณตั้งค่า verified_outputs ในขณะสร้างเซสชัน
• Stripe Identity ครอบคลุมกว่า 35 ประเทศพร้อมการรองรับเอกสารในท้องถิ่น

Stripe Identity API คืออะไร?

Stripe Identity คือผลิตภัณฑ์การยืนยันตัวตนที่สร้างขึ้นบนพื้นผิว API หลักของ Stripe มันให้ตระกูลปลายทางเดียว (/v1/identity/verification_sessions) ที่ประสานงานการจับภาพเอกสาร, การแยกข้อมูล, การจับคู่ใบหน้า, และการให้คะแนนการฉ้อโกง ผลลัพธ์ที่ได้คือบันทึกที่มีลายเซ็นและโครงสร้างที่คุณสามารถเชื่อถือได้: ชื่อเต็มที่ได้รับการยืนยัน, วันเดือนปีเกิด, ที่อยู่, และหมายเลขประจำตัว (เป็นทางเลือก), จับคู่กับรูปภาพเอกสารต้นฉบับที่จัดเก็บอยู่ในห้องนิรภัยของ Stripe

ภายใต้ระบบ Stripe ใช้รูปแบบเซสชันบวก webhook แบบเดียวกับที่คุณคุ้นเคยจาก Checkout และ Payment Intents คุณสร้างเซสชันทางฝั่งเซิร์ฟเวอร์, Stripe จัดการ UI การจับภาพที่ผู้ใช้เห็น, และคุณจะได้รับการแจ้งเตือนเมื่อผลลัพธ์พร้อมใช้งาน หากคุณเคยสร้างขั้นตอน Checkout มาก่อน Identity จะให้ความรู้สึกที่คุ้นเคยภายในไม่กี่นาที

การตรวจสอบสิทธิ์และการตั้งค่า

ก่อนที่คุณจะเรียกใช้ API ให้เปิดใช้งาน Stripe Identity ในแดชบอร์ด ไปที่แดชบอร์ด > การตั้งค่า > Identity, ยอมรับเงื่อนไข, และกรอกรายละเอียดธุรกิจที่ Stripe ต้องการสำหรับการปฏิบัติตามข้อกำหนด KYC ของตนเอง ตัวสลับจะเปิดใช้งาน Identity สำหรับทั้งโหมดทดสอบและโหมดใช้งานจริงในบัญชีของคุณ

การตรวจสอบสิทธิ์ใช้คีย์ลับ Stripe มาตรฐานของคุณ คีย์ทดสอบเริ่มต้นด้วย sk_test_ และคีย์ใช้งานจริงเริ่มต้นด้วย sk_live_ Stripe Identity ไม่ต้องใช้ข้อมูลรับรองแยกต่างหาก ซึ่งช่วยให้พื้นผิวการรวมระบบมีขนาดเล็ก

ติดตั้ง Node SDK:

npm install stripe

จากนั้นเริ่มต้นไคลเอ็นต์ กำหนดเวอร์ชัน API เพื่อให้ Stripe ไม่ทำให้คุณประหลาดใจกับการเปลี่ยนแปลงสคีมา:

import Stripe from "stripe";

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

ตอนนี้คุณสามารถเรียกใช้ปลายทางทุกจุดภายใต้ stripe.identity.verificationSessions ได้แล้ว

ปลายทางหลัก

การสร้าง VerificationSession

VerificationSession คือออบเจกต์เดียวที่คุณสร้างต่อความพยายามในการยืนยันผู้ใช้แต่ละครั้ง ซึ่งควบคุมประเภทเอกสารที่ยอมรับ, จำเป็นต้องถ่ายเซลฟี่หรือไม่, และฟิลด์ใดบ้างที่จะส่งคืนไปยังแบ็กเอนด์ของคุณ

ด้วย 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"

ด้วย 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" },
});

// Send one of these to the client:
// session.url              -> hosted redirect
// session.client_secret    -> Stripe.js embedded component

มีฟิลด์บางส่วนที่ควรให้ความสนใจ type: "document" บอกให้ Stripe ทำการตรวจสอบเอกสาร; อีกทางเลือกหนึ่งคือ id_number ซึ่งจะทำการค้นหาแบบ SSN เฉพาะในสหรัฐอเมริกาโดยไม่ต้องเก็บ ID allowed_types จำกัดประเภทเอกสารที่ผู้ใช้สามารถอัปโหลดได้ ซึ่งสำคัญสำหรับโปรแกรมการปฏิบัติตามข้อกำหนดที่ยอมรับเฉพาะบัตรประจำตัวที่มีรูปถ่ายที่ออกโดยรัฐบาลเท่านั้น verified_outputs คือรายการที่อนุญาตของฟิลด์ที่คุณต้องการให้ส่งคืน; Stripe จะไม่เปิดเผยข้อมูลใดๆ ที่คุณไม่ได้ร้องขอ ซึ่งช่วยให้การเก็บข้อมูลของคุณสะอาด

การเปลี่ยนเส้นทางการยืนยันแบบโฮสต์เทียบกับ Stripe.js แบบฝัง

Stripe มีรูปแบบการรวมระบบให้คุณสองรูปแบบ การเปลี่ยนเส้นทางแบบโฮสต์เป็นวิธีที่เร็วที่สุด: ส่งผู้ใช้ไปยัง session.url, Stripe จะจัดการประสบการณ์การจับภาพทั้งหมดบนโดเมน stripe.com, และผู้ใช้จะถูกส่งกลับไปยัง return_url ของคุณ คุณเขียนโค้ดประมาณสิบบรรทัดเท่านั้น

ขั้นตอนแบบฝังจะใช้ Stripe.js และแพ็คเกจ @stripe/stripe-js เพื่อติดตั้งโมดอลการยืนยันภายในแอปของคุณเอง คุณส่ง session.client_secret ไปยังฟรอนต์เอนด์และเรียกใช้ stripe.verifyIdentity(clientSecret) วิธีนี้ช่วยให้ผู้ใช้อยู่ในผลิตภัณฑ์ของคุณและให้คุณควบคุมการออกแบบของหน้าเว็บโดยรอบได้ เลือกใช้เมื่อการยืนยันเกิดขึ้นในระหว่างขั้นตอนการสมัครหรือ KYC; เลือกการเปลี่ยนเส้นทางเมื่อการยืนยันเป็นภารกิจที่แยกต่างหาก

Webhooks

อย่าพึ่งพาการเปลี่ยนเส้นทางของไคลเอ็นต์เพื่อบอกว่าการยืนยันสำเร็จ; ควรยืนยันจากแบ็กเอนด์เสมอผ่าน webhooks ลงทะเบียนปลายทางที่แดชบอร์ด > นักพัฒนา > Webhooks และสมัครรับข้อมูล:

• identity.verification_session.verified จะทำงานเมื่อการตรวจสอบทั้งหมดผ่านและข้อมูลที่ยืนยันแล้วพร้อมใช้งาน
• identity.verification_session.requires_input จะทำงานเมื่อผู้ใช้ตรวจสอบไม่ผ่านหรืออัปโหลดเอกสารที่อ่านไม่ได้ คุณสามารถเปลี่ยนเส้นทางพวกเขากลับไปลองใหม่ได้
• identity.verification_session.processing จะทำงานในขณะที่ Stripe กำลังทำการตรวจสอบแบบอะซิงโครนัส; มีประโยชน์สำหรับการแสดงสถานะการโหลด
• identity.verification_session.canceled จะทำงานหากคุณยกเลิกเซสชันด้วยโปรแกรม

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 });
});

การเรียกดูผลลัพธ์ที่ยืนยันแล้ว

เพย์โหลดของ webhook จะบอกคุณว่าเซสชันได้รับการยืนยันแล้ว แต่ไม่รวมฟิลด์ที่ละเอียดอ่อน หากต้องการอ่านผลลัพธ์ที่ยืนยันแล้ว ให้เรียกใช้ verificationSessions.retrieve โดยมี 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 จะคืนค่า id_number เพียงครั้งเดียวเท่านั้น; คุณควรจัดเก็บเป็นข้อมูลที่เข้ารหัสทันทีในฝั่งของคุณ ส่วนรูปภาพเอกสารจะยังคงอยู่ในห้องนิรภัยของ Stripe และสามารถเข้าถึงได้ผ่านแดชบอร์ดเพื่อการตรวจสอบ

ข้อผิดพลาดทั่วไปและข้อจำกัดอัตรา

ความล้มเหลวที่พบบ่อยที่สุดคือ verification_session.requires_input พร้อมรหัสเช่น document_unverified_other หรือ selfie_face_mismatch จัดการสิ่งเหล่านี้โดยการแสดง UI ให้ลองใหม่ที่เป็นมิตร; เซสชันเดียวกันสามารถนำกลับมาใช้ใหม่ได้โดยการเรียกใช้ verificationSessions.cancel และสร้างเซสชันใหม่ หรือโดยการเปลี่ยนเส้นทางไปยัง session.url เดิมในขณะที่ยังเปิดอยู่

Stripe ใช้ข้อจำกัดอัตรา API มาตรฐานที่ 100 คำขอต่อวินาทีในโหมดใช้งานจริง และ 25 คำขอต่อวินาทีในโหมดทดสอบ ปลายทาง /identity/verification_sessions อยู่ภายใต้กลุ่มเดียวกับ API ส่วนที่เหลือ หากคุณถึงขีดจำกัด คุณจะเห็น HTTP 429 พร้อมส่วนหัว Retry-After; ให้ใช้ exponential backoff และปฏิบัติตามส่วนหัวนั้น

ข้อผิดพลาดอื่นๆ ที่ควรระวัง: unsupported_document_type เมื่อผู้ใช้อัปโหลด ID ที่อยู่นอกรายการ allowed_types ของคุณ และ country_not_supported เมื่อมีคนพยายามใช้เอกสารจากประเทศที่ Stripe Identity ยังไม่รองรับ

ราคา Stripe Identity

Stripe Identity มีค่าใช้จ่าย 1.50 ดอลลาร์สหรัฐฯ ต่อการยืนยันในสหรัฐอเมริกา ราคาในต่างประเทศแตกต่างกันไป; ประเทศในยุโรปส่วนใหญ่จะอยู่ที่ประมาณ 1.50 ถึง 2.00 ดอลลาร์สหรัฐฯ และ Stripe ได้เผยแพร่รายละเอียดราคาต่อประเทศทั้งหมดในหน้าการกำหนดราคา การพยายามยืนยันที่สิ้นสุดด้วย requires_input จะไม่นับเป็นเหตุการณ์ที่ต้องชำระเงิน; เฉพาะเซสชันที่ verified ที่เสร็จสมบูรณ์เท่านั้นที่จะถูกเรียกเก็บเงิน

สำหรับลูกค้าที่มีปริมาณมาก Stripe เสนอราคาแบบกำหนดเองที่สามารถลดค่าธรรมเนียมต่อการตรวจสอบลงได้อย่างมาก หากคุณประมวลผลการยืนยันมากกว่า 10,000 ครั้งต่อเดือน โปรดติดต่อฝ่ายขาย

การทดสอบ Stripe Identity ด้วย Apidog

API Playgrounds ดีกว่าการเขียนคำสั่ง curl ด้วยมือเสมอ โดยเฉพาะเมื่อคุณกำลังวนซ้ำในเพย์โหลดของ webhook Apidog นำเข้า OpenAPI spec ของ Stripe โดยตรง ดังนั้นทุกฟิลด์บนออบเจกต์ VerificationSession จะแสดงขึ้นพร้อมเอกสารประกอบในบรรทัด คุณสามารถส่งคำขอจริงไปยังสภาพแวดล้อมการทดสอบของ Stripe ตรวจสอบการตอบกลับ และเล่นซ้ำได้หลายครั้งเท่าที่คุณต้องการ

ด้านการทดสอบ webhook คือส่วนที่ Apidog ประหยัดเวลาได้มากที่สุด คุณสามารถจำลองเหตุการณ์ identity.verification_session.verified ในเครื่อง ส่งไปยังเซิร์ฟเวอร์สำหรับนักพัฒนาของคุณ และตรวจสอบโค้ด handler ของคุณโดยไม่จำเป็นต้องมีการยืนยันจริงให้เสร็จสมบูรณ์ หากคุณกำลังเปรียบเทียบเวิร์กโฟลว์ คู่มือของเราเกี่ยวกับ การทดสอบ API โดยไม่ต้องใช้ Postman ในปี 2026 มีคำแนะนำเชิงลึกมากขึ้น ดาวน์โหลด Apidog เพื่อรับไคลเอนต์เดสก์ท็อป

คำถามที่พบบ่อย

Stripe Identity กับ KYC ปกติของ Stripe ต่างกันอย่างไร? KYC ในตัวของ Stripe ยืนยันเจ้าของธุรกิจสำหรับบัญชี Connect และ Payments ส่วน Stripe Identity เป็น API แบบสแตนด์อโลนสำหรับยืนยันผู้ใช้ปลายทางของคุณ; ระบบทั้งสองไม่แชร์ผลการยืนยันกัน

ฉันสามารถใช้ข้อมูลประจำตัวที่ยืนยันแล้วซ้ำในหลายเซสชันได้หรือไม่? ได้ เมื่อเซสชันได้รับการยืนยันแล้ว verified_outputs จะคงอยู่ถาวรบนออบเจกต์เซสชันนั้น หากคุณต้องการยืนยันซ้ำสำหรับเหตุการณ์ใหม่ ให้สร้างเซสชันใหม่และเชื่อมโยงกับบันทึกผู้ใช้ในฝั่งของคุณ

Stripe Identity ใช้งานได้นอกเหนือจากการชำระเงินหรือไม่? แน่นอน ลูกค้าจำนวนมากใช้มันเป็นเพียงชั้น KYC และไม่เคยแตะพื้นผิวการชำระเงินของ Stripe เลย หากคุณต้องการการคัดกรองการคว่ำบาตรที่กว้างขึ้นนอกเหนือจากการยืนยัน ID ให้จับคู่กับ API คัดกรอง AML โดยเฉพาะ

Stripe Identity เปรียบเทียบกับ Plaid Identity Verification อย่างไร? Stripe มุ่งเน้นไปที่เอกสารบวกเซลฟี่; Plaid เน้นข้อมูลระบุตัวตนที่ธนาคารยืนยัน โปรดดู คู่มือ API ของ Plaid ของเราสำหรับแนวทางอื่น

การตรวจสอบความมีชีวิตด้วยเซลฟี่เป็นข้อบังคับหรือไม่? ไม่ หากคุณต้องการเพียงการตรวจสอบเอกสาร ให้ตั้งค่า options.document.require_matching_selfie เป็น false ทีมป้องกันการฉ้อโกงส่วนใหญ่จะเปิดใช้งานไว้ เนื่องจาก liveness แบบพาสซีฟสามารถจับการโจมตีที่มีความพยายามต่ำได้มาก

Stripe Identity ครอบคลุมประเทศใดบ้าง? ครอบคลุมกว่า 35 ประเทศในอเมริกาเหนือ ยุโรป และบางส่วนของเอเชียแปซิฟิก พร้อมตัวแยกวิเคราะห์เอกสารที่แปลเป็นภาษาท้องถิ่นสำหรับแต่ละประเทศ Stripe เผยแพร่รายการประเทศที่รองรับในเอกสารของตนและเพิ่มตลาดใหม่ๆ อย่างสม่ำเสมอ