🔄 Tekrarlayan Ödeme İşlemleri

📝 Tekrarlayan Ödeme Oluşturma

Endpoint

POST /recurring

Açıklama

Düzenli aralıklarla otomatik olarak gerçekleştirilecek tekrarlayan ödeme (abonelik) oluşturur. Günlük, aylık veya yıllık periyotlarla ödeme planı yapılabilir.

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request: RecurringPaymentRequest

{
  "reference": "SUB-2026-001",
  "amount": 99.90,
  "currencyCode": "TRY",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "explanation": "Premium abonelik - aylık",
  "ownerDescription": {
    "fullName": "Ayşe Demir",
    "email": "ayse.demir@example.com",
    "phone": "+905559876543",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "paymentChannel": "mobile",
  "firstPaymentTime": "2026-03-01T00:00:00Z",
  "lastPaymentTime": "2027-03-01T00:00:00Z",
  "frequency": "monthly",
  "interval": 1,
  "dayOfMonth": 1
}

Parametreler

Parametre	Tip	Zorunlu	Açıklama
reference	string	✅	Abonelik referans kodu (max 150 karakter)
amount	number	✅	Her ödeme için tutar
currencyCode	string	✅	Para birimi kodu (örn: TRY, USD, EUR)
paymentSystemId	uuid	❌	Kullanılacak ödeme sistemi ID'si
explanation	string	❌	Ödeme açıklaması (max 400 karakter)
ownerDescription	object	✅	Kart sahibi bilgileri
paymentChannel	string	❌	Ödeme kanalı (max 50 karakter)
firstPaymentTime	datetime	✅	İlk ödeme tarihi (ISO 8601)
lastPaymentTime	datetime	❌	Son ödeme tarihi (ISO 8601)
frequency	string	✅	Ödeme sıklığı: daily, monthly, yearly
interval	integer	✅	Periyot aralığı (1-30 arası)
monthOfYear	integer	⚠️	Yılın hangi ayı (1-12) - yearly için zorunlu
dayOfMonth	integer	⚠️	Ayın hangi günü (1-30) - monthly/yearly için zorunlu

Frequency (Sıklık) Değerleri

Değer	Açıklama	Örnek
daily	Günlük	Her 1 gün, her 5 gün vb.
monthly	Aylık	Her ayın 1'i, her ayın 15'i vb.
yearly	Yıllık	Her yıl Ocak ayının 1'i vb.

Response

Başarılı İstek (200 OK)

{
  "success": true,
  "error": null,
  "shouldBeOwnerConfirmation": false,
  "ownerId": "OWN-123456",
  "orderStatus": "active"
}

Hata (403 Forbidden)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "instance": "/recurring"
}

---

📋 Tekrarlayan Ödemeleri Listeleme

Endpoint

GET /recurring

Açıklama

Mevcut tekrarlayan ödemeleri listeler. Filtreleme, sayfalama ve sıralama destekler.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
Subscription	string	❌	Abonelik ID'sine göre filtreleme
Page	integer	❌	Sayfa numarası (varsayılan: 1)
PageSize	integer	❌	Sayfa başına kayıt sayısı
OrderBy	string	❌	Sıralama alanı
Dir	string	❌	Sıralama yönü: asc veya desc

Örnek İstek

GET /recurring?Page=1&PageSize=10&OrderBy=createdAtUtc&Dir=desc

Response: RecurringPaymentModelPagedList

{
  "currentPage": 1,
  "pageCount": 5,
  "totalCount": 47,
  "hasNext": true,
  "hasPrevious": false,
  "stateKey": "abc123",
  "pages": [1, 2, 3, 4, 5],
  "list": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 99.90,
      "currencyCode": "TRY",
      "status": "active",
      "createdAtUtc": "2026-02-16T10:00:00Z",
      "reference": "SUB-2026-001",
      "explanation": "Premium abonelik - aylık",
      "interval": 1,
      "dayOfMonth": 1,
      "monthOfYear": null,
      "nextPaymentAtUtc": "2026-03-01T00:00:00Z",
      "lastPaymentAtUtc": "2026-02-01T00:00:00Z",
      "phone": "+905559876543",
      "email": "ayse.demir@example.com"
    }
  ]
}

