# WHMCS

> بوابة دفع لـ WHMCS: يدفع العملاء الفواتير بالبيتكوين أو USDC/USDT مباشرةً إلى محفظتك، ويسجّل ويب هوك موقّع الدفعة.

تضيف وحدة Perly Pay العملات المشفرة إلى فواتير WHMCS. يضغط العميل **ادفع بالعملات المشفرة**؛ فيصبح رصيد الفاتورة المتبقي فاتورة في Perly Pay تُدفع فوق صفحة WHMCS أو في صفحة مستقلة؛ ويسجّل ويب هوك موقّع الدفعة في WHMCS. WHMCS 8، وPHP 8.1+ مع curl. لا شيء لتثبيته عبر Composer: [PHP SDK](https://pay.perly.io/docs/sdks.md) موجودة بالداخل.

> **ملاحظة:** يُصدر Perly Pay الفواتير بالدولار الأمريكي أو اليورو. للعملاء بعملة أخرى، اختر في البوابة **Convert To For Processing** بالدولار أو اليورو؛ وستُسجَّل الدفعة مع ذلك بعملة الفاتورة نفسها. بدون ذلك، سيرى هؤلاء العملاء تلميحًا لاختيار طريقة دفع أخرى.

## التثبيت

1. **احصل على ملف zip** — الوحدة في طريقها إلى WHMCS Marketplace. وحتى تصل، [راسلنا](https://pay.perly.io/ar/contact) للحصول على `perly-pay-whmcs.zip`.
2. **ارفعها** — فك ضغطها فوق مجلد WHMCS. ستُضاف `modules/gateways/perlypay.php` و`modules/gateways/callback/perlypay.php` و`modules/gateways/perlypay/`.
3. **فعّلها** — Configuration → Apps & Integrations → Payment Gateways (أو Setup → Payment Gateways)، وفعّل **Perly Pay**.

## الإعداد

| الحقل | ما تكتبه |
| --- | --- |
| المفتاح السري | Dashboard → Developers → API keys. `sk_test_…` لـ[وضع الاختبار](https://pay.perly.io/docs/test-mode.md)، و`sk_live_…` للأموال الحقيقية. |
| سر توقيع الويب هوك | `whsec_…`، من الويب هوك الذي ستضيفه لهذا الـ WHMCS (أدناه). |
| صفحة الدفع | **نافذة علوية** تفتح الدفع فوق الفاتورة (pay.js). **انتقال** يوجّه العميل إلى صفحتها. على الهواتف تُفتح الصفحة نفسها دائمًا. |
| العملات | الدولار الأمريكي واليورو، أو إحداهما فقط. |

1. **الصق المفتاح** — احفظ واضغط **اختبر الاتصال** في حقل المفتاح: سترى هل يعمل المفتاح، ووضعه، وهل يوجد ويب هوك لهذا الـ WHMCS في Perly Pay.
2. **أضف ويب هوك** — في Dashboard → Developers → Webhooks أضف العنوان من الإعدادات، `https://your-whmcs/modules/gateways/callback/perlypay.php`، مع أحداث الفواتير والاستردادات. الصق سرّه واحفظ.
3. **اسمح بالنافذة العلوية** — في Dashboard → Settings أضف عنوان WHMCS إلى **Sites that may embed the checkout**. بدون ذلك ستعرض النافذة العلوية فتح الدفع في علامة تبويب جديدة.

## الاختبار

بمفتاح `sk_test_…` افتح فاتورة غير مدفوعة في منطقة العميل واضغط **ادفع بالعملات المشفرة**. ادفع بعملات تجريبية أو عبر API — معرّف الفاتورة في صفحة الدفع:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

خلال ثوانٍ تصبح الفاتورة في WHMCS **Paid**. يُظهر Billing → Gateway Log الشبكة والمبلغ ورابط المعاملة.

## كيف تتبع الفواتير المدفوعات

| في Perly Pay | في WHMCS |
| --- | --- |
| مدفوعة، وفُحص المُرسل (`invoice.fulfilled`) | دفعة بالمبلغ المفوتر للعميل، بعملة الفاتورة، مع معرّف دفعة Perly Pay (`pay_…`). يعلّم WHMCS الفاتورة Paid ويكمل الباقي كالمعتاد. |
| مرصودة، مدفوعة جزئيًا، مدفوعة وما زالت قيد الفحص | سطر في Gateway Log. بلا دفعة. |
| محتجزة [للمراجعة](https://pay.perly.io/docs/screening.md) | سطر في Gateway Log مع السبب. قرّر في Perly Pay. |
| منتهية أو ملغاة | سطر في Gateway Log. الضغط على الزر مجددًا ينشئ فاتورة جديدة. |
| استرداد مفتوح، جاهز، مُرسل، مؤكد | سطر في Gateway Log: ماذا ترسل وإلى أين. |

الضغط على الزر مرة أخرى يأخذ الفاتورة المفتوحة ما دام الرصيد المتبقي نفسه. تُسجَّل كل دفعة مرة واحدة مهما تكرر وصول الويب هوك، ولفواتير هذا الـ WHMCS فقط.

## الاستردادات

استرد المعاملة في WHMCS كالمعتاد: تفتح الوحدة [استردادًا](https://pay.perly.io/docs/refunds.md) في Perly Pay بالعملة التي دُفع بها (وبالنسبة نفسها للاسترداد الجزئي). يطلب Perly Pay من العميل عنوانًا بالبريد ويفحصه؛ ويقول Gateway Log ماذا ترسل وإلى أين. ترسل من محفظتك وتلصق معرّف المعاملة في Perly Pay — Perly Pay لا يحتفظ بالأموال أبدًا.

## الإطلاق

- فعّل الوضع الحقيقي في Perly Pay واربط المفاتيح العامة للمحفظة.
- الصق مفتاح `sk_live_…`. المفاتيح والويب هوك الحقيقية منفصلة عن الاختبارية: أضف عنوان الرد مرة أخرى في الوضع الحقيقي والصق سرّه.
- أضف عنوان https لـ WHMCS إلى **Sites that may embed the checkout** في الوضع الحقيقي.
- ادفع فاتورة حقيقية صغيرة واستردها.