يو باي منتس (UPayments)
UPayments صفحة دفع مستضافة مبنية حول الكويت — كي نت والبطاقات وأبل باي وغيرها من الطرق المفعّلة على حسابك في UPayments. يدفع المشترون على صفحة UPayments ثم يعودون إلى متجرك. الطرق التي تظهر يحددها حسابك في UPayments وليس TakeTheme.
الربط
الإعدادات ← المدفوعات ← يو باي منتس.
| بيان الاعتماد | مطلوب | أين تجده |
|---|---|---|
| مفتاح API | نعم | مفتاح API الخاص بك في UPayments (Bearer token) للبيئة التي تختارها أدناه |
| المفتاح السري لـ API | موصى به | لوحة UPayments ← Merchant API Details |
| البيئة | نعم | تجريبي (Sandbox) أو مباشر (إنتاج) |
يستخدم الاختبار والإنتاج مفاتيح مختلفة على خوادم مختلفة، لذا يجب أن يتطابق المفتاح مع البيئة. ابدأ على تجريبي بمفتاح الاختبار وبطاقة اختبار من UPayments، ثم انتقل إلى مباشر (إنتاج) بمفتاح الإنتاج. للحصول على مفاتيح الإنتاج تواص ل مع UPayments (support@upayments.com)؛ ويجب أن يجتاز حسابك مراجعة KYC لديهم قبل استقبال مدفوعات حقيقية.
المفتاح السري لـ API اختياري لكن يُنصح بإضافته:
- تشترط UPayments توقيع كل طلب API عندما يكون HMAC مفعّلاً على حسابك. عند حفظ المفتاح السري توقّع TakeTheme كل طلب؛ وبدونه تُرسل الطلبات غير موقّعة وسيرفضها أي حساب يفرض التوقيع.
- يتيح لـ TakeTheme التحقق من إشعارات الـ Webhook التي ترسلها UPayments (راجع مسار الدفع).
تُنشأ الطلبات عند عودة المشتري من UPayments: تستعلم TakeTheme عن عملية الدفع لدى UPayments أثناء العودة، لذا لا يلزم تسجيل أي شيء في المسار المعتاد. كما تمنح TakeTheme لـ UPayments رابط إشعار مع كل عملية دفع، فيُنشأ الطلب إذا دفع المشتري ثم أغلق الصفحة، أو إذا تأخر تأكيد البنك.
الإعدادات
| الإعداد | الافتراضي | وظيفته |
|---|---|---|
| اسم الدفع في صفحة الدفع | فارغ | الاسم الذي يراه العميل (مثل "كي نت أو بطاقة"). إن تُرك فارغاً يظهر "UPayments" |
| رسوم المعاملة | لا يوجد | رسوم ثابتة أو نسبية تُضاف إلى الطلب عند اختيار هذه الطريقة |
| خصم الدفع | لا يوجد | خصم يُطبَّق عند اختيار المشتري لهذه الطريقة |
| إرسال بريد تأكيد الدفع | مفعّل | يرسل بريداً للعميل عند نجاح الدفع |
| إشعار عند فشل الدفع (بريد) | فارغ | ينبّه فريقك عند فشل عملية دفع |
العملة
تُنشئ TakeTheme عملية الدفع بـعملة متجرك. تقبل UPayments KWD وSAR وUSD وBHD وEUR وOMR وQAR وAED وINR وGBP وJOD، وتحوّل أي عملة غير KWD بنفسها. قد يلزم أن تفعّل UPayments استخدام عملة غير KWD على حسابك. وإذا كانت عملة متجرك غير مدعومة لدى UPayments — مثل EGP — يعرض الدفع رسالة الخطأ من UPayments بدلاً من رابط الدفع.
تُرسل مبالغ KWD وBHD وOMR وJOD بثلاث خانات عشرية، وباقي العملات بخانتين.
إذا أبلغت UPayments عن مبلغ محصَّل يختلف عن إجمالي الطلب، تسجّل TakeTheme الفرق للمطابقة دون رفض الدفع.
مسار الدفع
- يختار المشتري UPayments ويُرسل الطلب.
- تُنشئ TakeTheme عملية دفع في UPayments (بمرجع داخلي) وتوجّه المشتري إلى صفحتها المستضافة.
- يختار المشتري طريقة الدفع ويدفع.
- تعيد UPayments المشتري إلى TakeTheme —
GET /v1/payment/upayments/return/<reference>بعد الدفع، أوGET /v1/payment/upayments/cancel/<reference>إذا ألغى. تستعلم TakeTheme عن عملية الدفع لدى UPayments بمفتاحك أنت وباستخدام الجلسة التي خزّنتها عند إنشاء العملية — وليس بأي شيء قادم من المتصفح — وفقط إذا أفادت UPayments بأنها CAPTURED تُنشئ الطلب مدفوعاً. - يصل المشتري إلى صفحة الشكر في متجرك.
ترسل UPayments أيضاً إشعاراً:
POST https://<your-api-host>/api/v1/payment/webhook/upayments
عند حفظ المفتاح السري لـ API يجب أن يحمل كل إشعار X-Signature صحيحاً (HMAC-SHA256 للطابع الزمني والطريقة والرابط الكامل والمحتوى الخام، بذلك المفتاح السري)؛ ويُرفض الإشعار بلا توقيع أو بتوقيع غير مطابق بالرمز 403. وحتى الإشعار الصحيح لا يحدد النتيجة بمفرده: هو فقط يعرّف عملية الدفع، وتُعاد قراءة الحالة من UPayments. أيهما وصل أولاً (العودة أو الإشعار) ينشئ الطلب — ولا يُنشئان طلبين.
المدفوعات الفاشلة والملغاة والمتأخرة
- العملية المرفوضة أو الفاشلة أو الملغاة أو التي حدث بها خطأ تعيد المشتري إلى فشل الدفع ليحاول مجدداً؛ ولا يُنشأ طلب.
- المشتري الذي ينسحب من صفحة UPayments قبل محاولة الدفع يصل أيضاً إلى فشل الدفع. ولا تُوسَم عملية الدفع نفسها بالفشل، فإذا نجحت العملية لاحقاً يُنشئ إشعار UPayments الطلب.
- العملية المعلّقة (بانتظار 3-D Secure أو تفويض) تُعامَل على أنها لم تُحسم بعد — يواصل المتجر التحقق بدلاً من إخبار المشتري بأنها فشلت.
- قد يتأخر تأكيد كي نت — قد تستغرق UPayments حتى نحو 13 دقيقة لتسوية بعض مدفوعات كي نت. وعند حدوث ذلك يُنشئ الإشعار الطلب حتى لو غادر المشتري.
وأثناء انتظار عملية معلّقة تتحقق صفحة الشكر من UPayments بوتيرة محدودة، لأن UPayments تسمح بـ 30 استعلاماً عن الحالة في الدقيقة لكل مفتاح وتحظر المفتاح عند تجاوزها. ولا يتأثر بهذا الحد عودة المشتري ولا إشعار UPayments.
اللغة
تفتح صفحة UPayments بالإنجليزية، ويمكن للمشتري تغيير اللغة منها.
الاسترداد
عمليات الاسترداد تُسجَّل في TakeTheme فقط — لا يصل أي طلب استرداد إلى UPayments. نفّذ الاسترداد من لوحة UPayments ثم سجّله هنا. راجع الاسترداد.
استكشاف الأخطاء
يقول الدفع إن UPayments رفضت مفتاح API. المفتاح لا يطابق البيئة. مفاتيح الاختبار تعمل على التجريبي فقط ومفاتيح الإنتاج على المباشر فقط. أعد حفظ المفتاح مع البيئة الصحيحة.
يقول الدفع إن UPayments رفضت توقيع الطلب. المفتاح السري لـ API خاطئ أو يخص بيئة غير بيئة المفتاح. انسخه مجدداً من Merchant API Details. وإذا قالت الرسالة إن التوقيع انتهت صلاحيته فساعة الخادم غير متزامنة — تواصل مع الدعم.
يقول الدفع إن العملة غير صالحة أو غير مدعومة. UPayments لا تقبل عملة متجرك (راجع العملة). لعملة غير KWD اطلب من UPayments تفعيل تعدد العملات على حسابك.
دفع المشتري لكن لم يظهر طلب.
افتح سجل الدفع للطلب: إذا تعذّر الوصول إلى UPayments أثناء الاستعلام، يواصل المتجر المحاولة ويظهر الطلب بمجرد النجاح؛ ودفعة كي نت المؤكَّدة متأخرة يظهر طلبها عند وصول الإشعار. ظهور 403 في سجل الـ Webhook يعني أن توقيع الإشعار لا يطابق المفتاح السري المحفوظ — أعد حفظه.
طريقة دفع غير ظاهرة في صفحة UPayments. تُفعَّل الطرق لكل حساب لدى UPayments؛ ولا ترسل TakeTheme أي تصفية للطرق.