Dokumentation
Dokumentation
Payment Web Apps BETA

1Einführung in Payment Web Apps

Payment Web Apps ermöglichen die Integration von Zahlungsdiensten, die nicht direkt in unseren Dienst integriert sind.

Payment Web Apps sind im Grunde einfach normale Web Apps mit der Fähigkeit, Zahlungen zu verarbeiten.

Auf einer hohen Ebene müssen Sie die folgenden Dinge tun, um die Zahlungsverarbeitung in Ihre Web App zu integrieren:

  1. Sie müssen den Installationsprozess für Ihre Web App integrieren.

  2. Sie müssen den Payment Web App REST-Dienst verwenden, um einen entsprechenden Prozessor und einen oder mehrere Connectors hinzuzufügen.

  3. Sie müssen eine URL bereitstellen, unter der Sie eine Zahlungsseite anzeigen können, auf der der Käufer die Zahlung bestätigen kann.

  4. Der Käufer bestätigt die Zahlung auf Ihrer Zahlungsseite. Sie melden das Ergebnis über JavaScript zurück.

  5. Im Hintergrund informieren Sie zusätzlich auch unser Backend über das Ergebnis der Zahlungsverarbeitung. Dafür verwenden Sie die Operation zum Aktualisieren des Zahlungsversuchs.

Optional können Sie dem Händler auch erlauben, verzögerte Completions durchzuführen und Rückerstattungen auszuführen.

Der folgende Abschnitt führt Sie durch die Details des Prozesses, um eine solche Integration umzusetzen.

2Installation des Prozessors und der Connectors

Die Installation des Prozessors und der Connectors erfolgt über den Payment Web App REST-Dienst. Damit Sie sie installieren können, benötigen Sie zunächst Zugriff auf den Space des Händlers. Folgen Sie dazu bitte der Anleitung, wie die Installation einer Web App durchgeführt werden muss.

Sobald Sie die Web App im Space des Händlers installiert haben, erlauben die Zugangsdaten der Web App die Installation der Prozessoren und Connectors. Als Teil des Installationsprozesses können Sie den Händler bitten, Ihnen bestimmte Berechtigungen zu erteilen. Um anschliessend die Prozessoren und Connectors installieren zu können, müssen Sie die Berechtigung Payment Web Apps (ID: 1627022088852) anfordern.

2.1Einfügen eines Prozessors

Sobald Sie vom Händler die Berechtigung für den Zugriff auf den Space angefordert haben, verwenden Sie die Operation zum Einfügen eines Prozessors, um einen neuen Prozessor hinzuzufügen.

Beim Einfügen des Prozessors müssen Sie eine externalId angeben. Diese ID muss pro Space eindeutig sein. Wenn der Dienst mehrmals mit derselben externalId aufgerufen wird, wird der Prozessor aktualisiert und kein neuer Prozessor eingefügt.

Note
 Wenn der Händler Ihre Web App deinstalliert, werden die zugehörigen Prozessoren ebenfalls entfernt.

2.2Einfügen eines Connectors

Sobald Sie einen Prozessor hinzugefügt haben, können Sie auch einen Connector einfügen. Dazu müssen Sie die Operation Connector einfügen verwenden.

  • externalId: Ähnlich wie beim Prozessor müssen Sie eine externalId angeben. Diese ID muss eindeutig sein. Anfragen mit derselben externalId aktualisieren den Connector, anstatt einen neuen einzufügen.

  • processorExternalId: Der Connector ist immer einem Prozessor zugeordnet. Sie müssen daher auch die processorExternalId des zuvor hinzugefügten Prozessors angeben.

  • completionConfiguration und refundConfiguration: Über die entsprechenden Konfigurationen steuern Sie, ob Rückerstattungen und verzögerte Completions unterstützt werden. Beachten Sie: Sobald Sie einmal angegeben haben, dass Sie diese optionalen Funktionen unterstützen, können Sie sie auf dem Connector über einen Aktualisierungsaufruf nicht mehr deaktivieren.

  • paymentPageEndpoint: Der paymentPageEndpoint empfängt die Zahlungsanfragen. Weitere Details finden Sie unter Verarbeitung der Zahlungsseite.

  • connector: Der connector definiert, welche Zahlart (und gegebenenfalls auch welche Marke) Ihrem neu hinzugefügten Web-App-Connector zugeordnet ist. Siehe unten die Connectors, die Sie angeben können.

