Anleitungen

Zahlungen und Rechnungen akzeptieren

Im Kern beginnen Zahlungen mit einem ausstehenden Betrag, der von einem Kunden eingezogen werden soll. Es ist möglich, die gesamte Zahlungslogik unabhängig aufzubauen und zu pflegen: Mandate verwalten, diese aktuell halten, Tokens speichern, Zahlungslinks generieren, Zahlungsmethoden nachverfolgen und entscheiden, welche Optionen welchem Kunden angezeigt werden. Dies wird jedoch schnell komplex und schwer skalierbar.

Stattdessen kann diese gesamte Verantwortung an Twikey delegiert werden, indem ausstehende Beträge an den Invoice-Endpoint übermittelt werden. Trotz des Namens ist der Invoice-Endpoint nicht auf traditionelle Rechnungen beschränkt - er verarbeitet jede Art von Zahlung: Abonnementgebühren, Einmalzahlungen, Bußgelder, Spenden oder jeden anderen ausstehenden Betrag. Durch die Übermittlung einer Zahlung an Twikey übernimmt Twikey alles rund um den Zahlungseinzug:

• Anbieten der korrekten Zahlungsmethoden für den Kunden
• Umstellung von Kunden auf automatische Zahlung, wenn ein Mandat möglich ist
• Verwaltung von Mandaten, Tokens und Zahlungslinks
• Abwicklung verschiedener Zahlungsabläufe basierend auf der Situation des Kunden

Zahlungsmethoden und PSP-Konfiguration werden im Twikey-Dashboard verwaltet. Beim Erstellen einer Zahlung ist es nicht erforderlich zu wissen, ob der Kunde ein Mandat/Token hat, welche Zahlungsmethode gilt oder ob ein Mandat/Token signiert werden muss. Das bedeutet, eine einzige Integration deckt alle Zahlungsabläufe ab.

Jeder Zahlungsablauf beginnt mit einem Aufruf des Invoice-Endpoints: POST /creditor/invoice. Bei einer großen Anzahl können diese sogar in einem einzigen Aufruf über den Batch-Insert gesendet werden.

Ab diesem Punkt bestimmt Twikey die geeigneten Aktionen basierend auf dem Kundenkontext, verfügbaren Mandaten/Tokens und der Konfiguration. Die folgenden Abschnitte beschreiben die möglichen Abläufe und wie diese über den Payment-Feed verfolgt und verarbeitet werden können.

Zahlungen und Rechnungen für einen Kunden mit Mandat/Token

Wenn der Kunde bereits ein aktives Mandat/Token hat, ist der Ablauf unkompliziert:

Nach der Erstellung der Zahlung initiiert Twikey automatisch eine Transaktion gemäß den Mandat-/Token-Details. Keine zusätzliche Kundeninteraktion ist erforderlich. Ein Webhook wird gesendet, wenn sich der Zahlungsstatus ändert, woraufhin die Details über den Payment-Feed abgerufen werden können.

Die Zahlungsseite spiegelt ebenfalls diesen Zustand wider. Verfügbare Zahlungsmethoden werden ausgeblendet und der Kunde wird informiert, dass eine automatische Zahlung bereits in Bearbeitung ist und keine weiteren Aktionen erforderlich sind.

Zahlungen und Rechnungen für einen Kunden ohne Mandat/Token

Wenn kein Mandat/Token vorhanden ist, um automatisch eine Transaktion auszulösen, werden dem Kunden die verschiedenen aktivierten Zahlungsmethoden angezeigt. Abhängig davon, welche Zahlungsmethode gewählt wird, unterscheidet sich der Ablauf auf der Twikey-Seite, endet aber immer mit einem Zahlungsevent im Payment-Feed. Sobald der Kunde fertig ist, wird ein Webhook gesendet.

Verfügbare Zahlungsmethoden

Idealerweise unterzeichnet der Kunde ein Mandat/Token für zukünftige Zahlungen. Auf diese Weise werden Zahlungen automatisch ausgeführt, was die Anzahl verspäteter Zahlungen reduziert. Nachdem der Kunde unterzeichnet hat, initiiert Twikey automatisch die Zahlung auf der Bank-/PSP-Seite.

Die Abwicklung von Einmalzahlungen ist immer gleich, unabhängig davon, welcher PSP mit Twikey verbunden ist.

Obwohl nicht als primäre Zahlungsmethode empfohlen, können Überweisungsinformationen auf der Zahlungsseite verfügbar gemacht werden. Eine erfolgreiche Zuordnung erfolgt nur, wenn die Zahlungsreferenz und der Betrag korrekt vom Kunden angegeben werden.

Payment-Feed

Sobald eine Zahlung erstellt wurde, wird Twikey die einzige Quelle der Wahrheit für alles, was mit dieser Zahlung geschieht.

