Dieser Artikel geht davon aus, dass Sie derzeit eine Integration mit unserer alten API haben.
Wenn Sie keine bestehende Integration haben oder unsere aktuelle API nutzen, ist dieser Artikel für Sie nicht relevant. Unsere Dokumentation zu unserer aktuellen API finden Sie hier.
Möglicherweise möchten Sie die Übersicht der Änderungen ansehen, bevor Sie diesen Leitfaden lesen.
Wenn Sie eine Partnerintegration entwickeln möchten, ist dieser Leitfaden für Sie relevant, Sie sollten sich jedoch mit uns in Verbindung setzen, bevor Sie beginnen.
Was mache ich zuerst?
Wenn Sie es nicht bereits getan haben, sollten Sie hier ein Sandbox-Konto erstellen. Sandbox-Konten sind nicht mehr mit Ihrem Live-Konto verknüpft, daher müssen Sie ein separates Sandbox-Konto erstellen, um Ihre Integration mit der neuen API zu entwickeln.
Erstellen Sie dann einen Zugrifsstoken. Sie müssen Ihrem Zugriffstoken einen Namen geben und ihn mit einem Lese-Schreib-Zugriff versehen. Klicken Sie auf „Zugriffstoken erstellen“ und kopieren Sie den Token in die Zwischenablage. Speichern Sie ihn an einem sicheren Ort, da Sie nicht mehr auf diese Seite zugreifen können. Wenn Sie dies dennoch tun müssen, können Sie Ihren Zugriffstoken deaktivieren und einen neuen Zugriffstoken erstellen.
Lesen Sie unseren Leitfaden Erste Schritte und unsere komplette Entwicklerdokumentation, um mit Ihrer neuen Integration zu beginnen. Der Leitfaden und die Dokumentation enthalten Code-Beispiele für all unsere aktuellen Client-Bibliotheken (oder HTTP-Anfragen, wenn wir keine Bibliothek für Ihren Stack haben), und Sie können die Quelle jeder Bibliothek mithilfe der Links in unserer Dokumentation anzeigen.
Anfragen an die neue API stellen
Wenn Sie eine unserer Client-Bibliotheken nutzen, ist dieser Abschnitt für Sie nicht relevant, da die Bibliotheken Entwicklungsanfragen im korrekten Format verarbeiten.
Die grundlegenden URLs für die API sind:
Live | https://api.gocardless.com/ |
Sandbox | https://api-sandbox.gocardless.com/ |
Sie müssen den zuvor erstellten Zugriffstoken in einem Autorisierungsanfrage-Header angeben, wenn Sie Anfragen an die API stellen:
Autorisierung
: Bearer ACCESS_TOKEN_HERE
Darüber hinaus müssen Sie den GoCardless-Version-Header festlegen. Die Version, die zum Zeitpunkt dieses Dokuments verfügbar ist, ist 2015-07-06:
GoCardless-Version
: 2015-07-06
Alle Anfragen und Antworten sind JSON-formatiert und UTF-8-verschlüsselt. Die Angabe des Accept
-Headers ist optional, wird jedoch empfohlen. Der Content-Type-Header muss angegeben werden, wenn Daten (mithilfe POST- und PUT-Endpunkten) an die API gesendet werden. Sie können entweder den Standard JSON MIME Typ (application/json
) oder die JSON-API Variante (application/vnd.api+json
) weitergeben.
Webhooks
Webhooks enthalten jetzt viel mehr Informationen und können an mehrere Endpunkte gesendet werden. Wenn sich der Status einer Ressource ändert, speichern wir ein Event und Events werden in Datenfelder stapelweise verarbeitet und als Webhooks gePOSTet.
Wenn Sie Webhooks verwenden möchten, müssen Sie hier einen Webhook-Endpunkt hinzufügen.In der Sandbox-Umgebung können Sie eine HTTP-URL für Ihre Webhooks verwenden, in der Live-Umgebung muss der Endpunkt jedoch mit HTTPS gesichert werden. Weitere aktuelle Informationen zu Webhooks finden Sie hier.
Wie stelle ich meinen Kunden weiterhin Abrechnungen?
Um Zahlungen für Ihre Kunden zu erstellen, müssen Sie eine Lastschriftmandatsnummer verwenden. Ganz egal, welche Genehmigung Sie in der alten API verwendet haben, Sie benötigen jetzt eine Lastschriftmandatsnummer zur Erstellung von Zahlungen.
Die bisher verwendeten Ressourcen-IDs können in der aktuellen API verwendet werden, sie verweisen jedoch auf etwas andere Ressourcen. So ist eine ID für Vorabgenehmigungen in der alten API jetzt eine ID für ein Lastschriftmandat in der neuen API. Die Mappings sind nachfolgend aufgeführt:
Alte ID | Neue ID |
ID für Vorabgenehmigungen | Lastschriftmandatsnummer |
ID für Dauerauftragsgenehmigungen | ID für Daueraufträge |
ID für ad-hoc-Genehmigungen | Zahlungs-ID |
Abrechnungs-ID | Zahlungs-ID |
Einschränkungen von Lastschriftmandaten
Die alte API verfügte über einmalige Abrechnungen und nicht bearbeitbare Daueraufträge. Daher müssen Kunden, die diese Lastschriftmandate eingerichtet haben, alle neuen Zahlungen oder Daueraufträge genehmigen, die sie im Rahmen ihrer Lastschriftmandate erstellen. Wir bezeichnen dies als „eingeschränkte Lastschriftmandate“.
Sie können keine eingeschränkten Lastschriftmandate über die aktuelle API erstellen, sie existieren jedoch, damit diese alten Genehmigungstypen leicht in Rechnung gestellt werden können, ohne dass Kunden ihre Bankdaten erneut eingeben müssen.
Alter Genehmigungstyp | Lastschriftmandatstyp |
Vorabgenehmigung | Uneingeschränktes Lastschriftmandat |
(einmalige) ad-hoc-Genehmigung | Eingeschränktes Lastschriftmandat |
Dauerauftrag | Eingeschränktes Lastschriftmandat |
Mithilfe eines uneingeschränkten Lastschriftmandats können Sie Zahlungen und Daueraufträge für Kunden ohne weitere Genehmigung erstellen. Wir werden die Kunden jedoch darüber informieren, wenn Sie eine Zahlung oder einen Dauerauftrag erstellt haben, um die Regeln der Lastschriftschema einzuhalten.
Bei einem eingeschränkten Lastschriftmandat bitten wir Kunden per E-Mail um ihre Genehmigung, bevor Zahlungen von ihrem Konto eingezogen werden. Dabei muss der Kunde nur auf einen Link in der E-Mail klicken und keine Zahlungsseiten ausfüllen oder erneut Daten eingeben.
Lastschriftmandate mit Vorabgenehmigungen sind nicht eingeschränkt, der von Ihnen festgelegte Höchstbetrag und das definierte Intervall gelten jedoch immer noch.
Wie richte ich einmalige Zahlungen/Daueraufträge/Vorabgenehmigungen jetzt ein?
Anstatt separate Links für jede Genehmigungsart zu erstellen, müssen Sie jetzt nur noch ein Umleitungskonzept verwenden.
Zunächst erstellen Sie eine Umleitung für Ihre Kunden und leiten Sie an die angegebene Umleitungs-URL weiter, z. B.: https://pay.gocardless.com/flow/RE123.
Der Kunde füllt die neuen und verbesserten GoCardless-Zahlungsseiten aus und gibt Name, E-Mail, Adresse und Bankdaten an.
Beim Einreichen des Formulars speichern wir die Daten an einem sicheren Ort und leiten den Kunden zurück zu ihrer Folge-Umleitungs-URL, die Sie beim Erstellen der Umleitung festlegen.
Danach müssen Sie die Umleitung mit einer einzigen API-Anfrage „abschließen“, die dann Kunde, Kundenbankkonto und Lastschriftmandat erstellt. Dieser Vorgang ähnelt dem Schritt „Ressource bestätigen“ in der alten API.
Mithilfe des neu erstellten Lastschriftmandats können Sie Zahlungen und Daueraufträge für den Kunden erstellen. Sie sollten die Lastschriftmandatsnummer speichern, sodass Sie künftige Zahlungen erstellen und eingehende Webhooks identifizieren können, die mit dem Status des Lastschriftmandats verbunden sind.
Wie wechsle ich?
Wenn Sie mit Ihrer Sandbox-Integration mit der neuen API zufrieden sind, können Sie in wenigen Schritten zur Live-Umgebung wechseln:
- Wir aktualisieren Ihr Konto auf unser neues Dashboard. Sie verlieren Zugriff auf Ihr altes Entwickler-Dashboard, Ihre alte Integration wird jedoch weiter funktionieren. All Ihre vorhandenen Daten sind im neuen Dashboard verfügbar.
- Jetzt befindet sich Ihr Konto auf dem neuen Dashboard und Sie können einen Zugriffstoken erstellen und einen Webhook-Endpunkt für Ihr Live-Konto festlegen.
- Auf Ihrer Seite können Sie stufenweise aus der alten API aussteigen und die neue API verwenden.
- Wenn alles reibungslos funktioniert, können wir Ihren alten Zugriffstoken und Webhook-Endpunkt deaktivieren.
Hinweise:
- Ihr Kontoverlauf ist immer noch verfügbar und Ihre Kunden müssen keine erneuten Genehmigungen erteilen.
- Alle Ressourcen, die Sie über das neue Dashboard oder die API erstellen, sind nicht in Ihrer alten Integration abrufbar, alle in Ihrer alten Integration erstellten Ressourcen können jedoch von der neuen API abgerufen werden.
- Sie müssen sich mit uns in Verbindung setzen, sodass wir Ihr Konto aktualisieren und Ihre alte Integration deaktivieren können (und natürlich stehen wir bei allen Fragen gerne zur Verfügung!).
- Wenn Sie eine alte Partnerintegration haben, sollten Sie sich mit uns in Verbindung setzen, um sicherzustellen, dass dieser Wechsel für Ihre Integration funktioniert.