💳 Kayıtlı Ödeme API'si

Genel Bakış

Kayıtlı Ödeme API'si (Registered Payment API), tekrarlayan ödemeler (abonelikler) ve gelecekteki ödeme emirlerini yönetmek için kapsamlı bir çözüm sunar. Bu API ile müşterilerinizin kart bilgilerini güvenli bir şekilde saklayabilir ve otomatik ödemeler oluşturabilirsiniz.

Özellikler

✅ Güvenli Kart Saklama - PCI-DSS uyumlu kart bilgisi saklama
✅ Tekrarlayan Ödemeler - Günlük, aylık veya yıllık abonelikler
✅ Ödeme Emirleri - Gelecek tarihli tek seferlik ödemeler
✅ Webhook Bildirimleri - Gerçek zamanlı ödeme durum güncellemeleri
✅ Esnek Periyotlar - Özelleştirilebilir ödeme sıklıkları
✅ Durum Yönetimi - Abonelikleri aktif/pasif yapma

API Versiyonu

v0.50

Base URL

Test Ortamı

https://pgw.klogs.dev/

Canlı Ortam

https://pgw.klogs.io/

Kimlik Doğrulama

Tüm API istekleri Bearer token ile kimlik doğrulaması gerektirir.

http

Authorization: Bearer YOUR_API_KEY

⚠️ Güvenlik Uyarısı: API anahtarınızı asla public repository'lerde paylaşmayın.

Hızlı Başlangıç

1️⃣ Kart Sahibi Kaydı

Önce kart sahibini sisteme kaydedin:

bash

curl -X POST https://pgw.klogs.dev/owner \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+905551234567"}'

2️⃣ Tekrarlayan Ödeme Oluşturma

Aylık abonelik oluşturun:

bash

curl -X POST https://pgw.klogs.dev/recurring \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SUB-001",
    "amount": 99.90,
    "currencyCode": "TRY",
    "ownerDescription": {
      "fullName": "Ahmet Yılmaz",
      "phone": "+905551234567",
      "email": "ahmet@example.com",
      "cardId": "CARD_UUID"
    },
    "firstPaymentTime": "2026-03-01T00:00:00Z",
    "frequency": "monthly",
    "interval": 1,
    "dayOfMonth": 1
  }'

3️⃣ Webhook Yapılandırması

Kart saklama tamamlandığında bildirim almak için webhook endpoint'inizi yapılandırın:

javascript

app.post('/webhooks/card-storage/:type/:id', (req, res) => {
  const { cardId, ownerId } = req.body;
  console.log(`Card ${cardId} saved for owner ${ownerId}`);
  res.json({ success: true });
});

API Endpointleri

Kart Sahibi İşlemleri

Method	Endpoint	Açıklama
POST	/owner	Kart sahibi kaydı oluşturur

Detaylı Dokümantasyon →

Ödeme Emri İşlemleri

Method	Endpoint	Açıklama
POST	/paymentOrder	Gelecek tarihli ödeme emri oluşturur

Detaylı Dokümantasyon →

Tekrarlayan Ödeme İşlemleri

Method	Endpoint	Açıklama
POST	/recurring	Yeni tekrarlayan ödeme oluşturur
GET	/recurring	Tekrarlayan ödemeleri listeler
PUT	/recurring/	UUID ile günceller
PUT	/recurring/subscription/	Subscription ID ile günceller

Detaylı Dokümantasyon →

Webhook İşlemleri

Method	Endpoint	Açıklama
POST	/api/return/webhook/complete-cardstorage/{type}/	Kart saklama tamamlama webhook'u

Detaylı Dokümantasyon →

Veri Modelleri

RegisteredPaymentStatus

Ödeme kaydı durumları:

Durum	Açıklama
`active`	Aktif - ödemeler işlenecek
`disabled`	Devre dışı - ödemeler yapılmayacak
`complete`	Tamamlandı
`waitForOwnerConfirmation`	Kart sahibi onayı bekleniyor
`waitForCardSave`	Kart kaydı bekleniyor

RecurringPaymentFrequence

Ödeme sıklığı değerleri:

Değer	Açıklama
`daily`	Günlük ödemeler
`monthly`	Aylık ödemeler
`yearly`	Yıllık ödemeler

OrderDirection

Sıralama yönü:

Değer	Açıklama
`asc`	Artan sıralama
`desc`	Azalan sıralama

Kullanım Senaryoları

Senaryo 1: Aylık Abonelik

Netflix benzeri streaming servisi için aylık abonelik:

json

{
  "reference": "NETFLIX-USER-123",
  "amount": 99.99,
  "currencyCode": "TRY",
  "frequency": "monthly",
  "interval": 1,
  "dayOfMonth": 1,
  "explanation": "Premium abonelik"
}

Senaryo 2: 3 Ayda Bir Ödeme

Üç aylık dönemlerde ödeme:

json

{
  "reference": "QUARTERLY-SUBSCRIPTION",
  "amount": 250.00,
  "currencyCode": "TRY",
  "frequency": "monthly",
  "interval": 3,
  "dayOfMonth": 15,
  "explanation": "3 aylık abonelik"
}

Senaryo 3: Yıllık Yenileme

Her yıl Ocak ayının 1'inde ödeme:

json

{
  "reference": "ANNUAL-LICENSE",
  "amount": 999.00,
  "currencyCode": "TRY",
  "frequency": "yearly",
  "interval": 1,
  "monthOfYear": 1,
  "dayOfMonth": 1,
  "explanation": "Yıllık lisans ücreti"
}

Senaryo 4: Tek Seferlik Gelecek Ödeme