Anstatt einzelne Zahlungen abzufragen, sollte der Payment-Feed konsumiert werden. Dieser Feed ist eventbasiert und stellt einen chronologischen Strom von Events dar, die beschreiben, was mit allen Zahlungen seit der letzten Abfrage passiert ist. Dies umfasst alle Schritte: Wenn eine Zahlung per Lastschrift eingezogen, aber seitdem zurückgebucht wurde, sind sowohl das Payment- als auch das Payment_failure-Event im Feed vorhanden.

Nicht nur alle Zahlungsevents sind verfügbar, sondern es können auch detailliertere Informationen extrahiert werden, falls dies für die Integration erforderlich ist:

• Welche Bank oder welcher PSP (Gateway) für die Zahlung verwendet wurde
• Welches Mandat/Token verwendet wurde
• Ein einheitlicher Fehlercode
• Die genauen vom Gateway empfangenen Codes
• Der nächste automatische Nachverfolgungsschritt, den Twikey ausführen wird
• Wo sich die Zahlung im automatischen Nachverfolgungsprozess befindet

Massenzahlungen und Rechnungen

Anstatt Zahlungen einzeln zu erstellen, können mehrere Zahlungen in einem Stapel eingereicht werden. Massenzahlungen ermöglichen es, mehrere ausstehende Beträge in einem einzigen API-Aufruf einzureichen, anstatt eine Anfrage pro Zahlung zu senden. Dies ist besonders nützlich für batchbasierte Rechnungsstellung oder periodische Exporte. Nach der Einreichung bei POST /creditor/invoice/bulk verarbeitet Twikey den Stapel asynchron. Jede Zahlung wird individuell behandelt und folgt derselben Zahlungslogik und Validierung wie eine reguläre Zahlungsanfrage.

Rechnungsdokumente hosten Bei der Einreichung von Massenzahlungen ist es nicht notwendig, Rechnungs-PDFs hochzuladen.

Stattdessen kann das Rechnungsdokument extern gehostet werden, wobei nur die Dokument-URL in der Bulk-Payload angegeben wird. Während der Bulk-Aufgabe ruft Twikey das Dokument automatisch ab und speichert es, sodass die vollständige PDF nicht im API-Aufruf gesendet werden muss. Das kopierte Dokument wird anschließend konsistent in allen Kommunikations- und Zahlungsabläufen verwendet, die sich auf die Zahlung beziehen.

Einen Bulk-Auftrag verfolgen

Sobald die Verarbeitung abgeschlossen ist, sendet Twikey einen Webhook, der angibt, dass der Batch-Import abgeschlossen ist. Zu diesem Zeitpunkt kann der endgültige Status des Bulk-Auftrags über das Bulk-Status-Endpoint abgerufen werden. Damit kann überprüft werden:

• Ob alle Zahlungen erfolgreich importiert wurden
• Wann das Hosting von Rechnungs-PDFs online eingestellt werden kann

Aktionen auf einer Zahlung oder Rechnung

Sobald eine Zahlung erstellt wurde, gibt es zusätzliche Aktionen, die ausgelöst werden können. Diese Aktionen fallen in zwei klare Kategorien: Kommunikation und Zahlungsaktionen. Alle diese Aktionen verwenden dieselbe Endpoint-Struktur: POST /creditor/invoice/{{id}}/{{action}}

Kommunikationsaktionen

Kommunikationsaktionen werden verwendet, um den Kunden erneut zu kontaktieren und zurück zur Zahlung zu führen.

Abhängig von der Situation stehen folgende Optionen zur Verfügung:

• Eine Erinnerung per E-Mail oder SMS senden
• Einen physischen Brief über einen der Postpartner versenden
• Die Rechnung erneut über Peppol versenden

Unabhängig vom Kanal verlinkt jede Kommunikation immer zurück zur ursprünglichen Zahlungsseite der Rechnung. Dies garantiert, dass:

• Der Kunde immer den aktuellen Status der Rechnung sieht
• Doppelte Zahlungen vermieden werden
• Die Verfügbarkeit von Zahlungsmethoden konsistent bleibt
• Keine neuen Zahlungsanfragen oder Links generiert werden müssen

Zahlungsaktionen Zahlungsaktionen werden typischerweise verwendet, nachdem der erste Einzugsversuch, die Nachverfolgung und die zugehörige Kommunikation nicht zu einer erfolgreichen Zahlung geführt haben. Sie ermöglichen eine Intervention bei einer bestehenden Zahlung, ohne eine neue Zahlungsanfrage zu erstellen. Es gibt zwei mögliche Ansätze:

Eine automatische Zahlung erneut versuchen Wenn der Kunde bereits ein bestehendes Mandat oder Token hat, kann Twikey angewiesen werden, eine neue automatische Zahlung mit diesem Mandat/Token zu versuchen.

