💳 Registrierte Zahlungs-API

Überblick

Die Registrierte Zahlungs-API (Recurring and Payment Order API) bietet eine umfassende Lösung für die Verwaltung wiederkehrender Zahlungen (Abonnements) und zukünftiger Zahlungsaufträge. Mit dieser API können Sie Karteninformationen Ihrer Kunden sicher speichern und automatische Zahlungen erstellen.

Funktionen

✅ Sichere Kartenspeicherung - PCI-DSS-konforme Speicherung von Karteninformationen
✅ Wiederkehrende Zahlungen - Tägliche, monatliche oder jährliche Abonnements
✅ Zahlungsaufträge - Zukünftige einmalige Zahlungen
✅ Webhook-Benachrichtigungen - Echtzeit-Statusaktualisierungen von Zahlungen
✅ Flexible Zeiträume - Anpassbare Zahlungshäufigkeiten
✅ Statusverwaltung - Abonnements aktivieren/deaktivieren

API-Version

v0.50

Basis-URL

Testumgebung

https://pgw.klogs.dev/

Produktionsumgebung

https://pgw.klogs.io/

Authentifizierung

Alle API-Anfragen erfordern eine Bearer-Token-Authentifizierung.

http

Authorization: Bearer YOUR_API_KEY

⚠️ Sicherheitswarnung: Teilen Sie Ihren API-Schlüssel niemals in öffentlichen Repositories.

Schnellstart

1️⃣ Karteninhaber Registrieren

Registrieren Sie zunächst den Karteninhaber im System:

bash

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

2️⃣ Wiederkehrende Zahlung Erstellen

Erstellen Sie ein monatliches Abonnement:

bash

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

3️⃣ Webhook Konfigurieren

Konfigurieren Sie Ihren Webhook-Endpunkt, um Benachrichtigungen zu erhalten, wenn die Kartenspeicherung abgeschlossen ist:

javascript

app.post('/webhooks/card-storage/:type/:id', (req, res) => {
  const { cardId, ownerId } = req.body;
  console.log(`Karte ${cardId} für Inhaber ${ownerId} gespeichert`);
  res.json({ success: true });
});

API-Endpunkte

Karteninhaber-Operationen

Methode	Endpunkt	Beschreibung
POST	/owner	Erstellt einen Karteninhaber-Datensatz

Detaillierte Dokumentation →

Zahlungsauftrags-Operationen

Methode	Endpunkt	Beschreibung
POST	/paymentOrder	Erstellt einen zukünftigen Zahlungsauftrag

Detaillierte Dokumentation →

Wiederkehrende Zahlungs-Operationen

Methode	Endpunkt	Beschreibung
POST	/recurring	Erstellt eine neue wiederkehrende Zahlung
GET	/recurring	Listet wiederkehrende Zahlungen auf
PUT	/recurring/	Aktualisiert nach UUID
PUT	/recurring/subscription/	Aktualisiert nach Abonnement-ID

Detaillierte Dokumentation →

Webhook-Operationen

Methode	Endpunkt	Beschreibung
POST	/api/return/webhook/complete-cardstorage/{type}/	Webhook für Kartenspeicherung abgeschlossen

Detaillierte Dokumentation →

Datenmodelle

RegisteredPaymentStatus

Zahlungsdatensatz-Status:

Status	Beschreibung
`active`	Aktiv - Zahlungen werden verarbeitet
`disabled`	Deaktiviert - keine Zahlungen werden durchgeführt
`complete`	Abgeschlossen
`waitForOwnerConfirmation`	Wartet auf Karteninhaber-Bestätigung
`waitForCardSave`	Wartet auf Kartenspeicherung

RecurringPaymentFrequence

Zahlungshäufigkeitswerte:

Wert	Beschreibung
`daily`	Tägliche Zahlungen
`monthly`	Monatliche Zahlungen
`yearly`	Jährliche Zahlungen

OrderDirection

Sortierrichtung:

Wert	Beschreibung
`asc`	Aufsteigende Reihenfolge
`desc`	Absteigende Reihenfolge

Anwendungsfälle

Szenario 1: Monatliches Abonnement

Monatliches Abonnement für einen Netflix-ähnlichen Streaming-Dienst:

json

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

Szenario 2: Vierteljährliche Zahlung

Zahlung alle drei Monate:

json

{
  "reference": "QUARTERLY-SUBSCRIPTION",
  "amount": 250.00,
  "currencyCode": "TRY",
  "frequency": "monthly",
  "interval": 3,
  "dayOfMonth": 15,
  "explanation": "3-Monats-Abonnement"
}

Szenario 3: Jährliche Verlängerung

Zahlung am 1. Januar jedes Jahres:

json

{
  "reference": "ANNUAL-LICENSE",
  "amount": 999.00,
  "currencyCode": "TRY",
  "frequency": "yearly",
  "interval": 1,
  "monthOfYear": 1,
  "dayOfMonth": 1,
  "explanation": "Jährliche Lizenzgebühr"
}

Szenario 4: Einmalige Zukünftige Zahlung

Einmalige Zahlung in 3 Monaten:

json

{
  "reference": "FUTURE-PAYMENT-001",
  "amount": 500.00,
  "currencyCode": "TRY",
  "paymentTime": "2026-05-16T10:00:00Z",
  "explanation": "Zahlung in 3 Monaten"
}

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes und das RFC 7807 Problem Details-Format.

