صفحة الدفع المستضافة

في صفحة الدفع المستضافة يُدخل العميل بيانات الدفع في صفحة تستضيفها تيرا باي، لا في موقعك. لا ترى بيانات البطاقات ولا تخزّنها، وتعمل كل وسائل الدفع التي يدعمها حسابك (البطاقات وApple Pay وGoogle Pay، إضافة إلى كي-نت ومدى وبنفت وSTC Pay في الحسابات التي تدعمها) بالتكامل نفسه. راجع وسائل الدفع وحسابك.

مسار إعادة التوجيه

 Your server            Customer's browser              Teyra Pay
     │  POST /v1/payments                                   │
     │─────────────────────────────────────────────────────▶│
     │◀──────────────────── Payment + checkout_url ─────────│
     │  302 → checkout_url │                                │
     │────────────────────▶│  GET checkout_url              │
     │                     │───────────────────────────────▶│  customer pays
     │                     │◀── 302 → return_url?payment_id=…&status=…
     │  GET return_url     │                                │
     │◀────────────────────│                                │
     │  GET /v1/payments/:id  (confirm)                     │
     │─────────────────────────────────────────────────────▶│
     │◀─────────────── POST webhook payment.succeeded ──────│

https://shop.example.com/thanks?payment_id=pay_01JBX4T9W2&status=succeeded

مثال على الخادم

// Express: start checkout for an order
app.post('/orders/:id/pay', async (req, res) => {
  const order = await db.orders.find(req.params.id);

  const response = await fetch('https://api.teyra.co/v1/payments', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TEYRA_SECRET_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `order-${order.id}-attempt-${order.attempt}`,
    },
    body: JSON.stringify({
      amount: order.totalMinor, // e.g. 12500 for 12.500 KWD
      currency: 'KWD',
      reference: String(order.id),
      description: `Order #${order.id}`,
      customer: { name: order.name, email: order.email, phone: order.phone },
      language: req.acceptsLanguages('ar', 'en') || 'en',
      return_url: `https://shop.example.com/orders/${order.id}/return`,
    }),
  });
  const payment = await response.json();
  if (!response.ok) return res.status(502).send(payment.error.message);

  await db.orders.update(order.id, { paymentId: payment.id });
  res.redirect(303, payment.checkout_url);
});

ما يراه العميل

صفحة الدفع صفحة تابعة لتيرا باي. تعرض اسم نشاطك التجاري، وdescription وreference الخاصين بعملية الدفع، والمبلغ، ووسائل الدفع المتاحة للعملة والجهاز. وتظهر شارة TEST على المدفوعات التجريبية. ويستطيع العميل تبديل لغة الصفحة بين العربية والإنجليزية.

• البطاقات (Visa وMastercard ومدى وAmerican Express): يُدخل العميل بيانات البطاقة في حقول آمنة على صفحة الدفع، فتذهب مباشرة إلى معالج البطاقات ولا تصل إليك ولا إلى تيرا باي. وإذا طلب البنك التحقق عبر 3-D Secure، يُكمله العميل إما في نافذة فوق صفحة الدفع أو في صفحة البنك، حسب حسابك، ثم يعود إلى return_url تلقائيًا.
• Apple Pay وGoogle Pay وSTC Pay: يتم الدفع بها في صفحة الدفع نفسها. ولا يظهر Apple Pay وGoogle Pay إلا على الأجهزة والمتصفحات التي تدعمهما.
• كي-نت وبنفت وغيرهما من وسائل الدفع البنكية (في الحسابات التي تدعمها): يُنقل العميل إلى صفحة الدفع الخاصة بالبنك ثم يعود تلقائيًا.
• البطاقات المرفوضة: تعرض الصفحة السبب مع زر إعادة المحاولة. تصبح العملية failed لكن يظل بالإمكان دفعها عبر checkout_url نفسه.
• الإلغاء: في الصفحة زر إلغاء والعودة إلى التاجر. تصبح العملية canceled (ويصلك payment.canceled) ويُعاد العميل إلى return_url مع status=failed. ويظل بالإمكان دفعها عبر checkout_url نفسه حتى انتهاء صلاحيتها.

إذا مرّرت payment_method عند إنشاء عملية الدفع، فلن تُعرض إلا تلك الوسيلة. ويجب أن تكون وسيلة يدعمها حسابك، وإلا لن تُنشأ عملية الدفع (422 validation_error).

انتهاء المهلة وإعادة المحاولة

• تنتهي صلاحية عملية الدفع بعد expires_in_minutes من إنشائها (الافتراضي 60 دقيقة، ويتراوح بين 5 و43200). فتح checkout_url بعد ذلك يعرض رسالة "انتهت صلاحية هذه الدفعة" (HTTP 410)، وتصبح الحالة expired.
• فتح checkout_url لعملية مدفوعة مسبقًا يعرض رسالة "تم الدفع مسبقاً" بدلًا من الخصم مرتين.
• يمكن دفع العملية failed أو canceled مجددًا عبر checkout_url نفسه حتى انتهاء صلاحيتها. للسماح للعميل بالمحاولة، أعِده إليه، فيبقى لكل طلب عملية دفع واحدة.
• إذا أنشأت عملية دفع جديدة للطلب بدلًا من ذلك (بمفتاح Idempotency-Key جديد)، فقد يُكمل العميل العملية القديمة في تبويب آخر. اعتبر أي payment.succeeded لهذا الطلب دفعًا مكتملًا، واسترد الدفعة المكررة.
• بعد expires_at أنشئ عملية دفع جديدة.
• إذا تعذّر تحميل نموذج البطاقة أو بدء الدفع، تعرض الصفحة الخطأ مع زر حاول مرة أخرى.

لغة صفحة الدفع

مرّر "language": "ar" لعرض صفحة الدفع بالعربية (من اليمين إلى اليسار) أو "language": "en" للإنجليزية. ويظل بإمكان العميل تبديل اللغة من الصفحة.