---

✏️ Tekrarlayan Ödeme Güncelleme

Endpoint 1: Subscription ID ile Güncelleme

PUT /recurring/subscription/{subscription}

Endpoint 2: UUID ile Güncelleme

PUT /recurring/{id}

Açıklama

Mevcut bir tekrarlayan ödemenin parametrelerini günceller. Tutar, para birimi, sıklık ve diğer ayarlar değiştirilebilir.

Path Parametreleri

Parametre	Tip	Açıklama
subscription	string	Abonelik ID'si (string)
id	uuid	Tekrarlayan ödeme UUID'si

Request: UpdateRecurringPaymentRequest

{
  "amount": 119.90,
  "currencyCode": "TRY",
  "explanation": "Premium Plus abonelik - aylık",
  "lastPaymentTime": "2028-03-01T00:00:00Z",
  "paymentSystemGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentChannel": "mobile",
  "frequency": "monthly",
  "status": "active",
  "interval": 1,
  "dayOfMonth": 1
}

Parametreler

Parametre	Tip	Zorunlu	Açıklama
amount	number	✅	Güncel ödeme tutarı
currencyCode	string	✅	Para birimi kodu
explanation	string	❌	Açıklama (max 400 karakter)
lastPaymentTime	datetime	❌	Son ödeme tarihi
paymentSystemGroupId	uuid	❌	Ödeme sistemi grup ID'si
paymentSystemId	uuid	❌	Ödeme sistemi ID'si
paymentChannel	string	❌	Ödeme kanalı (max 50 karakter)
frequency	string	❌	Ödeme sıklığı
status	string	❌	Durum değişikliği
interval	integer	❌	Periyot aralığı (1-30)
monthOfYear	integer	⚠️	Ayın günü (1-12)
dayOfMonth	integer	⚠️	Ayın günü (1-30)

Response

Başarılı İstek (200 OK)

{
  "success": true
}

---

Örnek Kullanımlar

cURL - Oluşturma

curl -X POST https://pgw.klogs.dev/recurring \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SUB-2026-001",
    "amount": 99.90,
    "currencyCode": "TRY",
    "ownerDescription": {
      "fullName": "Ayşe Demir",
      "email": "ayse.demir@example.com",
      "phone": "+905559876543",
      "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "firstPaymentTime": "2026-03-01T00:00:00Z",
    "frequency": "monthly",
    "interval": 1,
    "dayOfMonth": 1
  }'

JavaScript - Listeleme

const response = await fetch('https://pgw.klogs.dev/recurring?Page=1&PageSize=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.list);

C# - Güncelleme

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var updateRequest = new {
    amount = 119.90,
    currencyCode = "TRY",
    status = "active"
};

var content = new StringContent(
    JsonSerializer.Serialize(updateRequest),
    Encoding.UTF8,
    "application/json"
);

var subscriptionId = "SUB-2026-001";
var response = await client.PutAsync(
    $"https://pgw.klogs.dev/recurring/subscription/{subscriptionId}",
    content
);

Notlar

• Tekrarlayan ödemeler oluşturulurken firstPaymentTime gelecekte olmalıdır
• interval değeri 1-30 arasında olmalıdır
• Aylık ödemeler için dayOfMonth parametresi zorunludur
• Yıllık ödemeler için dayOfMonth ve monthOfYear parametreleri zorunludur
• Abonelik durumu active olduğunda ödemeler otomatik işlenir
• Aboneliği durdurmak için status değerini disabled olarak güncelleyin
• Başarısız ödemeler için otomatik retry mekanizması vardır

İlişkili Endpointler

• Kart Sahibi Kaydı
• Ödeme Emri Oluşturma
• Webhook İşlemleri