📋 Zahlungsauftrag Erstellen

Endpunkt

POST /paymentOrder

Beschreibung

Erstellt einen Zahlungsauftrag, der zu einem bestimmten Datum ausgeführt wird. Dieser Vorgang plant eine einmalige Zahlung für einen registrierten Karteninhaber in der Zukunft. Der Zahlungsauftrag wird automatisch am angegebenen Datum verarbeitet.

Header

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

Anfrage: PaymentOrderRequest

{
  "reference": "ORDER-2026-001",
  "amount": 150.50,
  "currencyCode": "TRY",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "explanation": "Abonnementgebühr - Februar 2026",
  "ownerDescription": {
    "fullName": "Max Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+905551234567",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "paymentChannel": "web",
  "paymentTime": "2026-02-28T09:00:00Z"
}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
reference	string	✅	Auftragsreferenzcode (max. 150 Zeichen)
amount	number	✅	Zahlungsbetrag (Dezimalzahl)
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)
paymentTime	datetime	✅	Datum und Uhrzeit der Zahlungsausführung (ISO 8601)

OwnerDescription Parameter

Parameter	Typ	Erforderlich	Beschreibung
fullName	string	✅	Vollständiger Name des Karteninhabers (max. 100 Zeichen)
email	string	❌	E-Mail-Adresse
phone	string	✅	Telefonnummer (E.164-Format)
cardId	uuid	✅	Registrierte Karten-ID

Antwort

Erfolgreiche Anfrage (200 OK)

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

Antwortparameter

Parameter	Typ	Beschreibung
success	boolean	Erfolgsstatus der Operation
error	object	Fehlerinformationen (falls vorhanden)
shouldBeOwnerConfirmation	boolean	Ist Karteninhaber-Bestätigung erforderlich?
ownerId	string	Karteninhaber-ID
orderStatus	string	Zahlungsauftragsstatus

OrderStatus Werte

Wert	Beschreibung
active	Aktiv - wird verarbeitet, wenn Zahlungszeit erreicht ist
disabled	Deaktiviert
complete	Abgeschlossen
waitForOwnerConfirmation	Wartet auf Karteninhaber-Bestätigung
waitForCardSave	Wartet auf Kartenspeicherung

Fehlercodes

HTTP-Code	Beschreibung
200	Operation erfolgreich
400	Ungültige Anfrage (Parameterfehler)
401	Unbefugter Zugriff
403	Zugriff verweigert

Beispielverwendung

cURL

curl -X POST https://pgw.klogs.io/paymentOrder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-2026-001",
    "amount": 150.50,
    "currencyCode": "TRY",
    "explanation": "Abonnementgebühr - Februar 2026",
    "ownerDescription": {
      "fullName": "Max Mustermann",
      "email": "max.mustermann@example.com",
      "phone": "+905551234567",
      "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "paymentChannel": "web",
    "paymentTime": "2026-02-28T09:00:00Z"
  }'

JavaScript

const response = await fetch('https://pgw.klogs.io/paymentOrder', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'ORDER-2026-001',
    amount: 150.50,
    currencyCode: 'TRY',
    explanation: 'Abonnementgebühr - Februar 2026',
    ownerDescription: {
      fullName: 'Max Mustermann',
      email: 'max.mustermann@example.com',
      phone: '+905551234567',
      cardId: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    },
    paymentChannel: 'web',
    paymentTime: '2026-02-28T09:00:00Z'
  })
});

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

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

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

var request = new {
    reference = "ORDER-2026-001",
    amount = 150.50,
    currencyCode = "TRY",
    explanation = "Abonnementgebühr - Februar 2026",
    ownerDescription = new {
        fullName = "Max Mustermann",
        email = "max.mustermann@example.com",
        phone = "+905551234567",
        cardId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    paymentChannel = "web",
    paymentTime = "2026-02-28T09:00:00Z"
};

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

var response = await client.PostAsync("https://pgw.klogs.io/paymentOrder", content);
var result = await response.Content.ReadAsStringAsync();

Hinweise

• paymentTime muss ein zukünftiges Datum sein
• cardId muss eine zuvor registrierte Karten-ID sein
• reference sollte für jeden Zahlungsauftrag eindeutig sein
• Der Zahlungsauftrag wird automatisch am angegebenen Datum ausgeführt
• Es gibt einen Wiederholungsmechanismus für fehlgeschlagene Zahlungen
• Zahlungsergebnisse werden per Webhook benachrichtigt

Verwandte Endpunkte

• Karteninhaber-Registrierung
• Wiederkehrende Zahlung Erstellen
• Webhook-Operationen