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

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

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

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

باختصار

• يتحقق Stripe Identity من المستخدمين باستخدام هوية حكومية بالإضافة إلى فحص حيوية الصورة الذاتية؛ وتبدأ الأسعار من 1.50 دولار لكل عملية تحقق في الولايات المتحدة.
• العنصر الأساسي هو كائن VerificationSession؛ تقوم بإنشاء واحد من جانب الخادم، ثم تعيد توجيه المستخدم أو تثبيت مكون 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؟

Stripe Identity هو منتج للتحقق من الهوية مبني على واجهة برمجة تطبيقات Stripe الأساسية. يوفر لك عائلة نقاط نهاية واحدة (/v1/identity/verification_sessions) تنسق التقاط المستندات، واستخراج البيانات، ومطابقة الوجه، وتسجيل نقاط الاحتيال. الناتج هو سجل موثوق وموقع ومنظم: اسم كامل متحقق منه، تاريخ الميلاد، العنوان، ورقم هوية اختياري، مقترنًا بصور المستند الأصلي المخزنة في خزانة Stripe.

تحت الغطاء، يستخدم Stripe نفس نمط الجلسة بالإضافة إلى الـ webhook الذي تعرفه بالفعل من Checkout و Payment Intents. تقوم بإنشاء جلسة من جانب الخادم، ويتولى Stripe واجهة المستخدم لالتقاط البيانات، ويتم إعلامك عندما تكون النتيجة جاهزة. إذا قمت ببناء تدفق Checkout من قبل، فسيبدو Identity مألوفًا في غضون دقائق.

المصادقة والإعداد

قبل استدعاء واجهة برمجة التطبيقات، قم بتشغيل Stripe Identity في لوحة التحكم. انتقل إلى لوحة التحكم > الإعدادات > الهوية، واقبل الشروط، واملأ تفاصيل العمل التي يحتاجها Stripe للامتثال لـ KYC من جانبه. ينشط التبديل الهوية لوضع الاختبار والوضع المباشر على حسابك.

تستخدم المصادقة مفتاح 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) في الولايات المتحدة فقط دون جمع هوية. يحدد 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. تعامل مع هذه الحالات عن طريق عرض واجهة مستخدم ودية للمحاولة مرة أخرى؛ يمكن إعادة استخدام نفس الجلسة عن طريق استدعاء verificationSessions.cancel وإنشاء جلسة جديدة، أو عن طريق إعادة التوجيه إلى نفس session.url بينما لا تزال مفتوحة.

يطبق Stripe حدودًا قياسية لمعدل استدعاءات API تبلغ 100 طلب في الثانية في الوضع المباشر و 25 طلبًا في الثانية في وضع الاختبار. تقع نقاط نهاية /identity/verification_sessions ضمن نفس الفئة مثل بقية واجهة برمجة التطبيقات. إذا وصلت إلى الحدود، سترى HTTP 429 مع ترويسة Retry-After؛ استخدم التراجع الأسي (exponential backoff) واحترم الترويسة.

أخطاء أخرى يجب الانتباه إليها: unsupported_document_type عندما يقوم المستخدم بتحميل هوية خارج قائمة 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 على كتابة أوامر curl يدويًا في كل مرة، خاصة عندما تقوم بتكرار العمل على حمولات الـ webhook. يقوم Apidog باستيراد مواصفات OpenAPI الخاصة بـ Stripe مباشرةً، لذا يظهر كل حقل في كائن VerificationSession مع توثيق مضمن. يمكنك إطلاق طلبات حقيقية في بيئة اختبار Stripe، وفحص الاستجابة، وإعادة تشغيلها عدة مرات حسب حاجتك.

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

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

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

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

هل يعمل Stripe Identity خارج نطاق المدفوعات؟ بالتأكيد. يستخدم العديد من العملاء Stripe Identity كطبقة KYC بحتة ولا يلمسون واجهة مدفوعات Stripe أبدًا. إذا كنت بحاجة إلى فحص أوسع للعقوبات بالإضافة إلى التحقق من الهوية، فقم بإقرانه بواجهة برمجة تطبيقات مخصصة لـ فحص AML.

كيف يقارن Stripe Identity بخدمة Plaid Identity Verification؟ يركز Stripe على المستند بالإضافة إلى الصورة الذاتية؛ بينما يميل Plaid إلى بيانات الهوية المتحقق منها من البنوك. راجع دليل Plaid API الخاص بنا للنهج الآخر.

هل فحص حيوية الصورة الذاتية إلزامي؟ لا. قم بتعيين options.document.require_matching_selfie إلى false إذا كنت تحتاج فقط إلى فحص مستند. تبقي معظم فرق مكافحة الاحتيال هذه الميزة مفعلة، لأن الكشف السلبي عن الحيوية يوقف العديد من الهجمات منخفضة الجهد.

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