Zum Inhalt

Payment Links

Ein Payment Link ist eine einmalig verwendbare URL, die Sie per API erstellen. Wenn Ihr Kunde den Link öffnet, sieht er eine gehostete Checkout-Seite, auf der er via Karte oder Banküberweisung bezahlen kann.

Lebenszyklus

stateDiagram-v2
    [*] --> Unused: createLink
    Unused --> Used: Kunde bezahlt
    Unused --> Cancelled: Kunde bricht ab
    Unused --> Deleted: deleteLink API-Call
    Used --> Refunded: refundPayment
Status Bedeutung
Unused Link erstellt, noch nicht bezahlt
Used Zahlung abgeschlossen
Cancelled Kunde hat abgebrochen (nur wenn cancellable)
Deleted Händler hat den Link per API gelöscht

Bei der Link-Erstellung gibt SecPaid einen pay_link zurück:

https://app.secpaid.com/payment?link_id=MTIzNDU=

Der link_id-Query-Parameter ist die base64-kodierte linktopay_id aus Ihrem Datenbank-Eintrag.

Anfrage-Felder

Feld Typ Pflicht Beschreibung
amount number Ja Zahlungsbetrag in EUR. Muss > 0 sein
recipient_note string Nein Ihre Referenz für diese Zahlung (z.B. Rechnungsnummer, Bestell-ID). Erscheint in Transaktionslisten und Webhooks
callback_url string Nein Browser-Redirect-URL nach Zahlung/Stornierung. Akzeptiert eine volle URL, einen Index in Ihre konfigurierte Liste, oder kommaseparierte URLs
payment_endpoint string Nein Server-zu-Server Webhook-URL(s). Akzeptiert eine URL, einen Index, oder kommasepariert
cancellable boolean Nein Ob Kunde abbrechen kann. Standard: true
bank_transfer string Nein Banküberweisung als Zahlungsmethode aktivieren ("true" / "false")
is_encryption string Nein Verschlüsselte Webhook-Payloads aktivieren ("true" / "false")
encryption_key string Nein Benutzerdefinierter AES-256-CBC-Schlüssel für diesen Link
bank_statement_description string Nein Text auf dem Kontoauszug des Kunden
is_qr_link string Nein Ob dies ein QR-Code-Link ist ("true" / "false")

Antwort-Felder

Bei der Link-Erstellung gibt SecPaid ein vollständiges Link-Objekt zurück:

Feld Typ Beschreibung
id integer Eindeutige Link-ID
pay_link string Die Zahlungs-URL, die Sie an Ihren Kunden senden
qr_img string Sofort verwendbare QR-Code-Bild-URL
amount number Zahlungsbetrag in EUR
status string Bei Erstellung immer "Unused"
is_cancellation string "No" = Kunde kann abbrechen, "Yes" = kann nicht abbrechen
recipient_note string Ihre Referenz-Notiz
callback_url string Konfigurierte Redirect-URL(s)
paymentEndpoint string Konfigurierte Webhook-URL(s)
servicefee string Plattform-Gebühren-Prozentsatz für diesen Link
bank_transfer string Ob Banküberweisung aktiviert ist
is_split_link string "false" für reguläre Links, "true" für Split Links
split_type string "normal" (proportional) oder "absolute"
transaction_type string "Basic" für reguläre Links, "Split" für Split Links
bank_statement_description string Beschreibung auf dem Kontoauszug des Kunden
is_qr_link string Ob QR-Code-Link
payment_config string Zahlungskonfiguration
created_at string Erstellungs-Zeitstempel (UTC)

Stornierbar (Cancellable)

Wert Verhalten
true (Standard) Kunde sieht einen "Abbrechen"-Link im Checkout. Bei Abbruch wird callback_url mit status=cancel aufgerufen
false Keine Abbruch-Option. Kunde muss den Browser-Tab schließen

Standard

Links sind standardmäßig stornierbar. Setzen Sie cancellable: false explizit, wenn Kunden nicht abbrechen können sollen.

QR-Code

Jeder Payment Link generiert automatisch eine QR-Code-Bild-URL (qr_img in der Antwort). Sie können diese in Rechnungen, E-Mails oder POS-Displays einbetten.

Service Fee

Das servicefee-Feld in der Antwort zeigt den Plattform-Gebühren-Prozentsatz, der von dieser Zahlung abgezogen wird. Dies wird auf Konto-Ebene in Ihren Integrations-Einstellungen konfiguriert und kann nicht pro Link geändert werden.

Callback & Benachrichtigung

Nach der Zahlung können zwei Benachrichtigungsmechanismen ausgelöst werden:

  1. callback_url — Browser-Redirect (kundenorientiert)
  2. payment_endpoint — Server-zu-Server-Webhook (Ihr Backend)

Siehe Webhooks & Callbacks für vollständige Details.

Verwandte Endpoints