Wie funktioniert die Kommunikation zwischen collana pay, ERP, Shop und PSP?

  • Aktualisiert

collana pay arbeitet als Middleware zwischen anbindenden Systemen (Webshop, ERP) und Payment Service Providern (PSPs). Es bietet eine einheitliche Schnittstelle, über die verschiedene PSPs und Zahlarten angebunden werden können, unabhängig davon, welches System die Zahlungsprozesse anstößt.

Das folgende Schaubild zeigt beispielhaft die Kommunikation zwischen collana pay und den angebunden Systemen. Dabei geben die collana pay APIs synchron immer nur Schlüsselwerte zurück, während die eigentliche Antwort asynchron erfolgt.

Beteiligte Systeme

System Rolle
Webshop Startet den Zahlungsprozess im Checkout. Erstellt Transaktionen, leitet den Kunden zur Zahlungseingabe weiter und reagiert auf Notifications von collana pay.
ERP-System (z. B. Business Central) Nimmt bei der Import-Anbindung einen ohne collana pay begonnenen Zahlungsprozess auf und führt diesen weiter. Bei der direkten Anbindung übernimmt das ERP nach der Shop-Zahlung die weitere Verarbeitung. Zusätzlich können Zahlungen direkt aus dem ERP gestartet werden (z. B. via Pay By Link). In allen Fällen stößt das ERP Captures, Refunds und Voids an und verarbeitet die zugehörigen Notifications.
collana pay Zentrale Middleware. Nimmt Anfragen entgegen, kommuniziert mit dem PSP und sendet die Ergebnisse als asynchrone Notifications an das anbindende System zurück.
Payment Service Provider (PSP) Führt die eigentliche Zahlungsverarbeitung durch (Reservierung, Capture, Refund). Wird ausschließlich von collana pay angesprochen — das anbindende System kommuniziert nie direkt mit dem PSP.

Asynchrone Kommunikation als Kernprinzip

Die gesamte Kommunikation zwischen collana pay und anbindenden Systemen basiert auf dem Prinzip der Asynchronität. Dieses Prinzip gilt unabhängig vom anbindenden System.

Der Ablauf ist immer gleich:

  1. Das anbindende System sendet einen Request an die collana pay API (z. B. Create, Prepare, Reserve, Capture).
  2. collana pay antwortet synchron nur mit Schlüsselwerten: transactionId und interactionId.
  3. collana pay verarbeitet die Anfrage und kommuniziert mit dem PSP.
  4. Das Ergebnis wird als Notification (Callback) an eine vom anbindenden System hinterlegte URL gesendet.
Das anbindende System muss in seinem Ablauf immer auf die Notification warten und abhängig vom darin enthaltenen Status reagieren. Die synchrone Antwort auf den API-Request bestätigt lediglich die Annahme der Anfrage, nicht das Ergebnis.

Notification-Status und erwartete Aktionen

Jede Notification enthält einen Status, der die nächste Aktion des anbindenden Systems bestimmt. Die folgende Tabelle zeigt die möglichen Status und die typischen Reaktionen:

Status Bedeutung Erwartete Aktion des anbindenden Systems
Success Die Interaktion wurde erfolgreich abgeschlossen. Mit dem nächsten Prozessschritt fortfahren (z. B. nach erfolgreicher Reservation den Capture anstoßen).
Fail Die Interaktion ist fehlgeschlagen. Fehlerbehandlung durchführen. Je nach Kontext: Zahlung abbrechen, Nutzer informieren oder alternativen Prozess starten.
Pending Die Interaktion ist noch nicht abgeschlossen und erfordert eine weitere Aktion. Abhängig vom mitgelieferten Typ reagieren, z. B. den Kunden zu einer RedirectUri weiterleiten, ein iFrame mit einer EmbedmentUri anzeigen oder auf eine weitere Notification warten.

Bei Notifications mit dem Status Pending wird ein zusätzlicher Typ mitgeliefert, der die erwartete Aktion spezifiziert:

Typ Aktion
RedirectUri Kunde zur angegebenen URL weiterleiten
EmbedmentUri URL in einem iFrame anzeigen
ScriptSrcUri / ScriptTagId JavaScript einbinden und ausführen
None Auf weitere Notification warten