Die vollständige Liste der unterstützten Connectors finden Sie unter unterstützte Connectors.

2.3Wechsel in den Live-Modus

Der Prozessor ist standardmässig automatisch bereit für den Einsatz in der Produktionsumgebung. Wenn Sie den Händler zuerst in einem Testmodus anbinden und später in einen Live-Modus wechseln möchten, ist das möglich. Beim Erstellen eines neuen Prozessors können Sie die productionModeUrl definieren. Wenn Sie diese URL angeben, wird der Benutzer an diese URL weitergeleitet, sobald der Prozessor in den Produktionsmodus versetzt wird.

An die URL werden die folgenden Parameter angehängt:

  • timestamp: Die Zeit als Unix-Zeitstempel (Sekunden seit Januar 1970). Er verhindert Replay-Angriffe. Sie sollten daher sicherstellen, dass er nicht zu alt ist.

  • externalId: Die ID des Prozessors, wie sie bei der Erstellung über die Web-Service-API angegeben wurde. Sie hilft Ihnen, den Prozessor auf Ihrer Seite zu identifizieren.

  • returnUrl: Wenn der Benutzer die Aktivierung abgeschlossen hat, können Sie den Benutzer an diese URL zurückleiten. Zusätzlich können Sie eine message und einen type anhängen. Dabei kann die message eine Nachricht für den Benutzer enthalten, und der type gibt an, ob es sich um einen failure oder success handelt.

  • spaceId: Die Space-ID gibt an, in welchem Space der Prozessor installiert wurde.

  • hmac: Der HMAC erlaubt zu überprüfen, ob der Benutzer wirklich von unseren Servern stammt. Die Berechnung des hmac funktioniert auf dieselbe Weise wie bei anderen HMACs.

Note
 Bitte beziehen Sie alle Parameter ein, die Sie über die URL erhalten. Wir könnten die Liste der Parameter in Zukunft erweitern. In diesem Fall werden wir sie ebenfalls in die HMAC-Berechnung einbeziehen.

3Verarbeitung der Zahlungsseite

Während der Installation des Connectors müssen Sie einen Zahlungsseiten-Endpunkt angeben. Diese Endpunkt-URL wird vom Käufer während der Zahlungsverarbeitung aufgerufen.

Dieser Aufruf ermöglicht es, die Zahlung zu verarbeiten, indem weitere Details abgefragt werden oder der Käufer authentifiziert wird usw. Der Zahlungsseiten-Endpunkt muss das folgende Verhalten bereitstellen:

  1. Prüfen Sie die Herkunft der Anfrage. Die Anfrage enthält einen HMAC, der die Überprüfung der Herkunft der Anfrage erlaubt. So können Sie sicher sein, dass die Anfrage legitim ist.

  2. Fragen Sie weitere Details vom Benutzer ab. Beispielsweise bitten Sie den Benutzer, sich zu authentifizieren. Dieser Schritt kann auch übersprungen werden, wenn er nicht nötig ist.

  3. Sobald das Ergebnis der Verarbeitung feststeht, rufen Sie das entsprechende JavaScript auf, um das Ergebnis der Verarbeitung der Zahlung zurückzumelden. Dieses Feedback wird nur innerhalb des Clients verwendet. Es löst im Client die Änderung der Benutzeroberfläche aus, sodass der Benutzer das Ergebnis kennt. Falls bei der Zahlung etwas schiefgeht und der Client abstürzt, müssen Sie das Ergebnis im Hintergrund auch an unser Backend zurückmelden.

Die folgenden beiden Abschnitte behandeln den ersten und den letzten Schritt des Prozesses genauer.

