# Square Modülü

https://docs.wisecp.com/tr/square-modulu

Square ile kart ödemelerini alın ve sonraki ödemeler için müşterinin kartını saklamasını sağlayın.

## Ekrana Erişim

**Ayarlar → Finansal → Ödeme Ağ Geçitleri** yolunu izleyin, **Tüm Modüller** sekmesini açın ve **Square** kartına tıklayın: `{admin}/modules/payment?module=Square`

Ağ geçidini müşterinin gördüğü yöntem listesine eklemeyi [Ödeme Modülleri](https://docs.wisecp.com/tr/odeme-modulleri) makalesinde bulursunuz.

## Ekranda Neler Var

Tek bir ayar formu: üç Square kimlik bilgisi, bildirim çifti, iki işaret kutusu ve her modülde bulunan ortak ağ geçidi ayarları.

Müşteri Square'in kendi kart alanlarıyla ödeme sayfasında karşılaşır, siteden ayrılmaz. Kart numarası doğrudan Square'e gider, sistem yalnız bir belirteç saklar.

Modül kart saklar, yenilemede saklı kartı çeker, abonelik açar ve fatura ekranından ödemeyi iade eder. Kendi formunuza yazılan kart numarasını kabul etmez, taksit sunmaz.

## Ön Koşullar

- Bir Square hesabı ve Square geliştirici panelinde tanımlı bir uygulama.
- Test ve canlı kimlik bilgileri ayrı takımlardır. Aynı anda tek takım kullanın.
- Ödemeleri işlediğiniz satış noktasının para birimi. Square tahsilatı o para biriminde yapar.
- Saklı kart ve otomatik yenileme ödemeleri için **Başlangıç Ayarları** içindeki **Kart Saklama Modülü** alanında bu modülün seçili olması.

## Alanlar

- **Application ID**: Kart alanlarının yüklendiği uygulama. Zorunlu.
- **Location ID**: Her ödemenin işlendiği satış noktası. Zorunlu.
- **Access Token**: Her çekim, iade ve abonelik çağrısının arkasındaki sunucu belirteci. Zorunlu.
- **Webhook Signature Key**: Bildirimin gerçekten Square'den geldiğini kanıtlayan anahtar. Bu alan boşsa her bildirim reddedilir.
- **Webhook Notification URL**: Square tarafında kaydettiğiniz adresin birebir aynısı. Square adresi mesajla birlikte imzalar; tek karakter fark her doğrulamayı düşürür.
- **Recurring Subscriptions**: Ödeme panelinde otomatik yenileme seçeneği sunar. Varsayılan olarak kapalı. Açmadan önce İşlemler bölümüne bakın.
- **Test Mode**: Her çağrıyı Square test ortamına gönderir. Varsayılan olarak kapalı; test kimlik bilgileriyle çalışırken işaretleyin.

**Durum**, **Komisyon Oranı (%)**, **Para Birimi Dönüştürme**, **Kabul Edilen Tutar Aralığı** ve ülke listeleri her ağ geçidinde aynı çalışır. [Ödeme Modülleri](https://docs.wisecp.com/tr/odeme-modulleri) makalesine bakın. **Abonelik Ücretinin Güncellenmesi** seçeneği, yenileme tutarı değiştiğinde Square tarafındaki abonelik tutarını yeniden yazar; varsayılan olarak kapalı. **Callback URL**, **Success URL** ve **Failed URL** alanlarını değiştiremezsiniz: alanın sonundaki ikonla kopyalayın.

## İşlemler

### Kimlik bilgilerini Square'den alma

1. Square geliştirici paneline giriş yapın ve uygulamanızı açın.
2. **Credentials** bölümünü açın, **Sandbox** ya da **Production** sekmesini seçin. Uygulama kimliğini ve erişim belirtecini aynı sekmeden kopyalayın.
3. **Locations** bölümünü açın ve satış yaptığınız noktanın kimliğini kopyalayın.

### Kimlik bilgilerini girme

1. Modül kartını açın ve **Durum** kutusunu işaretleyin. Bunu yapmadan diğer alanlar kilitli kalır ve hiçbir değer kaydedilmez.
2. **Application ID**, **Location ID** ve **Access Token** alanlarını doldurun. Kimlik bilgileri test ortamına aitse **Test Mode** kutusunu işaretleyin.
3. **Değişiklikleri Kaydet** butonuna tıklayın. Bu yöntemi seçen müşteriler artık Square kart alanlarını görür.
4. Sandbox kimlikleri ve Square test kartıyla bir test faturası ödeyin. Sağlayıcı işlem kaydını ve faturanın **Ödendi** durumunu kontrol edin.

### Bildirim adresini kaydetme

1. Modül kartındaki **Callback URL** değerini alanın sonundaki ikonla kopyalayın.
2. Geliştirici panelinde **Webhooks → Subscriptions** bölümünü açın ve **Add subscription** butonuna tıklayın. Adresi bildirim adresi olarak yapıştırın ve `payment.updated` olayını seçin.
3. Yeni kaydı açın ve **Endpoint Details** bölümündeki imza anahtarını kopyalayın.
4. Modül kartına dönün, anahtarı **Webhook Signature Key** alanına, aynı adresi **Webhook Notification URL** alanına yazın ve **Değişiklikleri Kaydet** butonuna tıklayın. Square artık sonradan tamamlanan ödemeleri bildirebilir.

### Müşterinin kartını saklamasına izin verme

1. **Ayarlar → Finansal → Ödeme Ağ Geçitleri** ekranına dönün ve **Başlangıç Ayarları** sekmesini açın.
2. **Kart Saklama Modülü** alanından **Square** seçin ve **Değişiklikleri Kaydet** butonuna tıklayın.
3. Müşteriler artık hesaplarından kart ekleyebilir, ödeme sırasında saklı kartı seçebilir ve otomatik ödemeyi açabilir.

### Abonelik sunma

1. Önce kart saklama adımını tamamlayın. Abonelik saklı bir kartı çeker, o yüzden kart saklanmadan çalışmaz.
2. Modül kartında **Recurring Subscriptions** kutusunu işaretleyin ve **Değişiklikleri Kaydet** butonuna tıklayın.
3. Modül, ihtiyaç duyduğu her ödeme döngüsü için Square kataloğunuza yeniden kullanılabilir bir plan ekler. Çekilen tutar her abonelikte ayrıca belirlenir, plandan alınmaz.
4. Desteklenen döngüler için Square aboneliği sunulur; beş aylık dönem sunulmaz. Sonraki abonelik tahsilatlarını WISECP yenileme faturalarıyla karşılaştırın: bu sürümde otomatik kaydedilmeyebilir.

### Müşterinin izlediği yol

Kart saklama, otomatik ödeme ve abonelik seçenekleri kendi hesabı adına ödeme yapan hesap sahibine sunulur. Paylaşımlı ödeme bağlantılarında görünmez.

1. Müşteri bu yöntemi sepette, bir faturada ya da bakiye yüklerken seçer.
2. Kart alanları aynı sayfada açılır. Müşteri kart girer ya da daha önce sakladığı kartı seçer. İki kutu kartı saklamayı ve gelecek faturaları o kartla ödemeyi önerir.
3. Abonelik açıksa müşteri hangi yenilenen kalemlerin tek bir sözleşmeye gireceğini de seçer. Bir kalem seçmek kartın saklanmasını da gerektirir.
4. Square kartı çeker. Ödeme faturayı kapatır ve hizmet etkinleşir.

### Ödemeyi iade etme

1. Ödenmiş faturayı açın: `{admin}/invoices/detail?id={fatura}`
2. **Özet → Durumu Değiştir** bölümünde **İade Edildi** ve **Ödeme altyapısı ile iade** seçin. **Durumu Güncelle** butonuna tıklayın.
3. Square o fatura için tahsil edilen tutarı geri verir.

## Dikkat Edilecekler

> **Adres birebir eşleşmeli**
> 
> Square adresi mesajla birlikte imzalar. **Webhook Notification URL** boşsa modül kendi **Callback URL** değerini kullanır. Bu adres Square'deki kayıtla birebir eşleşmelidir. Yanlış adres veya eksik imza anahtarı doğrulamayı engeller; sonradan tamamlanan ödemenin faturası açık kalabilir.

> **Abonelik Square kataloğunuza yazar**
> 
> Seçeneği açmak, bu sistemin başka yerde de kullandığınız satıcı kataloğuna plan eklemesine izin verir. Her döngü için bir plan gerekir; bir kez oluşturulur ve yeniden kullanılır. Bu planları Square tarafında silerseniz yeni sözleşmeler açılmaz.

> **Aynı anda tek ortam**
> 
> Test ve canlı ortamın kendi uygulama kimliği, belirteci, satış noktası ve bildirim kaydı vardır. Birinden alınan belirteci diğerinin kimliğiyle karıştırmak her çağrıyı düşürür. Test Mode işaretsiz gelir; test ederken işaretleyin.

## Gerekli Yetkiler

**Ödeme Modülü Ayarları** (`MODULES_PAYMENT_SETTINGS`) yetkisi gerekir. Fatura iadesi ayrıca `INVOICES_OPERATION` ister.

## İlgili Makaleler

- [Ödeme Modülleri](https://docs.wisecp.com/tr/odeme-modulleri)
- [Fatura Detayı Genel Görünüm](https://docs.wisecp.com/tr/fatura-detayina-genel-bakis)
- [Abonelikler](https://docs.wisecp.com/tr/abonelikler)
- [Modül Yönetimi](https://docs.wisecp.com/tr/modul-yonetimi)