Dokumentation
Dokumentation
Mobile Web View

1Einführung

Diese Dokumentation beschreibt im Detail, wie mit einem mobilen Gerät mit der Web-Service-API kommuniziert wird. Die Kommunikation soll über eine WebView oder eine ähnliche Technik erfolgen. Die Grundannahme ist, dass die mobile App in der Lage ist, durch den Aufruf von JavaScript-Funktionen innerhalb der WebView sowie durch das Abhören von URLs, die von der `WebView' aufgerufen werden, zu kommunizieren.

2Sicherheit der Web-Services

Die mobile Anwendung benötigt unter Umständen direkten Zugriff auf die Web-Services. Der MAC-Schlüssel des Anwendungsbenutzers sollte jedoch nicht auf das mobile Gerät übertragen werden, da ein bösartiges mobiles Gerät diese Details andernfalls wiederherstellen könnte. Daher stellen wir eine dedizierte Web-Service-Methode bereit, um für eine bestimmte Zahlungstransaktion TransactionCredentials zu erstellen. Diese Zugangsdaten gewähren vorübergehend (15 Minuten) die Berechtigung, mit der Transaktion zu arbeiten, mit der die Zugangsdaten verknüpft sind. Ausserdem gewähren die Zugangsdaten, wenn sie später verwendet werden, dieselben Berechtigungen wie der Benutzer, der die temporären Zugangsdaten erstellt hat. Dies bedeutet, dass das mobile Gerät dieselben Berechtigungen hat wie der Benutzer.

3Ablauf / Interaktionen

Der Ablauf ist ähnlich wie bei der iFrame-Integration. Die folgenden Schritte fassen zusammen, wie die SDK-Integration verwendet wird. Wir gehen davon aus, dass die Transaktion erstellt wurde und die Transaktions-Zugangsdaten auf das mobile Gerät übertragen wurden:

  1. Rufen Sie die verfügbaren Zahlarten mit der Operation fetchPossiblePaymentMethodsWithCredentials auf dem Transaction Service ab.

  2. Zeigen Sie dem Benutzer eine Liste der Zahlarten an.

  3. Betten Sie für die gewählte Zahlart das Formular ein, indem Sie die Operation buildMobileSdkUrlWithCredentials auf dem Transaction Service aufrufen. Die zurückgegebene URL enthält die gewählte Zahlart nicht. Diese muss hinzugefügt werden, indem der URL-Parameter paymentMethodConfigurationId mit der ID der zu verwendenden Zahlart-Konfiguration angehängt wird. Die URL sollte innerhalb einer WebView aufgerufen werden.

  4. Sobald der Benutzer angibt, die Zahlung abzuschliessen (zum Beispiel durch Drücken eines continue-Buttons), muss die Validierung ausgelöst werden. Dazu muss der MobileSdkHandler aufgerufen werden. Das Ergebnis der Validierung sollte schliesslich verwendet werden, um dem Benutzer eine angemessene Rückmeldung zu geben. In diesem Fall lösen wir den Callback validationCallback aus.

  5. Sobald die Zahlung verarbeitet werden soll (zum Beispiel weil der Benutzer den pay-Button gedrückt hat), muss das Formular innerhalb der WebView abgeschickt werden. Dies kann durch den Aufruf der Methode submit auf dem MobileSdkHandler erfolgen. Nach dem Absenden des Formulars wird unter Umständen ein externer Dienst aufgerufen (zum Beispiel 3-D secure). Dieser Dienst benötigt möglicherweise den gesamten Bildschirm. Sobald die Zahlung abgeschlossen wurde, rufen wir einen der folgenden Callbacks auf: awaitingFinalResultCallback, successCallback oder failureCallback

Mobile-SDK-Sequenzdiagramm
Figure 1. Sequenzdiagramm des Mobile-SDK-Ablaufs

4Ersetzte primäre Aktion

Einige Zahlarten erfordern einen komplexeren Prozess in mehreren Schritten. Standardmässig ist im Zahlungsformular ein Button enthalten, um durch diese Schritte zu navigieren. Es ist jedoch möglich, diese Buttons auszublenden und den primären Absende-Button in Ihrer Anwendung zu verwenden, um die Ereignisse auszulösen.

Immer wenn die primäre Aktion ersetzt wird, wird ein replacePrimaryAction-Callback mit der neuen Beschriftung als Parameter aufgerufen, mit der der primäre Button aktualisiert werden soll. Zusätzlich muss der Button so geändert werden, dass er die Aktion MobileSdkHandler.trigger() auslöst.

Wenn der Kunde alle notwendigen Schritte erfolgreich durchlaufen hat, wird der Callback resetPrimaryAction aufgerufen, was dazu führen sollte, dass der primäre Button auf das Standardverhalten zurückgesetzt wird, das heisst die ursprüngliche Beschriftung trägt und die Aktionen MobileSdkHandler.validate(); und MobileSdkHandler.submit(); auslöst.

Um die Buttons im Zahlungsformular auszublenden, hängen Sie den URL-Parameter replace-primary-action=1 an die Zahlungs-URL an.

5Callbacks

Callbacks werden ausgelöst, um der mobilen Anwendung die Möglichkeit zu geben, auf diese Ereignisse zu reagieren. Ein Callback wird durch den Aufruf einer URL mit dem Präfix https://localhost/mobile-sdk-callback/ ausgelöst. Die URL enthält einen Namen für den Callback und optional einige angehängte Daten. Beispiel: https://localhost/mobile-sdk-callback/some-callback?data={"data":"object"}

Die WebView muss auf URLs überwacht werden, die aufgerufen werden und mit https://localhost/mobile-sdk-callback/ beginnen. Diese URLs stellen Callbacks dar.

5.1Initialisierung

Wenn das Fenster vollständig geladen wurde und alle Listener angehängt sind, wird der Callback initializeCallback aufgerufen. Es werden keine weiteren Daten übermittelt.

5.2Änderung der Frame-Höhe

Wenn sich die Höhe des Frames ändert, wird der Callback heightChangeCallback mit der Höhe (in px) im Datenparameter aufgerufen.

5.3Ersetzen der primären Aktion

Wird die primäre Aktion des Zahlungsformulars ersetzt, wird der Callback replacePrimaryAction mit der Beschriftung der Aktion als Parameter aufgerufen. Der Absende-Button in Ihrer Anwendung sollte mit der übergebenen Beschriftung aktualisiert werden und beim Drücken die Aktion trigger auslösen.

5.4Zurücksetzen der primären Aktion

Wurde die primäre Aktion des Zahlungsformulars ersetzt und wird sie auf das Standardverhalten zurückgesetzt, wird der Callback resetPrimaryAction aufgerufen. Die Beschriftung des Absende-Buttons sollte auf den ursprünglichen Wert zurückgesetzt werden, und beim Drücken sollte die Aktion submit ausgelöst werden.

5.5Validierung

Wenn die Validierung ausgelöst wird, wird deren Ergebnis über den Callback validationCallback zurückgemeldet. Der Datenparameter enthält ein Ergebnisobjekt:

{
	success: false,
	errors: [
		'Message 1',
		'Message 2'
	]
}

5.6Warten auf den endgültigen Status

Wenn der Zahlungsprozess abgeschlossen wurde, kann es vorkommen, dass noch kein endgültiges Ergebnis (Erfolg / Fehlschlag) vorliegt. In diesem Fall rufen wir den Callback awaitingFinalResultCallback auf. Der Datenparameter enthält die Transaktions-ID. Normalerweise wird ein endgültiger Status (Erfolg oder Fehlschlag) innerhalb von Sekunden erreicht. Manchmal kann es auch Minuten dauern.

5.7Erfolg

Wenn der Zahlungsprozess erfolgreich abgeschlossen wird, wird der Callback successCallback aufgerufen. Der Datenparameter enthält die Transaktions-ID. Erfolgreich bedeutet, dass die Transaktion mindestens authorized ist.

5.8Fehlgeschlagen

Wenn der Zahlungsprozess fehlschlägt, wird der Callback failureCallback aufgerufen. Der Datenparameter enthält die Transaktions-ID. Fehlgeschlagen bedeutet, dass sich die Transaktion im Status failed befindet.

6JavaScript API 

<script>

// This triggers the validation.
MobileSdkHandler.validate();

// This triggers the primary action if it has been replaced by the 'replacePrimaryAction' callback.
MobileSdkHandler.trigger();

// This will submit the form and triggers the processing of the payment.
MobileSdkHandler.submit();

</script>

7Tokenisierung

Die verfügbaren Tokens können mit der Operation fetchOneClickTokensWithCredentials auf dem Transaction Service abgerufen werden. Die Verarbeitung einer Transaktion mit einem solchen Token kann über processOneClickTokenWithCredentials erfolgen. Das Löschen eines Tokens kann mit der Operation deleteOneClickTokenWithCredentials ausgeführt werden.

Weitere Operationen können über den regulären Token Service und Token Version Service ausgeführt werden.