الانتقال إلى المحتوى الرئيسي

تكامل Stripe

يشرح هذا الدليل تكامل Stripe في MyCloudBook: كيف يدفع العملاء الفواتير وأوامر البيع بالبطاقة، وكيف تربط حساب Stripe، وكيف يسجل MyCloudBook المدفوعات والرسوم.

نظرة عامة

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

يفتح العميل الرابط المشترك لفاتورة أو أمر بيع، مثلًا من رسالة البريد الإلكتروني الخاصة بالمستند. ثم ينقر العميل على Pay with Card. يستلم Stripe الدفعة في صفحة الدفع الخاصة به. في الفاتورة، المبلغ هو المبلغ الذي لا يزال مستحقًا. وفي أمر البيع، المبلغ هو الإجمالي، ما دام الأمر مفتوحًا وغير منتهي الصلاحية. بعد الدفع، يسجل MyCloudBook الدفعة تلقائيًا:

الحدثما يسجله MyCloudBook
دفع فاتورةسند قبض للعميل الذي يدفع الفاتورة. يذهب المبلغ إلى حساب الإيداع الخاص بعملة الدفعة.
دفع أمر بيعإيصال مبيعات للأمر. ويُنفِّذ الإيصال الأمر.
اقتطاع Stripe لرسومهمصروف لمورّد Stripe على حساب مصروف الرسوم، مدفوع من حساب الإيداع. ويُربط المصروف بمستند الدفعة بوصفه مستندًا مرتبطًا.
إنشاء المستنداتيتلقى العميل رسالة بريد إلكتروني فيها رابط المستند الجديد. يتطلب ذلك إعدادات SMTP للشركة وعنوان بريد إلكتروني للعميل.

يتكون الإعداد من جزأين. يستخدم الربط المفتاح السري لحساب Stripe. وتحدد الإعدادات المحاسبية لـ MyCloudBook طريقة تسجيل المدفوعات والرسوم. ولا يظهر زر الدفع في المستندات المشتركة إلا ما دامت الإعدادات نشطة.

كيفية فتح النافذة

  1. في الشريط العلوي، انقر على Settings. يقع الزر بين اسم الشركة واسم المستخدم.
  2. في القائمة، انقر على Stripe Integration. تُفتح نافذة Stripe Integration Settings.

تظهر قائمة Settings للمستخدمين الذين لديهم الدور Admin. ولا يرى المستخدمون الآخرون هذه القائمة.

قائمة Settings في الشريط العلوي لـ MyCloudBook مع تمييز العنصر Stripe Integration.
الشكل 1. قائمة Settings.
  1. 1Settings. يفتح قائمة إعدادات الشركة.
  2. 2Stripe Integration.

نافذة Stripe Integration Settings

تحتوي النافذة على ثلاث مجموعات: Stripe Connection وAccounting وRedirect URLs. يعرض المثال شركة لم تُربط بعد، مع قيم توضيحية في الحقول المحاسبية.

نافذة Stripe Integration Settings مع الحالة Not connected، وطريقة الدفع Credit Card، وحساب الإيداع 101 Checking Account، وحساب مصروف الرسوم 506 Bank and Credit Card Fees، وعنواني إعادة توجيه.
الشكل 2. نافذة Stripe Integration Settings.
  1. 1Status. Not connected أو Connected. ترى الشركة المربوطة أيضًا المفتاح السري بأحرف مخفية، وخطاف الويب.
  2. 2Connect.... يفتح نافذة الربط. ترى الشركة المربوطة Reconnect.... يحتوي السهم على Remove Connection....
  3. 3Payment Method. طريقة الدفع للمدفوعات المسجلة.
  4. 4Deposit Accounts. الحسابات التي تستقبل المدفوعات، بواقع حساب واحد لكل عملة.
  5. 5Stripe Supplier. المورّد الذي يمثل Stripe. فارغ في المثال.
  6. 6Fee Expense Account. حساب المصروفات الخاص برسوم Stripe.
  7. 7Success URL. الصفحة التي يراها العميل بعد الدفع.
  8. 8Cancel URL. الصفحة التي يراها العميل عند إلغاء الدفع.
  9. 9زر المساعدة. يفتح مساعدة النافذة.
  10. 10Active. يُفعّل المدفوعات. يتطلب الربط والحقول المحاسبية الأربعة.
  11. 11Save.
  12. 12Cancel.

ربط حساب Stripe

  1. في لوحة تحكم Stripe، افتح Developers، ثم API keys، وأنشئ مفتاحًا سريًا. انسخه فورًا، لأن Stripe لا يعرض المفتاح السري للوضع الحقيقي إلا مرة واحدة.
  2. في نافذة Stripe Integration Settings في MyCloudBook، انقر على Connect....
  3. الصق المفتاح في Secret Key. يبدأ المفتاح السري بـ sk_live_ أو sk_test_. لا تستخدم مفتاحًا قابلًا للنشر (pk_) أو مفتاحًا مقيّدًا (rk_).
  4. اترك Create the webhook automatically (recommended) محددًا، وانقر على Connect.