3.1Verarbeiten der eingehenden Zahlungsseiten-Anfrage

Wenn der Käufer die Zahlungsseiten-Endpunkt-URL aufruft, sind die folgenden Parameter Teil der GET-Anfrage:

  • transactionId: Die Transaktions-ID referenziert die Transaktion, die gerade verarbeitet wird. Sofern der Händler es erlaubt, kann es mehrere Zahlungsversuche pro Transaktion geben.

  • chargeAttemptId: Die Zahlungsversuchs-ID referenziert den Zahlungsversuch, der im Rahmen dieses Aufrufs durchgeführt wird.

  • language: Die Sprache gibt an, welche Sprache der Käufer spricht. Die Zahlungsseite sollte daher in dieser Sprache dargestellt werden. Der Parameter language hat das Format des IETF-Sprach-Tags. Zum Beispiel de-DE.

  • currency: Die Währung enthält den dreibuchstabigen ISO-Code der Währung (z. B. USD, EUR, CHF usw.).

  • returnUrl: Wenn die Zahlung abgeschlossen ist, müssen Sie den Benutzer an diese URL zurückleiten.

  • amount: Der Betrag entspricht dem Betrag, der belastet werden soll. Das Betragsformat ist eine normale Dezimalzahl. Zum Beispiel 10.56. Bitte beachten Sie, dass Sie möglicherweise eine geeignete Datenstruktur verwenden müssen, um dies korrekt zu verarbeiten. In Java sollten Sie beispielsweise ein BigDecimal verwenden. Die Anzahl der Dezimalstellen hängt von der Währung ab.

  • authorizationEnvironment: Die Umgebung, in der die Zahlung durchgeführt werden soll. Der Wert kann entweder TEST oder PRODUCTION sein. Wenn der Wert TEST ist, sollten Sie nur eine simulierte Zahlung durchführen. In diesem Fall darf kein Geld bewegt werden.

  • completionBehavior: Das Completion-Verhalten gibt an, ob die Zahlung IMMEDIATELY oder DEFERRED abgeschlossen werden soll. Falls der Connector die verzögerte Completion nicht unterstützt, ist der completionBehavior immer IMMEDIATELY.

  • spaceId: Die Space-ID referenziert den Space, in dem die Web App installiert wurde.

  • connectorExternalId: Dies ist die ID des Connectors, der die Zahlung ausführen soll. Die ID entspricht der ID, die bei der Erstellung des Connectors angegeben wurde.

  • merchantReference: Die Händlerreferenz hilft dem Händler, die Zahlung zu identifizieren. Fügen Sie diese Referenz der Zahlung hinzu, wenn es sinnvoll ist. Sie ist nicht eindeutig, hilft aber normalerweise dem Käufer und dem Händler zu verstehen, zu welcher Bestellung die Zahlung gehört.

  • hmac: Der hmac enthält den Hash über die obigen Parameter, abgesichert mit dem Web-App-Geheimnis. Die Berechnung des hmac funktioniert wie bei anderen HMACs im Zusammenhang mit Web Apps. Bitte beziehen Sie alle Parameter ein, die innerhalb der HTTP-Anfrage bereitgestellt werden (mit Ausnahme der bereits in der Endpunkt-URL vorhandenen Parameter). Wir könnten in Zukunft weitere Parameter hinzufügen, und Sie sollten diese einbeziehen, da die Verarbeitung sonst nicht mehr funktioniert.

Wenn die obigen Parameter nicht enthalten, was Sie zur Verarbeitung der Zahlung benötigen, können Sie über die REST-API das Transaktionsobjekt abrufen. In diesem Fall müssen Sie möglicherweise während der Installation der Web App weitere Berechtigungen anfordern.

