معاملات الدفع

قبل أن تبدأ

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

Base URL

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

إنشاء معاملة

POST /credit/transaction — ينشئ معاملة جديدة.

خطر

لضمان تحويل أفضل، قم بإنشاء المعاملة فقط بعد إكمال أي مصادقة مسبقة أو تحقق قد ينهي العملية قبل تجربة التحقق من البطاقة غير الحاضرة.

خطر

يجب تعبئة حقل orderNumber برقم الطلب الفريد لتلك العملية الشرائية في نظام التجارة الإلكترونية — استخدام معرّف معاملة مختلف أمر غير صحيح. قد يؤدي إعادة استخدامه إلى انخفاض معدل التحويل (رقم الطلب يساعد المستخدم النهائي على إكمال المسار) وإلى أخطاء API مثل replicated transaction إذا تم استخدام نفس رقم الطلب و CPF و BIN وآخر 4 أرقام.

Headers

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

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ],
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}

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

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...",
  "expiresAt": "2026-07-22T15:30:00Z"
}

الحقل	الوصف
id	معرّف المعاملة التي تم إنشاؤها.
status	حالة المعاملة الحالية.
link	الرابط المرتبط بالمعاملة.
token	رمز موقّع يحتوي على المعلمات اللازمة لتهيئة SDK الويب الخاص بالتحقق من البطاقة غير الحاضرة.
expiresAt	تاريخ ووقت انتهاء صلاحية المعاملة، بصيغة ISO 8601 (UTC).

تحذير

إذا حدد التحقق أن الالتقاط البيومتري غير مطلوب، تكون الاستجابة بحالة مختلفة ولا يتم إنشاء رابط التقاط:

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

يحدث هذا عند استخدام وحدتي Pre أو Super Pre لصفحة الدفع (Checkout)، وفقًا لـ الميزة.

ملاحظة

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

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

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

للاطلاع على استجابات الأخطاء، راجع الأخطاء — إنشاء المعاملة.

الحصول على حالة المعاملة

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

Headers

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

200 OK

{
  "status": "processing"
}

الحقل	الوصف
status	الحالة الحالية للمعاملة.

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

للاطلاع على استجابات الأخطاء، راجع الأخطاء — الحصول على حالة المعاملة.

الحصول على مجموعة إثباتات المعاملة

GET /credit/transactions/{transaction_id}/probative — يسترجع مجموعة الإثباتات لمعاملة محددة.

تحذير

لا يمكن إنشاء مجموعة الإثباتات إلا للمعاملات التي تمت الموافقة عليها.

خطر

الرابط المُعاد لمجموعة الإثباتات صالح لمدة خمس دقائق بعد الحصول عليه — لا تقم بحفظه، استخدمه لتنزيل مجموعة الإثباتات فورًا.

Headers

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

200 OK

{
  "link": "https://unico.io/probative.pdf"
}

الحقل	الوصف
link	عنوان URL لملف الإثبات.

للاطلاع على استجابات الأخطاء، راجع الأخطاء — استرداد مجموعة الإثباتات الخاصة بالمعاملة.

إعادة إرسال إشعار المعاملة

POST /credit/transactions/{transaction_id}/notify — يعيد إرسال الإشعارات عبر البريد الإلكتروني و/أو الهاتف لمعاملة محددة.

ملاحظة

من الممكن أيضًا تهيئة إعادة إرسال الإشعارات عبر البوابة، دون تنفيذها عبر API. تحدث مع نقطة الاتصال الخاصة بمشروعك لفهم الإمكانيات المتاحة.

Headers

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

Body

{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}

الحقل	النوع	إلزامي	الوصف
phone	string	نعم	رقم الهاتف لإرسال الإشعار إليه.
email	string	نعم	عنوان البريد الإلكتروني لإرسال الإشعار إليه.

200 OK

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

الحقل	الوصف
id	المعرّف الفريد للإشعار الذي تم إنشاؤه.
link	الرابط الذي تم إنشاؤه للإشعار.

للاطلاع على استجابات الأخطاء، راجع الأخطاء — إعادة إرسال إشعار المعاملة.