يتحقق MyCloudBook من المفتاح لدى Stripe، وينشئ خطاف الويب (webhook) في حساب Stripe، ويحفظ الربط. خطاف الويب هو العنوان الذي يُبلغ Stripe عبره MyCloudBook بكل دفعة مكتملة. بعد ذلك تعرض النافذة الحالة Connected، والمفتاح السري مع إخفاء معظم أحرفه، ووضع خطاف الويب Automatic. لا يظهر المفتاح الكامل مرة أخرى أبدًا. المفتاح الذي يبدأ بـ sk_test_ يربط وضع الاختبار في Stripe، وفيه تستخدم المدفوعات بطاقات الاختبار من Stripe ولا تنتقل أي أموال.

نافذة Connect to Stripe مع حقل Secret Key فارغ، ومربع الاختيار Create the webhook automatically محدد.
الشكل 3. نافذة Connect to Stripe.
  1. 1Secret Key. مطلوب.
  2. 2Create the webhook automatically (recommended).
  3. 3زر المساعدة. يفتح خطوات الربط.
  4. 4Connect. يتحقق من المفتاح ويحفظ الربط.
  5. 5Cancel.

خطاف ويب يدوي

ألغِ تحديد Create the webhook automatically (recommended) لتدير خطاف الويب بنفسك، مثلًا باستخدام أداة سطر الأوامر من Stripe أثناء التطوير. عندئذٍ تعرض النافذة مجموعة Manual Webhook.

  1. انسخ Webhook Listener URL بزر النسخ.
  2. في لوحة تحكم Stripe، أنشئ نقطة نهاية لخطاف الويب بهذا العنوان وبالأحداث checkout.session.completed وpayment_intent.succeeded وpayment_intent.payment_failed.
  3. الصق سر التوقيع الخاص بنقطة النهاية (يبدأ بـ whsec_) في Webhook Secret، وانقر على Connect.

اترك Webhook Secret فارغًا للربط دون خطاف ويب. عندئذٍ يُكمل MyCloudBook المدفوعات عبر العملية التي تعمل في الخلفية. تحتوي قائمة زر النسخ على Generate New Listener Token، الذي ينشئ عنوان مستمع جديدًا. استخدم العنوان الجديد لنقطة النهاية في Stripe، ثم اربط مرة أخرى بسر التوقيع الخاص بها.

نافذة Connect to Stripe مع إلغاء تحديد خيار خطاف الويب التلقائي، ومجموعة Manual Webhook التي تحتوي على عنوان المستمع وحقل Webhook Secret.
الشكل 4. نافذة الربط مع خطاف ويب يدوي.
  1. 1Create the webhook automatically (recommended)، غير محدد.
  2. 2Manual Webhook. خطوات نقطة النهاية وأحداثها.
  3. 3Webhook Listener URL. عنوان نقطة النهاية في Stripe. هذا الحقل للقراءة فقط.
  4. 4زر النسخ. تحتوي قائمته على Generate New Listener Token.
  5. 5Webhook Secret. سر التوقيع الخاص بنقطة النهاية، أو فارغ.

بعد خمس محاولات ربط فاشلة خلال عشر دقائق، يطلب MyCloudBook من المستخدم الانتظار. وبعد عشرين محاولة ربط فاشلة خلال يوم واحد، تُحظر المحاولات الجديدة لمدة 24 ساعة.

الإعدادات المحاسبية والتفعيل

تحدد الحقول المحاسبية لـ MyCloudBook طريقة تسجيل كل دفعة ورسومها. أنشئ أولًا مورّدًا لـ Stripe (راجع الموردون)، مثلًا باسم Stripe.

الحقلمطلوبالغرض والقواعد
Payment Methodعند التفعيلطريقة الدفع لسندات القبض والإيصالات التي يسجلها MyCloudBook. راجع طرق الدفع.
Deposit Accountsعند التفعيلحسابات أصول تستقبل المدفوعات، بواقع حساب واحد لكل عملة. تذهب الدفعة بعملة معيّنة إلى حساب تلك العملة.
Stripe Supplierعند التفعيلمورّد مصروفات الرسوم. لا يظهر في القائمة إلا المورّدون النشطون.
Fee Expense Accountعند التفعيلحساب من نوع المصروفات لرسوم Stripe، مثل 506 - Bank and Credit Card Fees.
Success URLاختياريالصفحة التي تظهر بعد نجاح الدفع. إذا تُرك الحقل فارغًا، تظهر صفحة حالة الدفع في MyCloudBook. يجب ألا يحتوي العنوان على الحرفين ? و&.
Cancel URLاختياريالصفحة التي تظهر بعد إلغاء الدفع. إذا تُرك الحقل فارغًا، تظهر صفحة الإلغاء في MyCloudBook.
Activeاختيارييُفعّل المدفوعات. تحتاج الإعدادات النشطة إلى الربط وإلى الحقول المحاسبية الأربعة. ويمكن حفظ الإعدادات غير النشطة مع ترك بعض الحقول فارغة، وحتى قبل الربط.

