🔄 Wiederkehrende Zahlungsoperationen

📝 Wiederkehrende Zahlung Erstellen

Endpunkt

POST /recurring

Beschreibung

Erstellt eine wiederkehrende Zahlung (Abonnement), die automatisch in regelmäßigen Abständen ausgeführt wird. Zahlungen können in täglichen, monatlichen oder jährlichen Zeiträumen geplant werden.

Header

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

Anfrage: RecurringPaymentRequest

{
  "reference": "SUB-2026-001",
  "amount": 99.90,
  "currencyCode": "TRY",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "explanation": "Premium-Abonnement - monatlich",
  "ownerDescription": {
    "fullName": "Julia Schmidt",
    "email": "julia.schmidt@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
}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
reference	string	✅	Abonnementreferenzcode (max. 150 Zeichen)
amount	number	✅	Betrag für jede Zahlung
currencyCode	string	✅	Währungscode (z.B. TRY, USD, EUR)
paymentSystemId	uuid	❌	Zu verwendende Zahlungssystem-ID
explanation	string	❌	Zahlungsbeschreibung (max. 400 Zeichen)
ownerDescription	object	✅	Karteninhaberinformationen
paymentChannel	string	❌	Zahlungskanal (max. 50 Zeichen)
firstPaymentTime	datetime	✅	Erstes Zahlungsdatum (ISO 8601)
lastPaymentTime	datetime	❌	Letztes Zahlungsdatum (ISO 8601)
frequency	string	✅	Zahlungshäufigkeit: daily, monthly, yearly
interval	integer	✅	Zeitraumintervall (zwischen 1-30)
monthOfYear	integer	⚠️	Monat des Jahres (1-12) - erforderlich für yearly
dayOfMonth	integer	⚠️	Tag des Monats (1-30) - erforderlich für monthly/yearly

Häufigkeitswerte

Wert	Beschreibung	Beispiel
daily	Täglich	Jeden 1. Tag, jeden 5. Tag, usw.
monthly	Monatlich	1. eines jeden Monats, 15. eines jeden Monats, usw.
yearly	Jährlich	1. Januar jedes Jahr, usw.

Antwort

Erfolgreiche Anfrage (200 OK)

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

Fehler (403 Forbidden)

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

---

📋 Wiederkehrende Zahlungen Auflisten

Endpunkt

GET /recurring

Beschreibung

Listet vorhandene wiederkehrende Zahlungen auf. Unterstützt Filterung, Paginierung und Sortierung.

Query-Parameter

Parameter	Typ	Erforderlich	Beschreibung
Subscription	string	❌	Nach Abonnement-ID filtern
Page	integer	❌	Seitennummer (Standard: 1)
PageSize	integer	❌	Datensätze pro Seite
OrderBy	string	❌	Sortierfeld
Dir	string	❌	Sortierrichtung: asc oder desc

Beispielanfrage

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

Antwort: 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-Abonnement - monatlich",
      "interval": 1,
      "dayOfMonth": 1,
      "monthOfYear": null,
      "nextPaymentAtUtc": "2026-03-01T00:00:00Z",
      "lastPaymentAtUtc": "2026-02-01T00:00:00Z",
      "phone": "+905559876543",
      "email": "julia.schmidt@example.com"
    }
  ]
}

---

✏️ Wiederkehrende Zahlung Aktualisieren

Endpunkt 1: Aktualisierung nach Abonnement-ID

PUT /recurring/subscription/{subscription}

Endpunkt 2: Aktualisierung nach UUID

PUT /recurring/{id}

Beschreibung

Aktualisiert Parameter einer bestehenden wiederkehrenden Zahlung. Betrag, Währung, Häufigkeit und andere Einstellungen können geändert werden.

Pfadparameter

Parameter	Typ	Beschreibung
subscription	string	Abonnement-ID (String)
id	uuid	Wiederkehrende Zahlungs-UUID

Anfrage: UpdateRecurringPaymentRequest

{
  "amount": 119.90,
  "currencyCode": "TRY",
  "explanation": "Premium Plus-Abonnement - monatlich",
  "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
}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
amount	number	✅	Aktualisierter Zahlungsbetrag
currencyCode	string	✅	Währungscode
explanation	string	❌	Beschreibung (max. 400 Zeichen)
lastPaymentTime	datetime	❌	Letztes Zahlungsdatum
paymentSystemGroupId	uuid	❌	Zahlungssystemgruppen-ID
paymentSystemId	uuid	❌	Zahlungssystem-ID
paymentChannel	string	❌	Zahlungskanal (max. 50 Zeichen)
frequency	string	❌	Zahlungshäufigkeit
status	string	❌	Statusänderung
interval	integer	❌	Zeitraumintervall (1-30)
monthOfYear	integer	⚠️	Monat des Jahres (1-12)
dayOfMonth	integer	⚠️	Tag des Monats (1-30)

Antwort

Erfolgreiche Anfrage (200 OK)

{
  "success": true
}

---

Beispielverwendung

cURL - Erstellen

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

JavaScript - Auflisten

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

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

C# - Aktualisieren

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.io/recurring/subscription/{subscriptionId}",
    content
);

Hinweise

• firstPaymentTime muss bei der Erstellung wiederkehrender Zahlungen in der Zukunft liegen
• interval-Wert muss zwischen 1-30 liegen
• dayOfMonth-Parameter ist für monatliche Zahlungen erforderlich
• dayOfMonth- und monthOfYear-Parameter sind für jährliche Zahlungen erforderlich
• Zahlungen werden automatisch verarbeitet, wenn der Abonnementstatus active ist
• Um ein Abonnement zu stoppen, aktualisieren Sie den status auf disabled
• Es gibt einen automatischen Wiederholungsmechanismus für fehlgeschlagene Zahlungen

Verwandte Endpunkte

• Karteninhaber-Registrierung
• Zahlungsauftrag Erstellen
• Webhook-Operationen