DEV Community

Cover image for دليل المطور: استخدام Stripe Identity API للتحقق من الهوية
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

دليل المطور: استخدام Stripe Identity API للتحقق من الهوية

إن التحقق من هوية المستخدم الحقيقية هو مهمة غالبًا ما تبدو بسيطة أثناء التصميم، لكنها تتحول لمشروع معقد عند التنفيذ العملي. يتطلب الأمر التقاط مستندات، تشغيل OCR، مطابقة وجه، التأكد من الحيوية، تحليل إشارات الاحتيال، وتغطية أنواع هويات متنوعة لكل دولة. تجمع واجهة Stripe Identity كل هذه العمليات في نقطة تكامل واحدة بحيث تستطيع بناء تدفق تحقق جاهز للإنتاج بسرعة وسهولة.

جرّب Apidog اليوم

هذا الدليل يوضح كل خطوة تقنية يحتاجها المطور لاعتماد Stripe Identity: من تفعيل الخدمة في لوحة التحكم، إنشاء VerificationSession، الاختيار بين تدفق إعادة التوجيه أو دمج Stripe.js، التعامل مع webhooks، وقراءة النتائج النهائية. ستجد أمثلة عملية باستخدام curl وNode، كيفية التعامل مع الأخطاء، وكيفية اختبار العملية بالكامل محليًا باستعمال Apidog. إذا كنت تبحث عن بدائل، اطلع على قائمتنا لأفضل واجهات KYC API قبل اتخاذ قرار.

يعتبر Stripe Identity الخيار الأمثل للفرق التي تستخدم Stripe للمدفوعات، لكنه يعمل كمنتج مستقل أيضًا. الوثائق الرسمية ممتازة لواجهة المنتج، لكن هذا الدليل التقني يركز على التفاصيل العملية: ماذا يحصل على الشبكة، الحقول المهمة، وأين تظهر المشاكل الشائعة.

باختصار عملي

  • Stripe Identity يتحقق من المستخدمين بواسطة مستند حكومي وصورة ذاتية، ابتداءً من 1.50 دولار لكل تحقق في الولايات المتحدة.
  • العنصر المركزي هو VerificationSession؛ أنشئه من السيرفر، ثم اعمل redirect أو دمج Stripe.js.
  • حدد الحقول المطلوبة عبر options.document.require_matching_selfie، require_id_number، وallowed_types.
  • تابع حالة التحقق من خلال webhooks: identity.verification_session.verified وidentity.verification_session.requires_input.
  • المخرجات المتحقق منها (كالاسم وتاريخ الميلاد) تظهر فقط إذا طلبتها صراحةً في verified_outputs عند إنشاء الجلسة.
  • يدعم Stripe Identity أكثر من 35 دولة مع مستندات محلية.

ما هي Stripe Identity API؟

Stripe Identity توفر نقطة نهاية واحدة (/v1/identity/verification_sessions) لإدارة عملية التحقق: التقاط المستندات، استخراج البيانات، مطابقة الوجه، وتسجيل إشارات الاحتيال. النتيجة هي سجل آمن وموثق يتضمن بيانات المستخدم وصور المستندات.

يعتمد Stripe على مفهوم الجلسة (Session) المشابه لعمليات Checkout وPayment Intents. أنشئ جلسة من السيرفر، واترك Stripe يدير واجهة الالتقاط. بمجرد الجاهزية، يتم إعلامك عبر webhook. إذا سبق وأنشأت تدفق Checkout، ستجد Identity مألوف جدًا.

المصادقة والإعداد السريع

قبل استدعاء API، فعّل Stripe Identity عبر لوحة التحكم: إعدادات > الهوية، وافق على الشروط، وأدخل بيانات عملك للامتثال لنظم KYC.

استخدم مفتاح Stripe السري المعتاد (يبدأ بـsk_test_ في الاختبار أو sk_live_ في الإنتاج).

ثبّت Stripe SDK في مشروع NodeJS:

npm install stripe

ثم فعّل العميل وحدد إصدار الـ API:

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

// أرسل أحد هذه القيم للعميل:
// session.url              --> إعادة توجيه مستضافة
// session.client_secret    --> مكون Stripe.js مدمج

الحقول الهامة:

  • type: "document": يحدد نوع التحقق (مستندات). استخدم id_number فقط إذا كنت بحاجة لبحث SSN أمريكي دون مستند.
  • allowed_types: يحدد أنواع المستندات المقبولة (مثلاً رخصة قيادة أو جواز سفر).
  • verified_outputs: قائمة الحقول التي تريد استرجاعها. Stripe لن يعيد أي حقل لم تطلبه صراحةً.

