# WHMCS

> WHMCS için ödeme altyapısı: müşteriler faturaları bitcoin ya da USDC/USDT ile doğrudan senin cüzdanına öder, ödemeyi imzalı bir webhook kaydeder.

Perly Pay modülü WHMCS faturalarına kripto ekler. Müşteri **Kriptoyla öde**'ye basar; faturanın kalanı bir Perly Pay faturası olur ve WHMCS sayfasının üstünde ya da ayrı bir sayfada ödenir; imzalı bir webhook ödemeyi WHMCS'e kaydeder. WHMCS 8, curl'lü PHP 8.1+. Composer ile kurulacak bir şey yok: [PHP SDK](https://pay.perly.io/docs/sdks.md) zaten içinde.

> **Not:** Perly Pay faturaları USD ya da EUR olarak keser. Başka para birimindeki müşteriler için altyapıda **Convert To For Processing** olarak USD ya da EUR seç; ödeme yine faturanın kendi para biriminde kaydedilir. Bu olmadan bu müşteriler başka bir ödeme yöntemi seçmelerini söyleyen bir ipucu görür.

## Kurulum

1. **Zip'i al** — Modül WHMCS Marketplace'e yolda. Orada olana kadar `perly-pay-whmcs.zip` için [bize yaz](https://pay.perly.io/tr/contact).
2. **Yükle** — WHMCS klasörünün üzerine aç. `modules/gateways/perlypay.php`, `modules/gateways/callback/perlypay.php` ve `modules/gateways/perlypay/` eklenir.
3. **Aç** — Configuration → Apps & Integrations → Payment Gateways (ya da Setup → Payment Gateways), **Perly Pay**'i etkinleştir.

## Ayarlar

| Alan | Ne yazılır |
| --- | --- |
| Gizli anahtar | Dashboard → Developers → API keys. [Test modu](https://pay.perly.io/docs/test-mode.md) için `sk_test_…`, gerçek para için `sk_live_…`. |
| Webhook imza secret'ı | `whsec_…`, bu WHMCS için ekleyeceğin webhook'tan (aşağıda). |
| Ödeme sayfası | **Katman** ödemeyi faturanın üstünde açar (pay.js). **Yönlendirme** müşteriyi ödeme sayfasına götürür. Telefonlarda her zaman sayfanın kendisi açılır. |
| Para birimleri | USD ve EUR ya da yalnızca biri. |

1. **Anahtarı yapıştır** — Kaydet ve anahtar alanındaki **Bağlantıyı test et**'e bas: anahtarın çalışıp çalışmadığını, modunu ve bu WHMCS'in webhook'unun Perly Pay'de olup olmadığını görürsün.
2. **Webhook ekle** — Dashboard → Developers → Webhooks'ta ayarlardaki adresi, `https://your-whmcs/modules/gateways/callback/perlypay.php`, fatura ve iade olaylarıyla ekle. Secret'ını yapıştır ve kaydet.
3. **Katmana izin ver** — Dashboard → Settings'te WHMCS adresini **Sites that may embed the checkout** listesine ekle. Bu olmadan katman ödemeyi yeni sekmede açmayı önerir.

## Test

`sk_test_…` anahtarıyla müşteri alanında ödenmemiş bir faturayı aç ve **Kriptoyla öde**'ye bas. Test coinleriyle ya da API üzerinden öde — fatura kimliği ödeme sayfasında yazar:

```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 '{}'
```

Birkaç saniye içinde WHMCS'teki fatura **Paid** olur. Billing → Gateway Log ağı, tutarı ve işlem bağlantısını gösterir.

## Faturalar ödemeleri nasıl izler

| Perly Pay'de | WHMCS'te |
| --- | --- |
| Ödendi, gönderen kontrol edildi (`invoice.fulfilled`) | Müşteriye kesilen tutarda, faturanın para biriminde, Perly Pay ödeme kimliğiyle (`pay_…`) bir ödeme. WHMCS faturayı Paid olarak işaretler ve gerisini her zamanki gibi yapar. |
| Görüldü, kısmen ödendi, ödendi ve hâlâ kontrol ediliyor | Gateway Log'da bir satır. Ödeme yok. |
| [Kontrol](https://pay.perly.io/docs/screening.md) için bekletildi | Gateway Log'da nedeniyle bir satır. Perly Pay'de karar ver. |
| Süresi doldu ya da iptal edildi | Gateway Log'da bir satır. Butona yeniden basmak yeni bir fatura oluşturur. |
| İade açıldı, hazır, gönderildi, onaylandı | Gateway Log'da bir satır: neyin nereye gönderileceği. |

Butona tekrar basmak, kalan aynı olduğu sürece açık faturayı kullanır. Her ödeme, webhook kaç kez gelirse gelsin bir kez kaydedilir, ve yalnızca bu WHMCS'in faturaları için.

## İadeler

İşlemi WHMCS'te her zamanki gibi iade et: modül Perly Pay'de ödenen coinle bir [iade](https://pay.perly.io/docs/refunds.md) açar (kısmi iadede aynı oranda). Perly Pay müşteriden e-postayla adres ister ve kontrol eder; Gateway Log neyin nereye gönderileceğini söyler. Sen kendi cüzdanından gönderirsin ve işlem kimliğini Perly Pay'e yapıştırırsın — Perly Pay parayı asla tutmaz.

## Canlıya geçiş

- Perly Pay'de canlı modu aç ve cüzdanın açık anahtarlarını bağla.
- `sk_live_…` anahtarını yapıştır. Canlı anahtarlar ve webhook'lar testtekilerden ayrıdır: geri çağırma adresini canlı modda bir kez daha ekle ve secret'ını yapıştır.
- Canlı modda WHMCS'in https adresini **Sites that may embed the checkout** listesine ekle.
- Küçük, gerçek bir fatura öde ve iade et.