Einen Zahlungsplan starten Alternativ kann ein Zahlungsplan gestartet werden. Bei der Erstellung eines Zahlungsplans wird Folgendes erwartet:

• Die Anzahl der Raten
• Welches Mandat oder Token verwendet wird
• Der anfängliche Betrag, der eingezogen wird
• Der Betrag jeder folgenden Rate

Twikey übernimmt dann:

• Die Planung der Raten
• Die Ausführung jeder Zahlung auf dem Mandat oder Token
• Die Berichterstattung über Fortschritt und Ergebnisse über den Payment-Feed

Rechnungspositionen

Rechnungspositionen sind nur erforderlich, wenn Twikey ein PDF- oder UBL-Dokument generieren muss, beispielsweise für die Zustellung über Peppol. Wenn keine Dokumentgenerierung benötigt wird, kann dieser Abschnitt übersprungen werden.

Bei der Bereitstellung von Rechnungspositionen müssen diese als Teil der Rechnungsdaten aufgenommen werden. Twikey wendet die strengen Peppol-Regeln bei der Verarbeitung von Rechnungspositionen an. Dies garantiert, dass generierte UBL-Dokumente gültig sind und erfolgreich zugestellt werden können. Diese Regeln werden auch durchgesetzt, wenn Rechnungen nicht über Peppol versendet werden, was konsistentes Verhalten über alle Integrationen garantiert.

Wenn sich die UBL-Spezifikation in Zukunft ändert, übernimmt Twikey diese Updates intern. Solange die Integration die unten beschriebenen Regeln für Rechnungspositionen befolgt, sind keine Änderungen erforderlich. Für Details zu MwSt und Rundung kann die Supportseite konsultiert werden, die ausführlicher erklärt, wie rechtliche Probleme vermieden werden können.

Gutschriften vs Rückerstattungen

Abhängig vom Ziel muss entweder eine Gutschrift erstellt, eine Rückerstattung auf eine Zahlung durchgeführt oder beides gemacht werden, da das Ausstellen einer Rückerstattung in Twikey anders funktioniert als das Ausstellen einer Gutschrift.

Rückerstattungen Rückerstattungen werden verwendet, wenn Geld an den Kunden zurückgezahlt werden muss. Bei der Erstellung einer Rückerstattung verwendet Twikey automatisch die ursprüngliche Zahlungsmethode und führt die Rückerstattung wenn möglich über dasselbe Mandat, Token oder denselben PSP durch, der für die Zahlung verwendet wurde. Rückerstattungen sind reine Zahlungsoperationen. Sie generieren keine Buchhaltungsdokumente und beeinflussen keine Rechnungssummen oder -status außerhalb der monetären Umkehrung.

Gutschriften Gutschriften werden verwendet, um eine Rechnung zu korrigieren oder zu reduzieren, unabhängig davon, ob direkt Geld zurückfließt. Typische Anwendungsfälle für Gutschriften sind:

• Eine Gutschrift als PDF oder UBL (z.B. für Peppol) generieren und an den Kunden senden
• Den Betrag einer unbezahlten Rechnung reduzieren

Die Erstellung einer Gutschrift verwendet dasselbe Endpoint und dieselben Parameter wie die Erstellung einer Rechnung. Der einzige Unterschied ist, dass der Betrag negativ ist. Eine Gutschrift kann mit einer bestehenden Rechnung verknüpft werden, indem relatedInvoiceNumber im Request-Body angegeben wird. Das bedeutet, dass Gutschriften natürlich in die bestehenden Rechnungs- und Zahlungsabläufe passen, ohne eine separate Integration zu erfordern.

Gutschriftverhalten basierend auf Rechnungsstatus

Abhängig vom Status der verknüpften Rechnung verhält sich Twikey bei der Erstellung einer Gutschrift unterschiedlich.

Gebuchte oder fällige Rechnungen

• Der Gutschriftbetrag wird von der Rechnung abgezogen
• Teilgutschriften reduzieren den verbleibenden zahlbaren Betrag
• Die Gutschrift selbst wird sofort als bezahlt markiert
• Jedes verbleibende Guthaben auf der Rechnung kann weiterhin eingezogen werden
• Wenn die Summe aller verknüpften Gutschriften den gesamten Rechnungsbetrag erreicht, wird die Rechnung als bezahlt markiert

Bezahlte Rechnungen

• Der Gutschriftbetrag wird nicht von der Rechnung abgezogen
• Die Gutschrift verbleibt im gebuchten Status
• Es wird keine Rückerstattung automatisch ausgelöst
• Wenn in diesem Fall Geld zurückgezahlt werden muss, muss eine Rückerstattung separat erstellt werden

Mandate und Tokens