Die Anfrage enthält eine chargeAttemptId. Jede Transaktion kann mehrere Zahlungsversuche haben. Jeder Versuch versucht, den Konsumenten zu belasten. Wenn ein Versuch erfolgreich ist, wird die Transaktion als authorized markiert. Das bedeutet, dass eine Transaktion höchstens einen successful Zahlungsversuch haben kann. Sie sollten dies auf Ihrer Seite prüfen und sicherstellen, dass dies nie zu einem Problem wird. Alle nachfolgenden Operationen (Rückerstattung, Void und Completion) referenzieren lediglich die Transaktion.

Note
 Sie müssen den HMAC validieren, um sicherzustellen, dass das System nicht manipuliert werden kann. Wenn Sie dies versäumen, könnte ein Angreifer in der Lage sein, eine Zahlung vorzutäuschen.
Note
 Bitte beziehen Sie alle Parameter ein, die Sie über die URL erhalten. Wir könnten die Liste der Parameter in Zukunft erweitern. In diesem Fall werden wir sie ebenfalls in die HMAC-Berechnung einbeziehen.

3.2Aktualisieren des Zahlungsversuchs

Sobald Sie den Zahlungsversuch verarbeitet haben, müssen Sie uns den Status des Zahlungsversuchs zurückmelden. Sie müssen dies tun, bevor Sie den Benutzer zur returnUrl zurückleiten. Verwenden Sie zu diesem Zweck die REST-API-Operation Zahlungsversuch aktualisieren.

4Verzögerte Completion

Der externe Dienstleister kann entscheiden, auch die verzögerte Completion anzubieten. Das bedeutet, dass der Händler zuerst einen Betrag autorisiert und in einem zweiten Schritt einen anderen Betrag abschliesst. Um einen solchen zweistufigen Prozess zu ermöglichen, muss der Connector die Konfigurationseigenschaft completionConfiguration enthalten. Bei der Erstellung des Connectors können Sie die entsprechende Eigenschaft hinzufügen.

Note
 Wenn der Connector einmal die verzögerte Completion unterstützt hat, kann sie nicht mehr abgeschaltet werden. Eine Aktualisierung, welche die Completion-Konfiguration entfernt, schlägt daher fehl.

Der Parameter completionBehavior innerhalb der Zahlungsseiten-Anfrage gibt an, ob die Zahlung direkt abgeschlossen werden soll oder ob später eine Completion-Anfrage folgt. IMMEDIATELY bedeutet, dass die Zahlung direkt verbucht werden muss.

4.1Ausführung einer Completion

Wenn der Händler eine Completion-Anfrage ausführt, wird der completionEndpoint aufgerufen, der innerhalb der completionConfiguration definiert ist. Die HTTP-POST-Anfrage an den Endpunkt enthält den folgenden Body:

{
	"completionId": 1231231,
	"spaceId": 12,
	"amount": 12.96,
	"transactionId": 542131,
	"merchantReference": "Some reference from the merchant for this completion",
	"lastCompletion": true,
}

Parameterbeschreibung:

  • completionId: Diese ID referenziert die Completion in unseren Systemen. Sie können auch die Web-Service-API verwenden, um das Completion-Objekt mit dieser ID zu lesen und weitere Details abzurufen. Zusammen mit der spaceId ist die completionId eindeutig.

  • spaceId: Die Space-ID referenziert den Space, zu dem die Completion gehört.

  • amount: Der Betrag entspricht dem Betrag, der abgeschlossen werden soll.

  • transactionId: Die ID der Transaktion referenziert das Transaktionsobjekt.

  • merchantReference: Die Händlerreferenz entspricht einer Referenz des Händlers, die hilft, diese Completion zu identifizieren.

  • lastCompletion: Dieses Flag gibt an, ob dies die letzte Completion ist oder ob eine weitere Completion folgen könnte.

Die HTTP-Anfrage mit der obigen JSON-Nachricht wird wiederholt, bis der comopletionEndpoint mit einem HTTP-2xx-Statuscode antwortet. Das Feedback über den Status der Completion muss durch einen Aufruf der REST-API-Operation Completion aktualisieren erfolgen. Dieses Feedback muss innerhalb der completionTimeoutInMinutes erfolgen. Andernfalls betrachten wir die Completion als fehlgeschlagen.

