Onboarding بطاقة الائتمان

قبل أن تبدأ

تتم مصادقة طلبات API الخاصة بك باستخدام رمز وصول. أي طلب لا يتضمن رمز وصول صالحًا سيُعيد خطأ. تعرف على المزيد في المصادقة.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• الإنتاج (Production): https://transactions.transactional.unico.app/api/public/v1

هام

يمكن إجراء Onboarding بطاقة الائتمان إما بطلب صورة سيلفي من المستخدم النهائي وإكمال التسجيل الكامل، أو بإعادة استخدام الالتقاطات البيومترية من العمليات التي نفّذتها منتجات أخرى ضمن منصة Unico IDCloud:

• لإعادة استخدام العمليات التي أنشأتها منتجات IDCloud الأخرى، قدّم معرّف العملية المرجعية في additionalInfo.processID؛
• يجب ألا يكون قد مضى على اكتمال العملية المرجعية المُستخدمة أكثر من ساعة واحدة.

التحقق من صحة بطاقة الائتمان

POST /walletid/transaction — يتحقق من صحة بطاقة ائتمان.

Headers

Header	القيمة
Authorization	Bearer {token} — رمز وصول صالح.

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "onboarding-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/wallet/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 5000.00,
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}

الحقل	النوع	إلزامي	الوصف
identity	object	نعم	معلومات هوية المستخدم.
identity.key	string	نعم	نوع مفتاح تعريف المستخدم.
identity.value	string	نعم	قيمة مفتاح تعريف المستخدم.
orderNumber	string	نعم	الرقم المرتبط بعملية التأهيل. يُستخدم كفهرس في البوابة وكمفتاح خارجي بين نظامك والتحقق من البطاقة غير الحاضرة.
company	string	نعم	معرّف الشركة المسؤولة عن المعاملة، مُقدَّم من Unico.
redirectUrl	string	لا	عنوان URL لإعادة توجيه المستخدم بعد إكمال المعاملة (عنوان URL بصيغة HTTPS للويب، أو عنوان URL بصيغة Schema لتطبيقات الجوال الأصلية).
card	object	نعم	معلومات البطاقة المُستخدمة في المعاملة.
card.binDigits	string	نعم	أول 8 أرقام من البطاقة.
card.lastDigits	string	نعم	آخر 4 أرقام من البطاقة.
card.expirationDate	string	لا	تاريخ انتهاء صلاحية البطاقة.
card.name	string	نعم	اسم حامل البطاقة — تأكد من صحته لتجنب مشكلات الترميز أو مشكلات الموافقة.
value	number	لا	الحد الأقصى للقيمة المضمونة.
additionalInfo	object	لا	أرسل هذا الكائن مع processID لإعادة استخدام الالتقاطات البيومترية من منتجات أخرى ضمن منصة Unico IDCloud، و/أو externalUserID لتفعيل التحقق الصامت لهذه المعاملة.
additionalInfo.processID	string	لا	معرّف العملية المرجعية من منصة IDCloud.
additionalInfo.externalUserID	string	لا	نفس المعرّف الذي تم تكوينه عبر externalUserId في SDK عند جمع بيانات تعريف الجهاز. مطلوب فقط لتفعيل التحقق الصامت — بدونه، يتم إنشاء المعاملة بشكل طبيعي لكنها تتبع دائمًا التدفق البصري القياسي.

خطر

يجب تعبئة حقل orderNumber برقم الطلب الفريد لتلك العملية الشرائية في نظام التجارة الإلكترونية — استخدام معرّف معاملة مختلف أمر غير صحيح، وقد تؤدي إعادة استخدام القيم إلى أخطاء replicated transaction.

200 OK

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

الحقل	الوصف
id	معرّف المعاملة التي تم إنشاؤها.
status	حالة المعاملة الحالية.
link	الرابط المرتبط بالمعاملة. يُعاد فقط إذا لم يتم تقديم additionalInfo.processID.
token	رمز موقّع لتهيئة SDK الويب الخاص بالتحقق من البطاقة غير الحاضرة. يُعاد فقط إذا لم يتم تقديم additionalInfo.processID.

ملاحظة

إذا تم إرسال additionalInfo.externalUserID وتمت الموافقة على المعاملة بشكل صامت، فإن الاستجابة تتخطى أيضًا رابط الالتقاط:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

راجع التحقق الصامت للاطلاع على التدفق الكامل، بما في ذلك إعداد SDK ومتطلبات التوقيت.

التحقق من حالة التحقق

GET /walletid/transactions/{transaction_id} — يتحقق من الحالة الحالية لمعاملة محددة.

Headers

Header	القيمة
Authorization	Bearer {token} — رمز وصول صالح.

200 OK

{
  "status": "processing",
  "hasIdentityChanged": false
}

الحقل	الوصف
status	الحالة الحالية للمعاملة.
hasIdentityChanged	اختياري. ما إذا كان قد حدث تبديل هوية في المعاملة.

راجع القيم التعدادية للاطلاع على جميع الحالات الممكنة. لتحسين الأداء، نفّذ Webhook بدلاً من الاستقصاء المتكرر (polling) لهذه النقطة النهائية.

للاطلاع على استجابات الأخطاء، راجع الأخطاء — Onboarding بطاقة الائتمان.