التحقق المستضاف مقابل Stripe.js المدمج

لديك خياران:

  • إعادة توجيه مستضافة: أرسل المستخدم إلى session.url، حيث يدير Stripe كل خطوات التحقق ثم يرجع المستخدم إلى return_url الخاص بك. أسرع وأبسط.
  • التدفق المدمج (Embedded): استخدم @stripe/stripe-js ومرر session.client_secret إلى الواجهة الأمامية، ثم استدعِ stripe.verifyIdentity(clientSecret). هذا الخيار يعطيك تحكم أكبر في تجربة المستخدم.
اختر التدفق الأنسب اعتمادًا على مكانية التحقق ضمن رحلتك البرمجية.

التعامل مع 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;

انتبه: id_number لن يعاد إلا مرة واحدة، لذا خزنه مباشرة وبطريقة آمنة. صور المستندات تبقى في لوحة تحكم Stripe فقط.

الأخطاء الشائعة وحدود الطلبات

أكثر الأخطاء شيوعًا:

  • verification_session.requires_input مع رموز كـ document_unverified_other أو selfie_face_mismatch.
  • حل: أعطِ للمستخدم خيار إعادة المحاولة. يمكنك إعادة استخدام الجلسة المفتوحة أو إلغاؤها وصنع واحدة جديدة.
  • حدود الطلبات: 100 طلب/ثانية (إنتاجي)، 25 طلب/ثانية (اختبار). إذا تجاوزت الحد، ستتلقى HTTP 429 مع Retry-After.
  • أخطاء إضافية: unsupported_document_type (نوع مستند غير مقبول)، country_not_supported (بلد غير مدعوم).

تسعير Stripe Identity

السعر يبدأ من 1.50 دولار لكل تحقق ناجح في الولايات المتحدة. تختلف الأسعار دوليًا (بين 1.50 و2.00 دولار لغالبية أوروبا). الجلسات التي لا تنجح (requires_input) ليست قابلة للفوترة. المؤسسات الكبيرة يمكنها التفاوض مع Stripe لأسعار أقل إذا تجاوزت 10,000 تحقق شهريًا.

اختبار Stripe Identity باستخدام Apidog

بدلاً من كتابة أوامر curl يدويًا، استخدم Apidog لاستيراد OpenAPI الخاص بـStripe، بحيث تظهر كل الحقول والخيارات بوضوح. يمكنك تنفيذ طلبات حقيقية على بيئة الاختبار وفحص الاستجابة بسهولة.

يتميز Apidog أيضًا باختبار الـ webhooks: يمكنك محاكاة أحداث مثل identity.verification_session.verified محليًا وإرسالها إلى خادم التطوير لديك لاختبار التدفق بدون الحاجة لإكمال تحقق حقيقي كل مرة. لمزيد من التفاصيل، راجع دليلنا حول اختبار API بدون Postman. قم بتنزيل Apidog لبيئة سطح المكتب.

الأسئلة الشائعة

ما الفرق بين Stripe Identity وKYC العادي في Stripe؟ نظام KYC ضمن Stripe يخص التحقق من أصحاب الأعمال لحسابات Connect وPayments. أما Stripe Identity فهو API مستقل للتحقق من المستخدمين النهائيين فقط، ولا تتشارك الأنظمة النتائج.

هل يمكن إعادة استخدام هوية متحققة عبر جلسات مختلفة؟ نعم، القيم في verified_outputs تبقى موجودة على كائن الجلسة. إذا احتجت تحقق جديد، أنشئ جلسة جديدة واربطها بالمستخدم.

هل Stripe Identity مرتبط فقط بالمدفوعات؟ لا. يمكن استخدامه كطبقة KYC مستقلة بدون أي دمج مع مدفوعات Stripe، ويمكنك ربطه مع APIs أخرى مثل فحص AML لمزيد من التدقيق.

كيف يقارن Stripe Identity مع Plaid Identity Verification؟ يركز Stripe على مستند وصورة ذاتية، بينما Plaid يعتمد على بيانات الهوية من البنوك. راجع دليل Plaid API لدينا لمقارنة الأساليب.

هل فحص حيوية الصورة الذاتية مطلوب دائمًا؟ لا، يمكنك تعطيل options.document.require_matching_selfie إذا لم تحتج فحص صورة، لكن معظم فرق مكافحة الاحتيال تتركه مفعّلًا.

ما هي الدول المدعومة؟ أكثر من 35 دولة في أمريكا الشمالية، أوروبا، وأجزاء من آسيا والمحيط الهادئ، مع دعم مستندات محلية. راجع قائمة الدول المحدثة في وثائق Stripe.

Top comments (0)