3 ay sonra tek seferlik ödeme:

json

{
  "reference": "FUTURE-PAYMENT-001",
  "amount": 500.00,
  "currencyCode": "TRY",
  "paymentTime": "2026-05-16T10:00:00Z",
  "explanation": "3 ay sonra ödeme"
}

Hata Yönetimi

API, standart HTTP durum kodları ve RFC 7807 Problem Details formatını kullanır.

Örnek Hata Yanıtı

json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "The amount field is required.",
  "instance": "/recurring"
}

Yaygın HTTP Kodları

Kod	Anlamı	Açıklama
200	OK	İşlem başarılı
400	Bad Request	Geçersiz istek parametreleri
401	Unauthorized	Kimlik doğrulama başarısız
403	Forbidden	Yetkisiz erişim
404	Not Found	Kaynak bulunamadı
500	Internal Server Error	Sunucu hatası

Rate Limiting

API istekleri için rate limit uygulanır:

Test Ortamı: 100 istek/dakika
Canlı Ortam: 1000 istek/dakika

Rate limit aşıldığında 429 Too Many Requests yanıtı alırsınız.

Güvenlik

Best Practices

✅ HTTPS Kullanın - Tüm istekleri HTTPS üzerinden gönderin
✅ Token Güvenliği - API anahtarlarını environment variables'da saklayın
✅ Webhook Doğrulama - Hash doğrulaması ile webhook'ları doğrulayın
✅ IP Whitelisting - Mümkünse IP kısıtlaması yapın
✅ Loglama - Tüm işlemleri loglayın

PCI-DSS Uyumluluğu

Klogs Payment Gateway, PCI-DSS Level 1 sertifikalıdır. Kart bilgileri:

AES-256 ile şifrelenir
Tokenize edilir
Güvenli vault'da saklanır
Asla düz metin olarak loglanmaz

Destek ve İletişim

Teknik Destek

Email: info@klogs.com.tr
Web: https://klogs.com.tr/contact
Dokümantasyon: https://docs.klogs.com.tr

Lisans

Bu API, KLOGS License altında lisanslanmıştır.
Detaylar: https://klogs.com.tr/license

Kullanım Şartları

Servis şartları: https://klogs.com.tr/terms

Değişiklik Geçmişi

v0.50 (Current)

✅ Tekrarlayan ödemeler desteği
✅ Ödeme emri özelliği
✅ Webhook bildirimleri
✅ Esnek periyot yönetimi

Sonraki Adımlar

Kart Sahibi Kaydı oluşturmayı öğrenin
Tekrarlayan Ödeme nasıl kurulur inceleyin
Webhook entegrasyonunu tamamlayın
Test ortamında denemeler yapın
Canlıya geçin! 🚀

💡 İpucu: Başlamadan önce test kartlarıyla işlem yaparak API'yi tanıyın. Test Kartları bölümüne göz atın.

💳 Kayıtlı Ödeme API'si ​

Genel Bakış ​

Özellikler ​

API Versiyonu ​

Base URL ​

Test Ortamı ​

Canlı Ortam ​

Kimlik Doğrulama ​

Hızlı Başlangıç ​

1️⃣ Kart Sahibi Kaydı ​

2️⃣ Tekrarlayan Ödeme Oluşturma ​

3️⃣ Webhook Yapılandırması ​

API Endpointleri ​

Kart Sahibi İşlemleri ​

Ödeme Emri İşlemleri ​

Tekrarlayan Ödeme İşlemleri ​

Webhook İşlemleri ​

Veri Modelleri ​

RegisteredPaymentStatus ​

RecurringPaymentFrequence ​

OrderDirection ​

Kullanım Senaryoları ​

Senaryo 1: Aylık Abonelik ​

Senaryo 2: 3 Ayda Bir Ödeme ​

Senaryo 3: Yıllık Yenileme ​

Senaryo 4: Tek Seferlik Gelecek Ödeme ​

Hata Yönetimi ​

Örnek Hata Yanıtı ​

Yaygın HTTP Kodları ​

Rate Limiting ​

Güvenlik ​

Best Practices ​

PCI-DSS Uyumluluğu ​

Destek ve İletişim ​

Teknik Destek ​

Lisans ​

Kullanım Şartları ​

Değişiklik Geçmişi ​

v0.50 (Current) ​

Sonraki Adımlar ​

💳 Kayıtlı Ödeme API'si

Genel Bakış

Özellikler

API Versiyonu

Base URL

Test Ortamı

Canlı Ortam

Kimlik Doğrulama

Hızlı Başlangıç

1️⃣ Kart Sahibi Kaydı

2️⃣ Tekrarlayan Ödeme Oluşturma

3️⃣ Webhook Yapılandırması

API Endpointleri

Kart Sahibi İşlemleri

Ödeme Emri İşlemleri

Tekrarlayan Ödeme İşlemleri

Webhook İşlemleri

Veri Modelleri

RegisteredPaymentStatus

RecurringPaymentFrequence

OrderDirection

Kullanım Senaryoları

Senaryo 1: Aylık Abonelik

Senaryo 2: 3 Ayda Bir Ödeme

Senaryo 3: Yıllık Yenileme

Senaryo 4: Tek Seferlik Gelecek Ödeme

Hata Yönetimi

Örnek Hata Yanıtı

Yaygın HTTP Kodları

Rate Limiting

Güvenlik

Best Practices

PCI-DSS Uyumluluğu

Destek ve İletişim

Teknik Destek

Lisans

Kullanım Şartları

Değişiklik Geçmişi

v0.50 (Current)

Sonraki Adımlar