Bei einem Upgrade Ihrer alten Integration auf die neue API müssen Sie Ihren Webhook-Handler anpassen, um neue Arten von Webhooks handhaben zu können, die wir Ihnen senden.
Darüber hinaus haben sich einige Aktionen geändert, die wir im alten System gesendet haben. Nachfolgend sehen Sie eine Übersicht dieser Änderungen sowie neue Aktionen, die Sie möglicherweise berücksichtigen möchten:
Genehmigungen > Lastschriftmandate
Genehmigungen sind jetzt Lastschriftmandate. Lastschriftmandate sind sehr viel flexibler. Sie können einmalige Zahlungen oder Daueraufträge im Rahmen desselben Lastschriftmandats erstellen. Darüber hinaus können Lastschriftmandate über mehrere Daueraufträge verfügen. Kunden müssen keine Zahlungen oder Daueraufträge im Rahmen eines Lastschriftmandats neu genehmigen.
| Alte API – Aktionen für Vorabgenehmigungen/Daueraufträge | Neue API – Aktionen für Lastschriftmandate | Beschreibung der Aktion |
| storniert | storniert | Das Lastschriftmandat wurde entweder vom Kunden über seine Bank oder diese API oder automatisch storniert, wenn sein Bankkonto geschlossen wird. |
| abgelaufen | abgelaufen | In den letzten 13 Monaten wurden keine Zahlungseinzüge im Rahmen des Lastschriftmandats vorgenommen. Dementsprechend ist das Lastschriftmandat abgelaufen und es können keine weiteren Zahlungseinzüge vorgenommen werden. Wenn Sie von diesem Kunden weiterhin Zahlungen einziehen möchten, sollten Die seine Genehmigung einholen und den „reinstate“-Endpunkt verwenden. |
| Neue API – zusätzliche Aktionen für Lastschriftmandate | Beschreibung der Aktion |
| erstellt | Das Lastschriftmandat wurde erstellt. |
| customer_approval_granted | Das Lastschriftmandat erfordert weitere Genehmigungen vom Kunden (z. B. Genehmigung durch einen zweiten Unterzeichner) und diese Genehmigung wurde erteilt. |
| customer_approval_skipped | Ursprünglich wurde eine weitere Genehmigung vom Kunden verlangt (z. B. Genehmigung durch einen zweiten Unterzeichner), diese Anforderung wurde jedoch übersprungen (beispielsweise weil das Lastschriftmandat irrtümlicherweise mit der Anforderung nach einer zweiten Unterschrift versehen wurde). |
| aktiv | Das Lastschriftmandat wurde erfolgreich von der Bank des Kunden eingerichtet. |
| fehlgeschlagen | Das Lastschriftmandat konnte nicht eingerichtet werden, weil das angegebene Bankkonto keine Lastschriftzahlungen akzeptiert oder geschlossen wurde. |
| übertragen | Das Lastschriftmandat wurde an ein anderes Bankkonto übertragen. Das Event verfügt über links[previous_customer_bank_account] und links[new_customer_bank_account], und das Lastschriftmandat wurde möglicherweise erneut eingereicht, je nachdem wie die Banken den Übertrag gehandhabt haben. |
| eingereicht | Das Lastschriftmandat wurde bei den Banken eingereicht und sollte in einigen Tagen aktiv werden, sofern die Bank die Anfrage nicht ablehnt. |
| resubmission_requested | Eine Aufforderung zur erneuten Einreichung eines Lastschriftmandats wurde vom „reinstate“-Endpunkt des Lastschriftmandats erstellt. |
| wieder in Kraft gesetzt | Das Lastschriftmandat ist wieder aktiv, nachdem es storniert oder abgelaufen war. Möglicherweise möchte die Bank eine gesendete Stornierungs- oder Ablaufbenachrichtigung zurücknehmen oder das Lastschriftmandat wurde über den „reinstate“-Endpunkt erfolgreich wieder in Kraft gesetzt. |
| ersetzt | Das Lastschriftmandat wurde storniert und durch ein neues Lastschriftmandat ersetzt (beispielsweise weil der Gläubiger eine neue Service User Number hat). Das Event verfügt über links[new_mandate] mit der ID des neuen Lastschriftmandats. |
Abrechnungen > Zahlungen
Mit unserer alten API konnten Sie einmalige Abrechnungen oder eine Reihe von einmaligen Abrechnungen mit einer Vorabgenehmigung erstellen. Abrechnungen heißen jetzt Zahlungen und eine Zahlung kann entweder als einmalige Zahlung oder als Teil eines Dauerauftrags erstellt werden.
| Alte API – Aktionen für Abrechnung | Neue API – Atkionen für Zahlungen | Beschreibung der Aktion |
| erstellt | erstellt | Die Zahlung wurde erstellt. |
| bezahlt | bestätigt | Die Zahlung wurde vom Bankkonto des Kunden eingezogen und wird jetzt von GoCardless treuhänderisch verwahrt. Der Einzug kann bis zu fünf Bankgeschäftstage dauern. Die Gelder werden dann für kurze Zeit treuhänderisch verwahrt und dann ausgezahlt (paid_out). |
| zurückgezogen | paid_out | Die Zahlung hat GoCardless verlassen und wurde an das Bankkonto des Gläubigers gesendet. |
| fehlgeschlagen | fehlgeschlagen | Die Zahlung konnte nicht eingezogen werden, üblicherweise weil der Kunde keine ausreichenden Gelder zur Verfügung hat. GoCardless wiederholt die Zahlung nicht automatisch. |
| storniert | storniert | Die Zahlung wurde storniert. |
| zurückerstattet | (als Erstattungsobjekt gesendet) ** | |
| rückbelastet | charged_back | Der Kunde hat seine Bank um eine Rückerstattung der Zahlung im Rahmen der Lastschriftgarantie gebeten. Diese Zahlung wurde nun an den Kunden zurückgegeben. |
| wiederholt | resubmission_requested | Eine Anfrage zur erneuten Einreichung der Zahlung wurde vom „retry“-Endpunkt der Zahlung gestellt. |
| Neue API - Zusätzliche Aktionen für Zahlungen | Beschreibung der Aktion |
| eingereicht | Die Zahlung wurde bei den Banken eingereicht. Es wird einige Tage dauern, bis Zahlungen eingezogen werden oder fehlschlagen. |
| late_failure_settled | Die Zahlung war ein verspäteter Fehler, der bereits ausgezahlt und von einer Auszahlung abgezogen wurde. |
| chargeback_cancelled | Die Bank des Kunden hat die Anfrage nach einer Rücklastschrift storniert. Dies geschieht fast ausschließlich auf Anfrage des Kunden. |
| chargeback_settled | Die Zahlung wurde zurückgegeben, nachdem sie zuvor ausgezahlt wurde, und wurde von einer Auszahlung abgezogen. |
** Erstattungen werden jetzt als eigene Ressource dargestellt. Wenn eine Zahlung zurückerstattet wird, bleibt der Status der Zahlungsressource auf „bestätigt“ und eine Rückerstattungsressource wird getrennt von der Zahlung erstellt.
| Neue API – Aktionen für Rückerstattungen | Beschreibung der Aktion |
| erstellt |
Eine Rückerstattung wurde erstellt. Die details[cause] ist payment_refunded und die details[origin] lautet api. |
| bezahlt | Die Erstattung wurde an Ihren Kunden bezahlt. Die details[cause] ist refund_paid und die details[origin] lautet gocardless. |
| verrechnete Erstattung | Die Erstattung wurde von einer Auszahlung abgezogen. Die details[cause] ist refund_settled und die details[origin] lautet gocardless. |
Daueraufträge werden jetzt im Rahmen eines Lastschriftmandats erstellt. Sie erhalten folgende Webhook-Aktionen:
| Neue API – Aktionen für Daueraufträge | Beschreibung der Aktion |
| erstellt | Der Dauerauftrag wurde erstellt. |
| customer_approval_granted | Für den Dauerauftrag ist eine zusätzliche Genehmigung des Kunden erforderlich, bevor er aktiv werden kann, und diese Genehmigung wurde gewährt. |
| customer_approval_denied | Für den Dauerauftrag ist eine zusätzliche Genehmigung des Kunden erforderlich, bevor er aktiv werden kann, und diese Genehmigung wurde abgelehnt. |
| payment_created | Dieser Dauerauftrag hat eine Zahlung erstellt. |
| storniert | Dieser Dauerauftrag wurde storniert. Es werden keine weiteren Zahlungen erstellt. |
| beendet | Dieser Dauerauftrag ist zu Ende. Es werden keine weiteren Zahlungen erstellt. |
Auszahlungen
Mit unserer neuen API können Sie Auszahlungen, die Sie von GoCardless erhalten, immer noch abfragen. Darüber hinaus haben wir einige Schritte hinzugefügt, damit Sie Auszahlungen mit Events abgleichen können, d. h. Sie erhalten eine Liste der Zahlungen im Rahmen einer bestimmten Auszahlung über die API.
| Neue API – Aktionen für Auszahlungen | Beschreibung der Aktion |
| bezahlt | GoCardless hat die Auszahlung an das Bankkonto des Gläubigers überwiesen. Die details[cause] ist immer payout_paid und die details[origin] lautet gocardless. |
Webhook-Format
Unsere alte API hat Webhooks über den Status einer Abrechnung, einer Vorabgenehmigung oder eines Dauerauftrags versendet. Unsere neue API versendet Webhooks mit viel mehr Informationen und kann an mehrere Endpunkte gesendet werden. Wenn eine Ressource ihren Status ändert, speichern wir ein Event und Events werden zu Feldern zusammengefasst und als Webhooks gePOSTet.
Beispiel für einen alten Webhook für eine Vorabgenehmigung:
{
"payload": {
"resource_type": "pre_authorization",
"action": "cancelled",
"pre_authorizations": [{
"id": "AKJ398H8KBOOO3",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOO3"
}, {
"id": "AKJ398H8KBOOOA",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOOA"
}],
"signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
}
}
Beispiel für einen Webhook für ein Lastschriftmandat in der neuen API:
{
"events": [
{
"id": "EVTESTWKH4MPNG",
"created_at": "2017-04-25T11:20:47.542Z",
"resource_type": "mandates",
"action": "cancelled",
"links": {
"mandate": "MD123"
},
"details": {
"origin": "api",
"cause": "mandate_cancelled",
"description": "The mandate was cancelled at your request."
},
"metadata": {}
}
]
}
In der Entwicklerregisterkarte Ihres neuen Sandbox- oder Live-Dashboards finden Sie außerdem ein nützliches Tool zum Testen dieser neuen Webhooks. Klicken Sie dazu im Entwicklerbereich auf „Test-Webhook senden“, um einen beliebigen Webhook zu versenden, den wir an Ihren Webhook-Endpunkt senden könnten.