Detaillierte Best Practices zum Umgang mit Notifications, einschließlich wichtiger Felder, Idempotenz und Fehlerbehandlung finden sich im Artikel zum Notification Handling.

Der allgemeine Zahlungsprozess

Der Zahlungsprozess in collana pay besteht aus mehreren aufeinanderfolgenden Interaktionen. Jede Interaktion folgt dem oben beschriebenen asynchronen Muster: Request → synchrone Bestätigung → Notification.

Prozessschritte im Überblick

Schritt Interaktion Beschreibung Typisch ausgelöst durch
1 Create Erstellt eine neue Transaktion in collana pay. Die daraus resultierende transactionId ist die übergreifende Kennung für alle weiteren Interaktionen. Webshop oder ERP
2 Prepare Bereitet die Zahlung vor. collana pay erstellt die Transaktion beim PSP. Je nach PSP und Zahlart kann eine Weiterleitung oder ein iFrame für die Eingabe von Zahlungsdaten erforderlich sein. Webshop oder ERP
3 Reserve Reserviert den Zahlbetrag beim PSP. Der Betrag wird auf dem Zahlungsmittel des Kunden geblockt, aber noch nicht eingezogen. Bei einigen Zahlungsarten/PSPs findet die Kundeninteraktion (Weiterleitung, Zahlungsdateneingabe) erst in diesem Schritt statt. Webshop oder ERP
4 Capture Zieht den reservierten Betrag ein. Dies geschieht in der Regel nach dem Warenversand oder der Leistungserbringung. Auch Teilcaptures sind möglich. ERP (oder Webshop)
5 Refund Erstattet einen bereits eingezogenen Betrag (vollständig oder als Teilrefund). ERP (oder Webshop)
6 Void Storniert eine offene Reservierung, bevor ein Capture erfolgt ist. ERP (oder Webshop)
Die Kundeninteraktion (Weiterleitung zum PSP, Eingabe der Zahlungsdaten) findet üblicherweise im Prepare-Schritt statt. Bei einigen Zahlungsarten und PSPs kann diese jedoch auch erst im Reserve-Schritt erfolgen. Das anbindende System sollte daher in beiden Schritten auf Notifications mit Status Pending und entsprechenden Weiterleitungs- oder Einbettungstypen vorbereitet sein.

Gesamtdurchlauf: Shop und ERP im Zusammenspiel

Im typischen Gesamtdurchlauf teilen sich Webshop und ERP-System die Prozessschritte:

Phase 1: Zahlungsabwicklung im Shop (Checkout)

  1. Der Webshop sendet einen Create-Request → collana pay legt die Transaktion an → Notification mit Status Success.
  2. Der Webshop sendet einen Prepare-Request → collana pay bereitet die Zahlung beim PSP vor → Notification mit Status Pending (Weiterleitung zur Zahlungseingabe) → nach Eingabe: Notification mit Status Success.
  3. Der Webshop sendet einen Reserve-Request → collana pay reserviert den Betrag beim PSP → Notification mit Status Success.

Der Kunde hat den Checkout abgeschlossen. Der Webshop übermittelt die Bestellung (inkl. transactionId) an das ERP-System.

Phase 2: Zahlungsverarbeitung im ERP

  1. Das ERP-System fragt den Transaktionsstatus bei collana pay ab (über die transactionId).
  2. Nach Warenversand stößt das ERP-System einen Capture-Request an → collana pay zieht den Betrag beim PSP ein → Notification mit Status Success.
  3. Bei Retouren oder Stornierungen stößt das ERP-System einen Refund- oder Void-Request an → collana pay verarbeitet die Erstattung/Stornierung beim PSP → Notification mit Status Success.
Die Aufteilung zwischen Shop und ERP ist flexibel. Bei der Import-Anbindung nimmt das ERP-System einen ohne collana pay begonnenen Zahlungsprozess auf und führt diesen ab dem Import weiter. Bei der direkten Anbindung kann auch der Webshop allein alle Schritte durchführen. Zusätzlich ist es möglich, Zahlungen direkt aus dem ERP zu starten, beispielsweise über Pay By Link. Detaillierte Beschreibungen der Anbindungsarten finden sich in den Artikeln zur direkten Anbindung und zur Import-Anbindung.

Kommunikationsdiagramm

happy way

 

Verknüpfung mit