Wie im Abschnitt über Zahlungen beschrieben: Wenn ein Kunde ein Mandat oder Token hat, werden Rechnungen automatisch ohne Kundeninteraktion eingezogen. Kunden können Mandate auch direkt von der Zahlungsseite aus unterzeichnen. Das Unterzeichnen und Verwalten von Mandaten kann jedoch auch direkt implementiert werden, was mehr Kontrolle bietet oder die Integration in bestehende Prozesse ermöglicht. Bei der direkten Arbeit mit Transaktionen wird erwartet, dass das Mandat verwaltet wird.

Ein Mandat ist eine Ermächtigung für Lastschriften (SEPA CORE, SEPA B2B oder BACS), während ein Token gespeicherte Kartendaten für wiederkehrende Zahlungen darstellt. Trotz der rechtlichen und funktionalen Unterschiede zwischen diesen Schemata vereint Twikey sie: Sie werden auf die gleiche Weise erstellt und verwendet. Zahlungsabläufe, Transaktionsabläufe und Mandatsaktionen funktionieren identisch unabhängig vom zugrunde liegenden Typ, wodurch alle Schemata vereinheitlicht und die Integration auf einen einzigen Ansatz vereinfacht wird.

Jedes Mandat oder Token beginnt mit einem von zwei Endpoints: POST /creditor/invite, wobei Twikey die vollständige Unterzeichnungserfahrung übernimmt, oder POST /creditor/sign, wobei der Unterzeichnungsprozess extern gesteuert wird. Sobald erstellt, sind alle Änderungen an Mandaten und Tokens, einschließlich neuer Unterschriften, Änderungen und Kündigungen, über den Mandats-Feed verfügbar.

Das /invite- vs /sign-Endpoint

Es gibt zwei Möglichkeiten, ein Mandat oder Token zu erstellen, jeweils mit einem unterschiedlichen Grad an Kontrolle über die Unterzeichnungserfahrung.

Das invite-Endpoint Das POST /creditor/invite-Endpoint erstellt ein vorbereitetes (nicht unterzeichnetes) Mandat und gibt eine Unterzeichnungs-URL zurück. Wenn der Kunde diese URL besucht, übernimmt Twikey die vollständige Unterzeichnungserfahrung: die Validierung der Kundendaten, die Präsentation der Allgemeinen Geschäftsbedingungen und das Anbieten der auf dem Template konfigurierten Unterzeichnungsmethoden.

Das sign-Endpoint Das POST /creditor/sign-Endpoint umgeht alle Twikey-Bildschirme. Dies ist für Integrationen gedacht, bei denen die Unterzeichnungserfahrung vollständig in die Anwendung des Händlers eingebettet ist. Da die Bildschirme von Twikey nicht angezeigt werden, wird die zu verwendende method zusammen mit methodenspezifischen Daten erwartet. Beispielsweise erfordert eine handschriftliche Unterschrift das Unterschriftsbild, und für eMachtiging wird der BIC benötigt, damit der Bankauswahlbildschirm übersprungen werden kann. Die Allgemeinen Geschäftsbedingungen von Twikey sollten auch in die eigenen Bedingungen des Händlers aufgenommen werden, da die Akzeptanzbildschirme von Twikey dem Kunden nicht angezeigt werden. Daher sind Links, die über das sign-Endpoint generiert werden, dafür vorgesehen, sofort verwendet zu werden, anstatt an den Kunden gesendet zu werden.

Ein bestehendes Mandat importieren Die Verwendung des sign-Endpoints mit method=import ist ein Sonderfall: Es wird davon ausgegangen, dass das Mandat bereits vollständig extern unterzeichnet wurde und einfach in Twikey importiert wird. Dies ist auf jedem Template verfügbar, unabhängig von den konfigurierten Unterzeichnungsmethoden.

Wann welches Endpoint verwenden Das invite-Endpoint ist die einfachste Integration: Twikey übernimmt die Unterzeichnungs-UX, Validierung und Akzeptanz der Bedingungen. Das sign-Endpoint bietet volle Freiheit, die Unterzeichnungserfahrung in einen eigenen Ablauf einzubauen, bringt aber die Verantwortung für die Handhabung methodenspezifischer Daten, das Sammeln von Kundendaten und die Akzeptanz der Bedingungen mit sich.

Signierungsabläufe für Kunden

Unabhängig davon, welches Endpoint verwendet wird, gibt es zwei Muster, wie die Unterzeichnungserfahrung dem Kunden angeboten wird.

Twikey sendet die Einladung Wenn Twikey die Einladung sendet, wird der Unterzeichnungslink per E-Mail direkt an den Kunden zugestellt. Dies eignet sich für Post-Sale-Konvertierungen zu automatischen Zahlungen oder Bulk-Konvertierungskampagnen. Der Kunde erhält die E-Mail, klickt auf den Link und schließt den Unterzeichnungsprozess ab.

