وضع الاختبار والوضع الحي

لكل حساب في تيرا باي وضعان منفصلان، وتحدد الوضع بمفتاح الـ API الذي تستخدمه.

لا تختلط بيانات الوضعين أبدًا. عملية الدفع التي أُنشئت بمفتاح اختبار لا يمكن قراءتها أو استردادها أو عرضها إلا بمفتاح اختبار.

الانتقال إلى الوضع الحي

يتطلب الوضع الحي حسابًا معتمدًا. قبل الاعتماد، تعيد الطلبات الحية رمز الحالة 403 مع الخطأ التالي:

{
  "error": {
    "code": "merchant_not_active",
    "message": "Live payments are available once your account is activated."
  }
}

الوضع الحي يتطلب HTTPS

في الوضع الحي، يجب أن يبدأ كل رابط تقدّمه لتيرا باي بـ https://:

• return_url عند إنشاء عملية دفع؛
• url لنقطة نهاية الـ Webhook.

يُرفض الرابط الذي يبدأ بـ http:// بالخطأ 422 validation_error:

{
  "error": {
    "code": "validation_error",
    "message": "The return_url must use https:// in live mode.",
    "details": { "fields": { "return_url": "must use https:// in live mode" } }
  }
}

يقبل وضع الاختبار http:// لتستخدم localhost أو نفقًا أثناء التطوير. أما روابط الدفع فلا تحمل رابطًا خاصًا بالتاجر، لذا لا يشملها هذا الشرط.

قائمة التحقق قبل الإطلاق

راجع هذه القائمة قبل أن تنقل إعدادات الإنتاج إلى sk_live_….

المدفوعات

• يتأكد خادمك من كل عملية دفع عبر GET /v1/payments/:id أو Webhook تم التحقق منه، ولا يعتمد على إعادة التوجيه وحدها (معالجة رابط العودة).
• تتحقق صفحة العودة من تطابق amount وcurrency وreference (أو الـ id المحفوظ) مع الطلب قبل تعليمه مدفوعًا.
• تعليم الطلب مدفوعًا آمن من التكرار: قد تصل صفحة العودة والـ Webhook كلاهما وبأي ترتيب.
• لا يُغلق payment.failed أو payment.canceled الطلب نهائيًا: يظل بإمكان العميل الدفع عبر checkout_url نفسه حتى expires_at (المدفوعات).
• تُرسل المبالغ أعدادًا صحيحة بالوحدات الصغرى وفق المنازل العشرية الصحيحة، خاصة مع KWD وBHD وOMR وJOD (المبالغ والعملات).
• يستخدم return_url البروتوكول https://.

الـ Webhooks

• سُجّلت نقطة Webhook حية برابط https:// يمكن الوصول إليه من الإنترنت، وحُفظ سر التوقيع الحي على خادمك.
• يتم التحقق من التواقيع على الجسم الخام مع مهلة 5 دقائق، وتُتجاهل الأحداث المكررة حسب Teyra-Event-Id (التحقق من التواقيع).
• تردّ نقطة النهاية برمز 2xx خلال 10 ثوانٍ وتنفّذ الأعمال البطيئة في الخلفية.
• هناك من يتابع عمليات التسليم الفاشلة في المطورون ← Webhooks.

طلبات الـ API

• تحمل طلبات POST الترويسة Idempotency-Key، وتعيد المحاولات استخدامها (منع التكرار).
• تُعالج الأخطاء وتُسجّل حسب error.code (الأخطاء).
• يُعاد إرسال الاستجابات 429 rate_limited و5xx بتأخير متصاعد مع احترام Retry-After (المصادقة).
• تُتجاهل الحقول وأنواع الأحداث ورموز الأخطاء غير المعروفة بدل اعتبارها أعطالًا.

المفاتيح والأمان

• المفتاح السري الحي محفوظ على خادمك فقط، في مخزن أسرار أو متغير بيئة، وليس في متصفح أو تطبيق أو مستودع (المصادقة).
• لكل نظام (الموقع، نظام ERP، الإضافة) مفتاحه الخاص، لتستطيع إلغاء أحدها دون التأثير على الباقي.
• ساعة خادمك متزامنة عبر NTP.
• لأعضاء فريقك في حساب تيرا باي الأدوار التي يحتاجونها فقط، مع تفعيل المصادقة الثنائية.

الفحص الأخير

• تنجح كل سيناريوهات الاختبار في وضع الاختبار.
• بعد الانتقال، نفّذ دفعة حية صغيرة ببطاقة حقيقية، وتأكد منها من البداية إلى النهاية (صفحة العودة والـ Webhook ولوحة التحكم)، ثم استردها.