انقر على Save لحفظ الإعدادات المحاسبية وحالة Active. أما الربط نفسه فتحفظه نافذة الربط.

نافذة Stripe Integration Help مع الجزأين Connection وAccounting Settings and Activation.
الشكل 5. مساعدة النافذة.
  1. 1الربط وإزالته.
  2. 2الإعدادات المحاسبية والتفعيل.

إزالة الربط

يحتوي سهم Connect... على Remove Connection.... يكون هذا الأمر مفعّلًا للشركة المربوطة.

  1. انقر على سهم زر الربط، ثم على Remove Connection....
  2. اقرأ السؤال وانقر على Yes.

يزيل MyCloudBook المفتاح السري وخطاف الويب، ويحذف نقطة نهاية خطاف الويب من حساب Stripe إذا كان MyCloudBook هو الذي أنشأها. تصبح الإعدادات غير نشطة، فيختفي زر الدفع من المستندات المشتركة. وتبقى الإعدادات المحاسبية والمدفوعات المسجلة والمستندات كما هي.

قائمة زر Connect مع العنصر Remove Connection، وهو معطّل لشركة غير مربوطة.
الشكل 6. قائمة زر الربط.
  1. 1Remove Connection.... معطّل ما دامت الشركة غير مربوطة.

الرسائل ومعانيها

الرسالةالسببالإجراء
Please fill in all required fields.حقل مطلوب فارغ.املأ الحقل المميَّز باللون الأحمر.
The configuration cannot be active while the following settings are missing: X.مربع Active محدد، ولكن الربط أو أحد الحقول المحاسبية ناقص.اربط الحساب، أو املأ الحقول المذكورة، أو ألغِ تحديد Active.
Deposit accounts must be under different currencies. A Deposit accounts with the Currency 'X' is already added.حسابا إيداع لهما نفس العملة.احتفظ بحساب واحد لكل عملة.
SuccessUrl is invalid. It must not contain '?' or '&' characters.يحتوي Success URL على الحرف ? أو &.استخدم عنوانًا لا يحتوي على هذين الحرفين.
Too many failed connection attempts. Please wait N minute(s) and try again.فشلت خمس محاولات ربط خلال عشر دقائق.تحقّق من المفتاح، وانتظر، ثم حاول مرة أخرى.
Too many failed connection attempts. New attempts are blocked for 24 hours. Please contact customer support.فشلت عشرون محاولة ربط خلال يوم واحد.تواصل مع فريق الدعم.
A manual webhook needs the webhook secret and the listener token together. Leave both empty to connect without a webhook.يحتوي خطاف الويب اليدوي على قيمة واحدة فقط من قيمتيه.الصق سر التوقيع، أو اترك Webhook Secret فارغًا.
رسالة من Stripe بشأن المفتاحرفض Stripe المفتاح السري.انسخ المفتاح السري مرة أخرى من لوحة تحكم Stripe.
The Stripe connection was saved successfully.تم حفظ الربط.املأ الإعدادات المحاسبية، ثم فعّل الإعدادات.
The Stripe connection was removed.تمت إزالة الربط.لا يلزم اتخاذ أي إجراء.
Stripe settings have been saved successfully.تم حفظ الإعدادات المحاسبية.لا يلزم اتخاذ أي إجراء.

أسئلة وأجوبة

كيف يمكن لعملائي دفع فاتورة عبر الإنترنت؟

اربط الشركة بـ Stripe من Settings ثم Stripe Integration، واملأ الحقول المحاسبية، وحدّد Active، ثم احفظ. بعد ذلك يعرض الرابط المشترك لفاتورة عليها مبلغ مستحق زر Pay with Card.

هل يسجل MyCloudBook الدفعة تلقائيًا؟

نعم. تحصل الفاتورة المدفوعة على سند قبض، ويحصل أمر البيع المدفوع على إيصال مبيعات. وتُسجَّل رسوم Stripe بوصفها مصروفًا لمورّد Stripe.

لماذا أحتاج إلى حساب إيداع لكل عملة؟

تذهب الدفعة إلى حساب الإيداع الخاص بعملتها. كل عملة يدفع بها العملاء تحتاج إلى حساب إيداع خاص بها.

هل يمكنني اختبار التكامل دون أموال حقيقية؟

نعم. اربط باستخدام مفتاح اختبار من Stripe يبدأ بـ sk_test_. عندئذٍ تستخدم المدفوعات بطاقات الاختبار من Stripe.

هل يظهر مفتاحي السري في MyCloudBook؟

لا. بعد الربط، تعرض النافذة المفتاح مع إخفاء معظم أحرفه.