Den Kunden weiterleiten Anstatt Twikey die Einladung senden zu lassen, wird die Unterzeichnungs-URL in der API-Antwort zurückgegeben und kann verwendet werden, um den Kunden direkt weiterzuleiten. Dies ist ideal für eingebaute Onboarding-Abläufe in Websites oder wenn die Kommunikation über ein externes System erfolgt.

Signierung über Erstzahlung

In Szenarien wie Checkout-Abläufen, Abonnementaktivierungen oder jeder Situation, in der Onboarding und Einzug gleichzeitig stattfinden, kann die Unterzeichnung eines Mandats mit dem Einzug einer Erstzahlung in einem einzigen Schritt kombiniert werden. Durch Angabe von transactionAmount und transactionMessage bei der Erstellung des Mandats unterzeichnet und bezahlt der Kunde in einem Ablauf. Da die Unterzeichnung über eine Erstzahlung immer an einen tatsächlichen Kauf gekoppelt sein muss, ist die Gültigkeit der resultierenden Unterschrift deutlich stärker. Dies erfordert jedoch eine Unterzeichnungsmethode, die die Initiierung über eine Erstzahlung unterstützt, wobei eine echte Zahlung über einen PSP (der das IBAN oder die Kartendaten erfasst) oder über Zahlungsinitiierung (Twikey-pay-by-bank) erfolgt. Da eine Zahlung beteiligt ist, werden zwei Webhook-Events gesendet: type=payment für die Transaktion und type=contract für das unterzeichnete Mandat.

B2B-Validierung

B2B-SEPA-Lastschriftmandate unterscheiden sich von CORE-Mandaten dadurch, dass sie nicht nur die Unterschrift des Kunden erfordern, sondern auch die Registrierung bei der Bank des Kunden. Wie dies gehandhabt wird, hängt von der Bank ab:

Verbundene Banken Für Banken, mit denen Twikey eine direkte Verbindung hat, ist der gesamte Unterzeichnungs- und Registrierungsprozess digital und automatisiert. Es sind keine manuellen Schritte erforderlich. Der Kunde unterzeichnet das Mandat und die Bankregistrierung wird im Hintergrund abgewickelt.

Nicht verbundene Banken Für Banken ohne direkte Verbindung kann der B2B-Validierungsablauf aktiviert werden. Nachdem der Kunde das Mandat unterzeichnet hat, übernimmt Twikey die Registrierung bei der Bank: Erinnerungen werden gesendet, wenn das Mandat noch nicht aktiviert wurde, und Twikey prüft periodisch, ob die Registrierung abgeschlossen ist. Sobald die Registrierung bestätigt ist, wird das Mandat vollständig unterzeichnet und ein AcceptedBank-Event per Webhook gesendet. Wenn die Registrierung nach den Wiederholungsversuchen nicht bestätigt wird, bleibt das Mandat nicht unterzeichnet.

Das B2B-Validierungsverhalten wird pro Profil im Twikey-Dashboard konfiguriert.

Mandats-Feed

Sobald Mandate oder Tokens erstellt wurden, wird Twikey die einzige Quelle der Wahrheit für alles, was damit geschieht. Anstatt einzelne Mandate abzufragen, sind alle Änderungen über den Mandats-Feed verfügbar. Dieser Mandats-Feed ist statusbasiert: Er gibt den letzten Status jedes Mandats zurück, das seit der letzten Abfrage geändert wurde. Dies umfasst neu unterzeichnete Mandate, Änderungen (wie Adress- oder IBAN-Änderungen) und Kündigungen. Für jedes Mandats-Update bietet der Feed Details wie Unterzeichnerinformationen, die verwendete Unterzeichnungsmethode, Gründe für Änderungen und Kündigungsgründe. Der Feed sollte konsumiert werden, bis keine Updates mehr verbleiben, um sicherzustellen, dass alle Änderungen verarbeitet werden.

Standardmäßig gibt der Mandats-Feed alle verfügbaren Attribute zurück. Um die Antwort auf nur die benötigten Felder zu beschränken, können include-Parameter verwendet werden. Verfügbare Optionen sind: mandate, person, signature, plan, tracker, cancelled_mandate, paidamount und payment.

Jeder Eintrag im Feed entspricht einem von drei Nachrichtentypen:

• Unterzeichnetes Mandat: Der Nachrichtentext beginnt mit Mndt, mit den vollständigen Mandatsdetails.
• Änderung: Der Nachrichtentext beginnt mit dem AmdmntRsn-Objekt mit einem Rsn-Feld, das den Grund der Aktualisierung beschreibt.
• Kündigung: Die Nachricht beginnt mit CxlRsn mit einem Rsn-Feld, das den Kündigungsgrund beschreibt.

