DEV Community

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

Posted on • Originally published at apidog.com

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

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

ทดลองใช้ Apidog วันนี้

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

Stripe Identity เหมาะกับทีมที่ใช้ Stripe ชำระเงินอยู่แล้ว และก็ใช้งานแบบสแตนด์อโลนได้เช่นกัน โพสต์นี้จะชี้จุดสำคัญสำหรับ developer: flow ที่เกิดขึ้น ฟิลด์ที่สำคัญ และ common gotchas ที่ควรรู้

สรุป (TL;DR)

  • Stripe Identity ยืนยันผู้ใช้ด้วยเอกสารที่รัฐออกให้ + selfie liveness; ราคาเริ่มที่ $1.50 ต่อการยืนยันในสหรัฐฯ
  • หัวใจของระบบคือ object VerificationSession; สร้างที่ backend แล้ว redirect หรือ embed Stripe.js
  • เลือกฟิลด์ที่ต้องการผ่าน options.document.require_matching_selfie, require_id_number, allowed_types
  • ตั้ง webhook สำหรับ identity.verification_session.verified และ identity.verification_session.requires_input เพื่ออัปเดตสถานะ
  • ข้อมูลที่ยืนยันจะถูกส่งกลับเฉพาะฟิลด์ที่ขอผ่าน verified_outputs
  • รองรับ 35+ ประเทศ เอกสารท้องถิ่นหลายรูปแบบ

Stripe Identity API คืออะไร?

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

Workflow คือสร้าง session ฝั่ง backend, Stripe จัดการ UI ให้ user เอง, และ backend รับ webhook ผลลัพธ์ เมื่อเคยใช้ Stripe Checkout หรือ Payment Intents แล้ว จะเข้าใจ flow ได้ทันที

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

1. เปิด Stripe Identity ในแดชบอร์ด: ไปที่ Settings > Identity, ยอมรับข้อตกลง และกรอกข้อมูลบริษัท

2. ใช้ Stripe Secret Key มาตรฐาน (sk_test_... สำหรับ test, sk_live_... สำหรับ production) ไม่ต้องแยก credential ใหม่

3. ติดตั้ง Node SDK:

npm install stripe

4. เริ่มต้น client และระบุ API version:

import Stripe from "stripe";

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

ตอนนี้สามารถใช้ทุก method ใต้ stripe.identity.verificationSessions ได้แล้ว

ปลายทางหลัก

สร้าง VerificationSession (ขั้นตอนหลัก)

สร้าง session ใหม่สำหรับแต่ละการยืนยัน:

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

// เลือกส่งไป client:
// session.url              -> hosted redirect
// session.client_secret    -> Stripe.js embedded

ฟิลด์สำคัญ:

  • type: "document" = ตรวจสอบเอกสาร (หรือ id_number เฉพาะ US)
  • allowed_types = จำกัดประเภทเอกสาร
  • verified_outputs = ฟิลด์ข้อมูลที่ต้องการให้ backend ได้รับ

โฮสต์ redirect vs Stripe.js embedded

เลือกวิธีรวมระบบ:

  • Hosted redirect: ส่ง user ไป session.url Stripe จัดการ UI ทั้งหมดและ redirect กลับ return_url
  • Embedded (Stripe.js): ส่ง session.client_secret ไป frontend แล้วเรียก stripe.verifyIdentity(clientSecret) ในแอปของคุณ เหมาะกับฟลูว์ onboard

Webhooks

อย่าใช้ client redirect เป็นตัวบอกว่า identity สำเร็จ ควรเชื่อมต่อ webhook ที่ backend เสมอ:

  • 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 จะบอกว่าเซสชัน verified แล้ว แต่ถ้าต้องการข้อมูลเต็ม ให้ดึง session เพิ่ม 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;

ข้อควรระวัง: id_number จะถูกคืนแค่ครั้งเดียว ควรเข้ารหัสและจัดเก็บทันที

ข้อผิดพลาด/ข้อจำกัดอัตรา

  • ข้อผิดพลาดทั่วไป: verification_session.requires_input (เช่น document_unverified_other, selfie_face_mismatch) ให้ UI ลองใหม่ได้โดยใช้ session เดิมหรือสร้างใหม่
  • Rate limit: 100 req/sec (prod), 25 req/sec (test) ถ้าเกินจะได้ HTTP 429 + Retry-After ควร exponential backoff
  • ข้อผิดพลาดอื่น: unsupported_document_type, country_not_supported

ราคา Stripe Identity

  • เริ่มต้น $1.50 ต่อ verification ในสหรัฐฯ
  • ยุโรปประมาณ $1.50-2.00 ต่อครั้ง
  • เฉพาะ session ที่ status verified เท่านั้นที่ถูกคิดเงิน (ถ้า requires_input ไม่คิดเงิน)
  • ปริมาณมาก (10,000+/เดือน) ขอราคาพิเศษได้

ทดสอบ Stripe Identity ด้วย Apidog

API Playground อย่าง Apidog ช่วยให้ทดสอบ Stripe Identity ได้เร็วกว่าเขียน curl เอง เพราะสามารถนำเข้า OpenAPI Spec ของ Stripe ได้โดยตรง ทุกฟิลด์ของ VerificationSession จะมี doc ครบ สามารถยิง request จริงไปยัง Stripe test environment, ดู response และ replay ได้ทันที

จุดเด่นอีกอย่างคือ test webhook: สามารถจำลอง event identity.verification_session.verified ส่งไปยัง dev server ของคุณ แล้วตรวจสอบ logic ได้โดยไม่ต้องรอ user จริง หากสนใจเปรียบเทียบเวิร์กโฟลว์ อ่านคู่มือ ทดสอบ API โดยไม่ต้องใช้ Postman หรือ ดาวน์โหลด Apidog เพื่อทดลอง client desktop

<!--kg-card-begin: html-->







<!--kg-card-end: html-->

FAQ

  • Stripe Identity ต่างกับ KYC ปกติของ Stripe ยังไง? KYC ปกติใช้สำหรับ onboarding business (Connect/Payments) แต่ Stripe Identity เป็น API สำหรับตรวจสอบลูกค้าปลายทาง ผลลัพธ์ไม่แชร์กัน
  • ใช้ข้อมูลยืนยันซ้ำในหลาย session ได้ไหม? ได้ ข้อมูล verified_outputs จะอยู่กับ session ถาวร ถ้าต้องการ re-verify สร้าง session ใหม่แล้วผูกกับ user record
  • Stripe Identity ใช้งานโดยไม่เกี่ยวกับ payment ได้หรือไม่? ได้ หลาย use-case ใช้เฉพาะ KYC ไม่ผูกกับ payment หากต้องการ AML screening เพิ่มเติม แนะนำอ่าน API คัดกรอง AML
  • Stripe Identity vs Plaid Identity Verification? Stripe มุ่งที่เอกสาร+เซลฟี่, Plaid ดึงข้อมูลที่สถาบันการเงินยืนยัน ดู คู่มือ Plaid API
  • Selfie liveness เป็นข้อบังคับไหม? ไม่ต้องเปิดก็ได้ (require_matching_selfie: false) แต่ทีม fraud ส่วนมากแนะนำเปิดใช้
  • Stripe Identity รองรับประเทศอะไรบ้าง? 35+ ประเทศในอเมริกาเหนือ, ยุโรป, เอเชียแปซิฟิก ดูรายชื่อประเทศในเอกสาร Stripe ซึ่งอัปเดตเพิ่มตลาดใหม่เป็นระยะ

Top comments (0)