Beispiel-Fehlerantwort

json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Ein oder mehrere Validierungsfehler sind aufgetreten.",
  "status": 400,
  "detail": "Das Betragsfeld ist erforderlich.",
  "instance": "/recurring"
}

Häufige HTTP-Codes

Code	Bedeutung	Beschreibung
200	OK	Operation erfolgreich
400	Bad Request	Ungültige Anfrageparameter
401	Unauthorized	Authentifizierung fehlgeschlagen
403	Forbidden	Unbefugter Zugriff
404	Not Found	Ressource nicht gefunden
500	Internal Server Error	Serverfehler

Ratenbegrenzung

API-Anfragen unterliegen einer Ratenbegrenzung:

Testumgebung: 100 Anfragen/Minute
Produktionsumgebung: 1000 Anfragen/Minute

Bei Überschreitung des Ratenlimits erhalten Sie eine 429 Too Many Requests-Antwort.

Sicherheit

Best Practices

✅ HTTPS verwenden - Alle Anfragen über HTTPS senden
✅ Token-Sicherheit - API-Schlüssel in Umgebungsvariablen speichern
✅ Webhook-Validierung - Webhooks mit Hash-Verifizierung validieren
✅ IP-Whitelisting - IP-Einschränkungen anwenden, wenn möglich
✅ Protokollierung - Alle Operationen protokollieren

PCI-DSS-Konformität

Klogs Payment Gateway ist PCI-DSS Level 1 zertifiziert. Karteninformationen:

Mit AES-256 verschlüsselt
Tokenisiert
In sicherem Vault gespeichert
Niemals im Klartext protokolliert

Support und Kontakt

Technische Unterstützung

E-Mail: info@klogs.com.tr
Web: https://klogs.com.tr/contact
Dokumentation: https://docs.klogs.com.tr

Lizenz

Diese API ist unter der KLOGS-Lizenz lizenziert.
Details: https://klogs.com.tr/license

Nutzungsbedingungen

Service-Bedingungen: https://klogs.com.tr/terms

Änderungsprotokoll

v0.50 (Aktuell)

✅ Unterstützung für wiederkehrende Zahlungen
✅ Zahlungsauftragsfunktion
✅ Webhook-Benachrichtigungen
✅ Flexible Zeitraumverwaltung

Nächste Schritte

Erfahren Sie, wie Sie Karteninhaber-Registrierung erstellen
Überprüfen Sie, wie Sie Wiederkehrende Zahlung einrichten
Vervollständigen Sie die Webhook-Integration
Testen Sie in der Testumgebung
Gehen Sie live! 🚀

💡 Tipp: Bevor Sie beginnen, machen Sie sich mit der API vertraut, indem Sie mit Testkarten testen. Besuchen Sie den Abschnitt Testkarten.

💳 Registrierte Zahlungs-API ​

Überblick ​

Funktionen ​

API-Version ​

Basis-URL ​

Testumgebung ​

Produktionsumgebung ​

Authentifizierung ​

Schnellstart ​

1️⃣ Karteninhaber Registrieren ​

2️⃣ Wiederkehrende Zahlung Erstellen ​

3️⃣ Webhook Konfigurieren ​

API-Endpunkte ​

Karteninhaber-Operationen ​

Zahlungsauftrags-Operationen ​

Wiederkehrende Zahlungs-Operationen ​

Webhook-Operationen ​

Datenmodelle ​

RegisteredPaymentStatus ​

RecurringPaymentFrequence ​

OrderDirection ​

Anwendungsfälle ​

Szenario 1: Monatliches Abonnement ​

Szenario 2: Vierteljährliche Zahlung ​

Szenario 3: Jährliche Verlängerung ​

Szenario 4: Einmalige Zukünftige Zahlung ​

Fehlerbehandlung ​

Beispiel-Fehlerantwort ​

Häufige HTTP-Codes ​

Ratenbegrenzung ​

Sicherheit ​

Best Practices ​

PCI-DSS-Konformität ​

Support und Kontakt ​

Technische Unterstützung ​

Lizenz ​

Nutzungsbedingungen ​

Änderungsprotokoll ​

v0.50 (Aktuell) ​

Nächste Schritte ​

💳 Registrierte Zahlungs-API

Überblick

Funktionen

API-Version

Basis-URL

Testumgebung

Produktionsumgebung

Authentifizierung

Schnellstart

1️⃣ Karteninhaber Registrieren

2️⃣ Wiederkehrende Zahlung Erstellen

3️⃣ Webhook Konfigurieren

API-Endpunkte

Karteninhaber-Operationen

Zahlungsauftrags-Operationen

Wiederkehrende Zahlungs-Operationen

Webhook-Operationen

Datenmodelle

RegisteredPaymentStatus

RecurringPaymentFrequence

OrderDirection

Anwendungsfälle

Szenario 1: Monatliches Abonnement

Szenario 2: Vierteljährliche Zahlung

Szenario 3: Jährliche Verlängerung

Szenario 4: Einmalige Zukünftige Zahlung

Fehlerbehandlung

Beispiel-Fehlerantwort

Häufige HTTP-Codes

Ratenbegrenzung

Sicherheit

Best Practices

PCI-DSS-Konformität

Support und Kontakt

Technische Unterstützung

Lizenz

Nutzungsbedingungen

Änderungsprotokoll

v0.50 (Aktuell)

Nächste Schritte