Zahlungslinks

Zahlungslinks sind wiederverwendbare URLs, über die Kunden eine Bestellung bezahlen können. Im Gegensatz zu Standardbestellungen, die nach einem einzigen fehlgeschlagenen Versuch ablaufen, unterstützen Zahlungslinks mehrere Wiederholungsversuche und sind daher ideal für Rechnungen, E-Mail-basierte Zahlungen und Szenarien, in denen der Kunde möglicherweise nicht sofort bezahlt.

Hauptmerkmale

Wiederverwendbar: Kunden können die Zahlung bis zu 25 Mal wiederholen, wenn vorherige Versuche fehlschlagen.
Langlebig: Die Standard-Ablaufzeit beträgt 30 Tage (konfigurierbar über expiration_period).
Teilbar: Senden Sie den Link per E-Mail, SMS, Chat oder betten Sie ihn auf Ihrer Website ein.

Zahlungslink erstellen

Senden Sie einen POST-Request an /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Die Antwort enthält die payment_url zum Teilen mit dem Kunden und eine eindeutige id zur Nachverfolgung:

Response (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Speichern Sie die id — Sie benötigen sie, um den Status des Zahlungslinks später zu überprüfen.

Erforderliche Felder

Feld	Beschreibung
`merchant_order_id`	Ihre eigene Referenz-ID für den Zahlungslink
`amount`	Betrag in Cent (z. B. 9,95 EUR = `995`)
`currency`	ISO 4217 Währungscode (z. B. `EUR`, `GBP`)

Optionale Felder

Feld	Beschreibung
`description`	Beschreibung, die dem Kunden angezeigt wird
`expiration_period`	ISO 8601 Dauer. Standard ist `P30D` (30 Tage)
`return_url`	URL, zu der der Kunde nach erfolgreicher Zahlung weitergeleitet wird
`failure_url`	URL, zu der der Kunde bei Stornierung, Ablauf oder Fehler weitergeleitet wird
`webhook_url`	URL für Statusänderungsbenachrichtigungen
`customer`	Kundendetails-Objekt (Name, E-Mail usw.)

Wenn Sie sowohl return_url als auch failure_url angeben, werden Kunden zu failure_url weitergeleitet, wenn der Bestellungsstatus cancelled, expired oder error ist. Andernfalls gehen alle Weiterleitungen an return_url.

Zahlungslink abrufen

Senden Sie einen GET-Request an /v1/paymentlinks/{id}/ mit der Zahlungslink-id aus der Erstellungsantwort:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

Die Antwort enthält den aktuellen Status und Verweise auf alle vom Link erstellten Bestellungen, gruppiert nach deren Status:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

In diesem Beispiel hatte der Kunde einen fehlgeschlagenen Versuch (Bestellung 0d79014c... im Status error), bevor er erfolgreich war (Bestellung 3bb663cc... im Status completed). Sie können vollständige Details zu jeder Bestellung über GET /v1/orders/{order_id}/ abrufen.

Zahlungslink-Status

Status	Beschreibung
`new`	Der Link wurde erstellt, aber es wurde noch kein Zahlungsversuch unternommen.
`processing`	Ein Zahlungsversuch ist derzeit in Bearbeitung.
`all_unsuccessful`	Alle bisherigen Zahlungsversuche sind fehlgeschlagen. Der Kunde kann es weiterhin versuchen (bis zu 25 Versuche).
`completed`	Zahlung war erfolgreich. Der Link ist nicht mehr aktiv.
`expired`	Der Link ist abgelaufen, bevor eine erfolgreiche Zahlung erfolgt ist.

Der Status all_unsuccessful ist kein Endstatus. Der Kunde kann weiterhin versuchen zu bezahlen, bis entweder die Zahlung erfolgreich ist, die maximale Anzahl an Versuchen (25) erreicht ist oder der Link abläuft.

Sobald ein Zahlungslink den Status completed oder expired erreicht hat, kann er nicht mehr verwendet werden. Erstellen Sie einen neuen Zahlungslink, wenn der Kunde erneut bezahlen muss.

Beispiel-Workflow

Erstellen Sie einen Zahlungslink über POST /v1/paymentlinks/.
Teilen Sie die zurückgegebene payment_url mit Ihrem Kunden (z. B. per E-Mail, SMS oder Rechnung).
Der Kunde öffnet den Link und schließt die Zahlung ab.
Cost+ sendet einen Webhook an Ihre webhook_url, wenn sich der Status ändert.
Verifizieren Sie den Zahlungslink-Status über GET /v1/paymentlinks/{id}/.
Erfüllen Sie die Bestellung, sobald der Status completed ist.