Leitfaden zur Verwendung von Daueraufträgen über die API

Daueraufträge ermöglichen die Erstellung von Zahlungen nach einem Zeitplan. In diesem Leitfaden werden die verfügbaren Funktionen sowie die optimale Implementierung über die API erklärt.

 

Erstellen eines Dauerauftrags

Zum Erstellen eines Dauerauftrags für einen Kunden sind die folgenden Felder erforderlich:

amount - Der Betrag in Pence (GBP), Cent (AUD/EUR), Öre (SEK) oder Øre (DKK).

currency -  Der Währungscode nach ISO 4217. Zurzeit werden GBP, EUR, SEK, AUD und DKK unterstützt.

interval_unit - Der Zeitraum zwischen den Tagen, an denen der Kunde belastet wird. Kann weekly, monthly oder yearly sein.

links[mandate] - Das Kennzeichen des Lastschriftmandats des Kunden, unter dem der Dauerauftrag Zahlungen erstellt.

 

Neben diesen Feldern können die folgenden optionalen Parameters gesendet werden:

name - Optionale Bezeichnung für den Dauerauftrag, der außerdem die Beschreibung der einzelnen Zahlungen darstellt.

interval - Die Anzahl der „interval_units“ zwischen den einzelnen Belastungsdaten. Dabei muss mindestens eine Belastung pro Jahr erfolgen. Bei fehlender Angabe wird standardmäßig 1 eingetragen.

count - Die Gesamtzahl der Zahlungen, die im Rahmen des Dauerauftrags eingezogen werden.

day_of_month - Der Tag des Monats (1–28), an dem Ihr Kunde belastet werden soll. Sie können auch -1 eintragen, um den letzten Tag des Monats anzugeben.

month - Der Name des Monats, in dem der Kunde belastet wird.

start_date - Das Datum, an dem die erste Zahlung belastet werden soll. Dieses Datum muss innerhalb eines Jahres nach Erstellung des Dauerauftrags und am oder nach dem next_possible_charge_date des Lastschriftmandats liegen. Wenn dieser Parameter nicht angegeben ist, wird die erste Zahlung so früh wie möglich belastet.

payment_reference - Dieser Parameter ist nur für Pro-Konten verfügbar. Ein optionaler Verwendungszweck, der für alle Zahlungen festgelegt und im Kontoauszug Ihres Kunden angegeben wird.

Angeben des Zahlungsintervalls

Beim Angeben des Zahlungsintervalls gelten folgende Regeln:

• Die erste Zahlung muss innerhalb eines Jahres belastet werden.
• Wenn weder month noch day_of_month vorhanden sind, wird der Dauerauftrag ab dem  start_date gemäß der interval_unit wiederholt.
• Wenn month oder day_of_month angegeben ist, werden die Wiederholungsregeln ab dem start_date angewendet und es werden folgende Prüfungen durchgeführt:

interval_unit	month	day_of_month
yearly	optional (erforderlich, wenn day_of_month angegeben ist)	optional (erforderlich, wenn month angegeben ist)
monthly	ungültig	erforderlich
weekly	ungültig	ungültig

Beispiele:

interval_unit	interval	month	day_of_month	Gültig?
yearly	1	january	-1	gültig
yearly	1	march		ungültig - es fehlt day_of_month
monthly	6		12	gültig
monthly	6	august	12	ungültig - month muss leer sein
weekly	2			gültig
weekly	2	october	10	ungültig - month und day_of_month müssen leer sein

 

Einmalige Zahlungen

Es gibt Situationen, in denen Sie zusätzlich zum Dauerauftrag eine einmalige Gebühr einziehen möchten, z. B. eine Einrichtungsgebühr.

Hierfür können Sie einfach bei der Erstellung des Dauerauftrags eine Anforderung zum Erstellen einer Einzelzahlung senden.

 

Ändern eines bestehenden Dauerauftrags

Wenn Sie den Betrag eines Dauerauftrags ändern möchten, beispielsweise um für eine bestimmte Anzahl von Monaten eine verminderte Rate einzuziehen, können Sie den Endpunkt „Dauerauftrag aktualisieren“ verwenden, wie hier gezeigt.

Um sicherzustellen, dass der Betrag zum richtigen Zeitpunkt aktualisiert wird, müssen Sie möglicherweise die Anzahl der vom Dauerauftrag erzeugten Zahlungen mithilfe von Webhooks oder des Endpunkts „Events“ verfolgen und speichern. 

Das Belastungsdatum eines Dauerauftrags kann leider nicht aktualisiert werden. Sie müssen hierfür den vorhandenen Dauerauftrag stornieren und einen neuen Dauerauftrag mit den aktualisierten Belastungsdaten erstellen.

 

Behandlung von Events, die mit Daueraufträgen zusammenhängen

Wenn Sie Webhooks oder den Endpunkt „Events“ zur Aktualisierung Ihres eigenen Systems verwenden, dann müssen Sie sich über die folgenden Events im Zusammenhang mit Daueraufträgen im Klaren sein.

Wenn eine Zahlung von einem Dauerauftrag erstellt wird, erhalten Sie zwei Webhooks, die dies angeben. Einer weist den ResourceType „payments“ auf, der andere „subscriptions“:

Wenn Sie in Ihrem System keine Informationen speichern, können Sie mit den folgenden API-Aufrufen zu dem Dauerauftrag zurückverlinken, der mit der Zahlung verbunden ist:

Senden Sie anhand des Zahlungskennzeichens eine Anforderung an den Endpunkt „Payments“.

Suchen Sie in der Antwort das Feld links[subscription], das das Dauerauftragskennzeichen des entsprechenden Dauerauftrags enthält.

Sie können die auf den Dauerauftrag bezogenen Informationen dann finden, indem Sie anhand des Dauerauftragskennzeichens eine Anforderung an den Endpunkt „Subscriptions“ senden.

 

Alternativen zu Daueraufträgen

Daueraufträge sind nicht für jeden Integrator die perfekte Lösung. Wenn Sie zusätzliche Funktionen benötigen, könnte sich die Implementierung Ihrer eigenen Dauerauftragslogik mithilfe des Zahlungsendpunkts anbieten.