Die Statusspalte in der folgenden Tabelle spiegelt die tatsächlichen Mandatsstatus wider, wie sie vom Mandatsdetail-Endpoint zurückgegeben werden.

Zwischenstatus Im Gegensatz zum Payment-Feed, der eventbasiert ist und alle Zwischenevents enthält, spiegelt der Mandats-Feed nur den aktuellen Status wider. Wenn ein Mandat zwischen zwei Feed-Abfragen mehrere Statusänderungen durchlaufen hat, wird nur der endgültige Status zurückgegeben. Um alle Zwischenstatus zu erfassen, kann der Webhook (type=contract) verwendet werden, um sofort benachrichtigt zu werden, wenn ein Update stattfindet. Durch Abrufen des Feeds direkt nach Empfang eines Webhooks kann jeder Status erfasst werden, bevor er sich erneut ändert.

Zurückgegebene Vertragstypen Standardmäßig gibt der Feed CORE- und B2B-Mandate zurück. Um andere Typen wie Kreditkarten-Tokens aufzunehmen, kann der X-TYPES-Header verwendet werden, um anzugeben, welche Typen enthalten sein sollen.

Aktionen auf einem Mandat

Sobald ein Mandat oder Token erstellt wurde, stehen zusätzliche Aktionen über das POST /creditor/mandate/{mndtId}/action-Endpoint zur Verfügung. Diese Aktionen fallen in drei Kategorien.

Kommunikationsaktionen Diese Aktionen werden verwendet, um nicht unterzeichnete Mandate zur Fertigstellung zu führen.

• method = invite: die Unterzeichnungseinladung erneut per E-Mail versenden
• method = reminder: eine Erinnerung an den Kunden senden, das Mandat zu unterzeichnen

Kunden-Selfservice Für unterzeichnete Mandate kann dem Kunden Zugang zur Verwaltung der eigenen Mandatsdaten gewährt werden.

• method = access: stellt einen Link zum Kundenportal für das spezifische Mandat bereit. Über das Portal kann der Kunde das IBAN aktualisieren, änderbare Attribute anpassen und Mandatsdaten verwalten.

B2B-Validierungs-Overrides Für B2B-Mandate kann das auf dem Profil konfigurierte Validierungsverhalten pro Mandat überschrieben werden.

• method = automaticCheck: automatische Validierung für dieses spezifische Mandat einschalten, wodurch der Profilstandard überschrieben wird
• method = manualCheck: automatische Validierung für dieses spezifische Mandat ausschalten, wodurch der Profilstandard überschrieben wird

Mandatslebenszyklus

Mandatsdaten aktualisieren Sobald ein Mandat unterzeichnet ist, können Details wie Adresse, IBAN, Mobilnummer, E-Mail, Firmenname, Sprache und eventuelle auf dem Template definierte benutzerdefinierte Attribute über POST /creditor/mandate/update aktualisiert werden. Aktualisierungen eines Mandats werden im Mandats-Feed widergespiegelt.

Mandate kündigen Mandate können über DELETE /creditor/mandate gekündigt werden. Selbst wenn eine Kündigung außerhalb von Twikey empfangen wird, empfiehlt es sich, diese zurückzukommunizieren, damit alle Systeme synchronisiert bleiben.

Automatisches Aufräumen nicht unterzeichneter Mandate Nicht unterzeichnete Mandate oder Tokens verfallen automatisch nach 12 Monaten, oder nach 6 Monaten, sobald der Unterzeichnungslink geöffnet wurde. Wenn ein neues Mandat auf demselben Profil für denselben Kunden erstellt wird und das neue Mandat unterzeichnet wird, werden ältere nicht unterzeichnete Mandate für diesen Kunden automatisch entfernt, wodurch die Umgebung frei von zurückgebliebenen nicht unterzeichneten Mandaten und Tokens bleibt.

Zahlungslinks

Zahlungslinks sind für Einmalzahlungen ohne Mandat oder Token gedacht und können über POST /creditor/payment/link erstellt werden. Während das Rechnungs-Endpoint als "senden und vergessen"-Implementierung funktioniert, die die Methodenauswahl, Nachverfolgung, Mandatskonvertierung und Kommunikation übernimmt, überlassen Zahlungslinks diese Kontrolle der Integration.

Zahlungslinks leiten den Kunden direkt zum PSP weiter, wobei die Twikey-Zahlungsseite vollständig umgangen wird. Wenn der Zahlungsmethoden-Auswahlbildschirm auf der PSP-Seite ebenfalls übersprungen werden soll, kann dies durch Angabe des method-Parameters im Erstellungsaufruf erfolgen. Dies macht Zahlungslinks zur richtigen Wahl, wenn ein eigener Checkout, eine Landingpage oder ein Kommunikationsablauf bereits existiert und die automatische Orchestrierung des Rechnungs-Endpoints nicht benötigt wird.