4.2Ausführung eines Voids

Falls der Händler entscheidet, die Transaktion nicht abzuschliessen, führen wir einen Void aus. Wenn der Händler eine oder mehrere Completions ausgelöst hat, kann kein Void mehr ausgelöst werden.

Wenn der Händler einen Void auslöst, erhält der voidEndpoint, der innerhalb der completionConfiguration definiert ist, den folgenden HTTP-POST-Anfrage-Body:

{
	"voidId": 65437,
	"spaceId": 12,
	"transactionId": 542131,
}

Parameterbeschreibung:

  • voidId: Diese ID referenziert den Void in unseren Systemen. Sie können auch die Web-Service-API verwenden, um das Void-Objekt mit dieser ID zu lesen und weitere Details abzurufen. Zusammen mit der spaceId ist die voidId eindeutig.

  • spaceId: Die Space-ID referenziert den Space, zu dem der Void gehört.

  • transactionId: Die ID der Transaktion referenziert das Transaktionsobjekt.

Die HTTP-Anfrage mit der obigen JSON-Nachricht wird wiederholt, bis der voidEndpoint mit einem HTTP-2xx-Statuscode antwortet. Das Feedback über den Status des Voids muss durch einen Aufruf der REST-API-Operation Void aktualisieren erfolgen. Dieses Feedback muss innerhalb der completionTimeoutInMinutes erfolgen. Andernfalls betrachten wir den Void als fehlgeschlagen.

5Rückerstattungen

Rückerstattungen ermöglichen es einem Händler, dem Käufer Geld zurückzugeben. Der Händler kann eine solche Rückerstattung nur auslösen, wenn der Connector Rückerstattungen unterstützt. Bei der Erstellung des Connectors aktiviert die Eigenschaft refundConfiguration Rückerstattungen für den entsprechenden Connector. Wenn ein Connector einmal Rückerstattungen unterstützt hat, kann dies nicht mehr abgeschaltet werden. Eine Aktualisierung des Connectors, welche die refundConfiguration nicht mehr enthält, schlägt daher fehl.

Wenn der Händler eine Rückerstattung auslöst, rufen wir den refundEndpoint auf. Der Body der HTTP-POST-Anfrage enthält das folgende JSON:

{
	"refundId": 5623,
	"spaceId": 12,
	"amount": 12.96,
	"merchantReference": "Some reference from the merchant for this refund",
	"transactionId": 542131,
}

Parameterbeschreibung:

  • refundId: Diese ID referenziert die Rückerstattung in unseren Systemen. Sie können auch die Web-Service-API verwenden, um das Rückerstattungsobjekt mit dieser ID zu lesen und weitere Details abzurufen. Zusammen mit der spaceId ist die refundId eindeutig.

  • spaceId: Die Space-ID referenziert den Space, zu dem die Rückerstattung gehört.

  • amount: Der Betrag entspricht dem Betrag, der dem Käufer zurückerstattet werden soll.

  • transactionId: Die ID der Transaktion referenziert das Transaktionsobjekt.

  • merchantReference: Die Händlerreferenz entspricht einer Referenz des Händlers, die hilft, diese Rückerstattung zu identifizieren.

Die HTTP-Anfrage mit der obigen JSON-Nachricht wird wiederholt, bis der refundEndpoint mit einem HTTP-2xx-Statuscode antwortet. Das Feedback über den Status der Rückerstattung muss durch einen Aufruf der REST-API-Operation Rückerstattung aktualisieren erfolgen. Dieses Feedback muss innerhalb der refundTimeoutInMinutes erfolgen. Andernfalls betrachten wir die Rückerstattung als fehlgeschlagen.

6Payment App Connectors

Wenn die Zahlungs-App installiert ist, können Sie die Connectoren hinzufügen, mit denen Sie die Zahlungen verarbeiten. Die folgenden Connectoren können dafür verwendet werden.

Id Name
1634723429050 Kryptowährung