وسائل الدفع وحسابك

تستخدم جميع حسابات تيرا باي التكامل نفسه: نقاط النهاية نفسها والكائنات نفسها والـ Webhooks نفسها وcheckout_url نفسه. وعند اعتماد حسابك، تربطه تيرا باي بإعداد معالجة البطاقات المناسب لبلدك وعملاتك. وتعتمد بعض التفاصيل على هذا الإعداد، وتجمعها هذه الصفحة كلها حتى تعمل شيفرتك مع أي حساب.

وسائل الدفع حسب الحساب

الحسابات الإماراتية تقبل card وapple_pay وgoogle_pay. أما الوسائل المحلية مثل كي-نت ومدى فلا تتوفر إلا في الحسابات التي تدعمها. إذا لم تكن متأكدًا مما يدعمه حسابك، راسل support@teyra.co، أو جرّب في وضع الاختبار: الوسيلة التي لا يدعمها حسابك تُرفض فورًا (انظر أدناه).

طلب وسيلة لا يدعمها حسابك

المعامل payment_method اختياري. من دونه تعرض صفحة الدفع كل الوسائل التي يدعمها حسابك للعملة ولجهاز العميل، وهذا ما تحتاجه معظم عمليات التكامل. أما إذا مرّرته ولم يكن حسابك يدعم تلك الوسيلة، فيرد POST /v1/payments بالرمز 422 ولا يُنشئ شيئًا:

{
  "error": {
    "code": "validation_error",
    "message": "This payment method is not available for your account.",
    "details": { "fields": { "payment_method": "unsupported" } }
  }
}

لحل ذلك احذف payment_method، أو اعرض فقط الوسائل التي يدعمها حسابك من الجدول أعلاه. ولا تُعِد إرسال الطلب نفسه، فلن تتغير الإجابة.

ما الذي يعرضه payment_method

بعد نجاح الدفع يبيّن payment_method الوسيلة التي دفع بها العميل. وفي الحسابات الإماراتية تكون قيمته دائمًا card أو apple_pay أو google_pay. ومع Apple Pay وGoogle Pay يحمل الحقل card علامة البطاقة الموجودة في محفظة العميل وآخر أربعة أرقام منها:

{ "payment_method": "apple_pay", "card": { "brand": "visa", "last4": "4242" } }

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

المبالغ ذات المنازل الثلاث تنتهي بصفر (في بعض الحسابات)

في بعض الحسابات، ومنها الحسابات الإماراتية، يجب أن تنتهي المبالغ بالعملات ذات المنازل العشرية الثلاث (KWD وBHD وOMR وJOD) بصفر: القيمة 1250 (1.250 د.ك) مقبولة، أما 1255 (1.255 د.ك) فلا. ولا تتأثر العملات ذات المنزلتين مثل AED وSAR.

في هذه الحسابات يرفض POST /v1/payments وPOST /v1/payment-links (وروابط الدفع المنشأة من لوحة التحكم) هذا المبلغ قبل إنشاء أي شيء:

{
  "error": {
    "code": "validation_error",
    "message": "Amounts in this currency must end in 0 (for example 1.250, not 1.255).",
    "details": { "fields": { "amount": "unsupported" } }
  }
}

أبسط طريقة لتعمل مع أي حساب هي تقريب الأسعار ذات المنازل الثلاث إلى أقرب 10 فلوس (أو بيسات) قبل إرسالها، وأن تنتهي مبالغ الاسترداد الجزئي بهذه العملات بصفر أيضًا:

const THREE_DECIMALS = new Set(['KWD', 'BHD', 'OMR', 'JOD']);

// 1255 KWD -> 1260; 1250 KWD -> 1250; AED amounts are unchanged
function payableAmount(minor, currency) {
  return THREE_DECIMALS.has(currency) ? Math.round(minor / 10) * 10 : minor;
}

راجع المبالغ والعملات لمعرفة الوحدات الصغرى.

صفحة الدفع

المسار واحد في كل الحسابات: تنشئ عملية الدفع، وتوجّه العميل إلى checkout_url، ثم يعود إلى return_url مع payment_id وstatus، وتتحقق من خادمك. راجع صفحة الدفع المستضافة.

ما يراه العميل في الحسابات الإماراتية:

• حقول بطاقة آمنة داخل صفحة الدفع في تيرا باي. يُكتب رقم البطاقة وتاريخ الانتهاء ورمز CVV في حقول يقدّمها معالج البطاقات، فلا تصل أبدًا إلى خوادمك ولا إلى خوادم تيرا باي.
• Apple Pay وGoogle Pay كخيارين في النموذج نفسه عندما يدعمهما جهاز العميل ومتصفحه (Apple Pay في Safari مع بطاقة في Apple Wallet، وGoogle Pay في متصفح فيه بطاقة محفوظة في Google Pay). وتمرير payment_method يقصر الصفحة على تلك الوسيلة.
• 3-D Secure يُفتح في نافذة فوق صفحة الدفع عندما يطلبه بنك العميل. لا يغادر العميل الصفحة إلى البنك، ويُوجَّه إلى return_url فور تأكيد الدفع.
• رفض البطاقة يظهر في الصفحة مع السبب الذي ذكره البنك وزر إعادة المحاولة. تصبح العملية failed (ويصلك payment.failed)، لكنها تظل قابلة للدفع عبر checkout_url نفسه حتى expires_at، فقد يتبعها payment.succeeded.
• الإلغاء يعمل كما في كل الحسابات: تصبح العملية canceled ويعود العميل إلى return_url مع status=failed.

في الحسابات التي تدعم الوسائل المحلية، تنقل كي-نت وبنفت وما شابههما العميل إلى صفحة بنكه ثم تعيده، وقد يتم 3-D Secure للبطاقات أيضًا في صفحة البنك. ولا تحتاج شيفرتك إلى معرفة ذلك، فكلا المسارين ينتهي عند return_url.

قد تكون العملية processing لفترة قصيرة عند عودة العميل. انتظر الـ Webhook payment.succeeded أو payment.failed، أو تحقق مجددًا عبر GET /v1/payments/:id.

الرسوم والمبلغ الصافي

تدفع سعرًا واحدًا في كل الحسابات أيًّا كانت وسيلة الدفع: رسوم تيرا باي، وهي نسبة مئوية من المبلغ زائد مبلغ ثابت لكل عملية دفع. يظهر سعرك في ملف النشاط التجاري والإيداعات في لوحة التحكم. وتكاليف المعالجة مشمولة فيه؛ ولا يُخصم أي شيء آخر.

تُحدَّد commission وnet عند نجاح الدفع، في الـ Webhook payment.succeeded وفي GET /v1/payments/:id:

• commission هي رسوم تيرا باي على هذه العملية: النسبة المئوية من amount مقرّبة إلى أقرب وحدة صغرى، زائد المبلغ الثابت. ولا تتجاوز amount أبدًا.
• net تساوي amount − commission: ما تستلمه عن هذه العملية.

مثلًا، بسعر 2.5% + 0.000 KWD، يكون لعملية دفع بقيمة 12.500 KWD (12500) قيمة commission تساوي 313 وnet تساوي 12187. ورصيدك هو مجموع net ناقص المبالغ المستردة.

الاسترداد

يعمل الاسترداد بالطريقة نفسها في كل الحسابات: POST /v1/payments/:id/refunds، كاملًا أو جزئيًا، بالحالات والأخطاء نفسها والـ Webhooks refund.succeeded وrefund.failed. راجع الاسترداد.

• يُخصم المبلغ المسترد من رصيدك، ولا تُعاد عمولة تيرا باي على عملية الدفع الأصلية.
• تُقبل قيم reason الأربع في كل الحسابات.
• يبدأ الاسترداد بالحالة pending، ويصبح عادةً succeeded خلال ثوانٍ في الحسابات الإماراتية. ويستغرق ظهوره في كشف حساب العميل بضعة أيام عمل للبطاقات والمحافظ، حسب بنكه.

الاعتراضات

الاعتراض (أو استرجاع المبلغ، Chargeback) هو أن يطلب حامل البطاقة من بنكه عكس عملية دفع بالبطاقة أو Apple Pay أو Google Pay. وفي الحسابات الإماراتية يتلقى كل مالك رسالة عند الاعتراض على دفعة، وتعرض الاستردادات ← الاعتراضات في لوحة التحكم حالة كل اعتراض وآخر موعد للرد. وفي الحسابات الأخرى يتواصل معك فريق الدعم. راجع الاعتراضات لمعرفة الحالات وما تفعله.

الاختبار

يتصرف وضع الاختبار مثل الوضع الحي في كل ما سبق، فتستطيع فحص تكاملك قبل الإطلاق:

تعتمد أرقام بطاقات الاختبار على حسابك: راجع الاختبار.