Zahlungsabläufe für Kunden

Unabhängig davon, wie der Zahlungslink erstellt wurde, gibt es zwei Muster für die Zustellung des Zahlungslinks an den Kunden.

Twikey sendet die Einladung Wenn eine E-Mail-Adresse angegeben und sendInvite gesetzt ist, stellt Twikey den Zahlungslink direkt an den Kunden zu. Dies eignet sich für eigenständige Zahlungsanfragen, bei denen keine zusätzliche Landingpage oder kein Kommunikationsablauf erforderlich ist.

Den Kunden weiterleiten Anstatt Twikey die Einladung senden zu lassen, wird die Zahlungslink-URL in der API-Antwort zurückgegeben und kann in eigene Abläufe, Kommunikation oder Seiten eingebettet werden. Dies ist ideal für Checkout-Abläufe in Websites oder wenn die Kommunikation über ein externes System erfolgt.

Einen Zahlungslink mit einer bestehenden Zahlung verknüpfen

Ein Zahlungslink kann mit einer oder mehreren bestehenden unbezahlten Transaktionen verknüpft werden, indem txref bei der Erstellung des Links angegeben wird. Sobald der Zahlungslink bezahlt ist, werden alle verknüpften Transaktionen ebenfalls als bezahlt markiert. Dies ist nützlich für die Konsolidierung mehrerer ausstehender Beträge in einer einzigen Zahlungsaktion während einer angepassten Nachverfolgung unbezahlter Transaktionen.

Es ist auch möglich, einen Zahlungslink auf einer bestehenden Rechnung zu erstellen, indem der invoice-Parameter mit der Rechnungsnummer angegeben wird. Dadurch kann die Zahlung für eine bestehende Rechnung direkt über den PSP eingezogen werden, anstatt über die von Twikey gehostete Zahlungsseite, die vom Rechnungs-Endpoint verwendet wird.

Zahlungslink-Feed

Der Zahlungslink-Feed funktioniert nach demselben statusbasierten Modell wie der Mandats-Feed: Jeder Aufruf von GET /creditor/payment/link/feed gibt Einträge zurück, die sich seit der letzten Abfrage geändert haben. Jeder Eintrag repräsentiert den aktuellen Status eines Zahlungslinks, nicht ein einzelnes Event.

Standardmäßig werden nur bezahlte Updates zurückgegeben. Durch Angabe von all=true werden alle Statusänderungen aufgenommen. Zusätzliche Details können durch Hinzufügen von include-Parametern aufgenommen werden: customer, meta, time und refunds. Diese werden standardmäßig nicht aufgenommen, um die Antwort kompakt zu halten.

Webhooks für Zahlungslinks validieren

Für Checkout-Integrationen ist es wichtig zu verifizieren, dass ein Webhook tatsächlich von Twikey stammt. Die Validierung des Webhooks kann durch Validierung des x-signature-Headers erfolgen. Dies ist derselbe Validierungsmechanismus, der für alle Twikey-Webhooks verwendet wird. Siehe die Webhook-Referenz für vollständige Details.

Einen Zahlungslink zurückerstatten

Ein bezahlter Zahlungslink kann vollständig oder teilweise über POST /creditor/payment/link/{id}/refund erstattet werden. Die Unterstützung für Rückerstattungen hängt vom PSP ab, der im Twikey-Portal aktiviert ist. Der Rückerstattungsstatus wird im Zahlungslink-Feed widergespiegelt, wenn der entsprechende Include-Parameter ebenfalls hinzugefügt wurde.

Transaktionen

Im Gegensatz zum Zahlungsablauf, bei dem Rechnungen automatisch verwaltet und eingezogen werden, arbeiten Transaktionen direkt auf Mandaten oder Tokens. Eine Transaktion wird immer auf einem spezifischen Mandat erstellt, nicht auf einem Kunden. Dadurch wird die Zuordnung von Transaktionen zum richtigen Mandat oder Token von der Integration übernommen, nicht von Twikey.

Wie bei Mandaten und Zahlungslinks bietet die direkte Arbeit mit Transaktionen mehr Kontrolle über den Einzugsprozess, bringt aber auch mehr Verantwortung bei der korrekten Verwaltung des Ablaufs mit sich.

Transaktionen werden über POST /creditor/transaction erstellt, unter Angabe der Mandatsreferenz, des Betrags und einer Nachricht (die auf dem Kontoauszug des Kunden erscheint). Twikey sammelt ausstehende Transaktionen in Batches und reicht sie bei der Bank oder dem PSP zur Verarbeitung ein. Sobald Feedback empfangen wurde, wird ein type=payment-Webhook gesendet und die Ergebnisse können über den Transaktions-Feed abgerufen werden. Wenn eine Transaktion fehlschlägt, startet der konfigurierte Mahnprozess automatisch.

