تأهيل بطاقة الائتمان

قبل أن تبدأ

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

Base URL

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

هام

يمكن إجراء تأهيل بطاقة الائتمان إما بطلب صورة سيلفي من المستخدم النهائي وإكمال التسجيل الكامل، أو بإعادة استخدام الالتقاطات البيومترية من العمليات التي نفّذتها منتجات أخرى ضمن منصة 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
}

الحقل	النوع	إلزامي	الوصف
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.
additionalInfo.processID	string	نعم (إذا تم إرسال additionalInfo)	معرّف العملية المرجعية من منصة IDCloud.

خطر

يجب تعبئة حقل 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.

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

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

Headers

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

200 OK

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

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

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

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