Transaktions-Feed

Der Transaktions-Feed funktioniert nach demselben statusbasierten Modell wie der Mandats-Feed: Jeder Aufruf von GET /creditor/transaction gibt den aktuellen Status jeder Transaktion zurück, die sich seit der letzten Abfrage geändert hat. Jeder Aufruf verschiebt die Position, daher sollte der Feed konsumiert werden, bis er leer ist. Um alle Zwischenstatus zu erfassen, kann der Zahlungs-Webhook (type=payment) verwendet werden, um eine Feed-Abfrage auszulösen, sobald eine Änderung eintritt.

Das final-Flag Jeder Eintrag enthält auch ein final-Flag:

• final=true zeigt an, dass keine automatischen Aktionen mehr auf dieser Transaktion ausgeführt werden. Dies gilt für Transaktionen, die bezahlt und abgewickelt sind, oder bei denen alle automatischen Nachverfolgungsschritte nach einem Fehlschlag ausgeschöpft wurden.
• final=false zeigt an, dass Twikey noch automatische Nachverfolgung durchführt und weitere Statusänderungen erwartet werden.

Hinweis: Eine PAID + final=true Transaktion kann trotzdem zu einem späteren Zeitpunkt von der Bank zurückgebucht werden (z.B. ein Chargeback oder Reversal). In der Praxis kommt eine Lastschrifttransaktion fast immer zuerst als PAID + final=true zurück, da Banken so über Lastschriften kommunizieren: Der gesamte Batch wird als bezahlt markiert, und an den folgenden Tagen kommuniziert die Bank über einzelne unbezahlte Transaktionen.

Automatische Nachverfolgung Wenn eine Transaktion fehlschlägt, führt Twikey automatische Nachverfolgungsschritte durch, wie das erneute Anbieten der Zahlung, das Senden von Benachrichtigungen an den Kunden und das Vorschlagen alternativer Zahlungsmethoden. Der Feed spiegelt das Ergebnis dieser Schritte wider, sobald sie abgeschlossen sind. Eine Transaktion kann von ERROR zurück zu PAID wechseln, wenn ein Nachverfolgungsschritt erfolgreich ist, oder mit final=true im Status ERROR verbleiben, sobald alle Schritte ausgeschöpft sind.

Include-Parameter Standardmäßig gibt der Feed eine kompakte Antwort zurück. Zusätzliche Details können durch Hinzufügen von include-Parametern abgerufen werden:

• collection - die Collection-Batch-ID
• lastupdate - Zeitstempel der letzten Statusänderung
• action - alle automatischen Nachverfolgungsaktionen, die bei einer fehlgeschlagenen Transaktion durchgeführt wurden
• action_payment - wie action, enthält aber nur die Aktionen, die seit dem letzten Feed-Aufruf durchgeführt wurden
• link - ein Zahlungslink für den Kunden
• stage - das aktuelle Stadium der Transaktion
• seq - die Sequenznummer innerhalb des Feeds

Massentransaktionen

Anstatt Transaktionen einzeln zu erstellen, können bis zu 5.000 Transaktionen in einer einzigen Anfrage über POST /creditor/transaction/bulk eingereicht werden. Nach der Einreichung verarbeitet Twikey den Batch asynchron. Ein type=bulk-Webhook wird gesendet, sobald die Verarbeitung abgeschlossen ist, und der Batch-Status kann mit der zurückgegebenen Batch-ID überprüft werden.

Eine Transaktion zurückerstatten

Eine Rückerstattung kann auf jeder bezahlten Transaktion über POST /creditor/transaction/{id}/refund initiiert werden. Wie die Rückerstattung verarbeitet wird, hängt davon ab, wie die ursprüngliche Transaktion eingezogen wurde.

Für Lastschrifttransaktionen wird die Rückerstattung einer Credit-Transfer-Datei hinzugefügt. Diese Datei muss heruntergeladen, bei der Bank hochgeladen und unterzeichnet werden, bevor die Rückerstattung ausgeführt wird. Der Betrag wird standardmäßig auf das IBAN des ursprünglichen Mandats zurückerstattet.

Für Transaktionen, die über einen PSP eingezogen wurden, sei es eine Lastschrift über einen PSP oder wiederkehrende Kreditkarte, leitet Twikey die Rückerstattung direkt an den PSP zur Verarbeitung weiter.

Weitere Anleitungen

Die folgenden Anleitungen werden vorbereitet:

• Abonnements
• Überweisungen
• Reservierungen
• Kundenidentifikation
• IBAN-Namensabgleich
• Inkasso

In der Zwischenzeit behandelt die API-Referenz alle verfügbaren Endpoints.