Documentation
Documentation
Vue Web mobile

1Introduction

This documentation covers the details how to communicate with the web service API with a mobile device. The communication is intended to be done through a WebView or some similar technique. The base assumption is that the mobile app is able to communicate by invoking JavaScript functions within the WebView and by listening on URLs invoked by the `WebView'.

2Web Services Security

The mobile application may need direct access to the web services. However it the MAC key of the application user should not be pushed to the mobile device because they would eventually allow a malicious mobile device to recover those details. As such we provide a dedicated web service method to create for a particular payment transaction to create TransactionCredentials. Those credentials grant temporarily (15 minutes) the permission to work with the transaction with which the credentials are linked. Furthermore, when the credentials are provided later they will grant the same permissions as the user has which created the temporary credentials. This implies that the mobile device will have the same permissions as the user.

3Flow / Interactions

The flow is similar as with the iFrame integration. The following steps summarize how to use the SDK integration. We assume that the transaction has been created and the transaction credentials has been pushed to the mobile device:

  1. Fetch the available payment methods by using the operation fetchPossiblePaymentMethodsWithCredentials on the Transaction Service.

  2. Present a list of payment methods to the user.

  3. For the selected payment method embed the form by calling the operation buildMobileSdkUrlWithCredentials on the Transaction Service. The returned URL will not contain the selected payment method. This has to be added by appending the URL parameter paymentMethodConfigurationId with the ID of payment method configuration to use. The URL should be invoked within a WebView.

  4. Once the user indicates to complete the payment (press a for example a continue button) the validation has to be triggered. Therefore the MobileSdkHandler has to be invoked. Eventually the result of the validation should be used to give the user an appropriated feedback. We trigger the callback validationCallback in this case.

  5. Once the payment should be processed (for example the user has pressed the pay button) the form within the WebView has to be submitted. This can be done by invoking the submit method on the MobileSdkHandler. Once the form has been submitted we may invoke an external service (for example 3-D secure). This service may require the whole screen. Once the payment has been completed we invoke one of the following callbacks: awaitingFinalResultCallback, successCallback or failureCallback

Mobile SDK Sequence Diagram
Figure 1. Sequence Diagram of the Mobile SDK flow

4Replaced Primary Action

Some payment methods require a more complex process in multiple steps. By default, a button is included in the payment form to navigate through these steps. It is however possible, to hide these buttons and use the primary submit button in your application to trigger the events.

Whenever the primary action is replaced, a replacePrimaryAction callback is invoked with the new label as a parameter the primary button should be updated with. Additionally, the button must be changed to trigger the MobileSdkHandler.trigger() action.

When the customer has successfully navigated through all necessary steps, the resetPrimaryAction callback is invoked, that should result in the primary button being reset to default behaviour i.e. having the initial label and triggering the MobileSdkHandler.validate(); and MobileSdkHandler.submit(); actions.

To hide the buttons in the payment form, append the URL parameter replace-primary-action=1 to the payment URL.

5Callbacks

Callbacks are triggered to give the mobile application to react to those events. A callback is triggered through invoking a URL prefixed with https://localhost/mobile-sdk-callback/. The URL contains a name for the callback and optionally with some data attached. Example: https://localhost/mobile-sdk-callback/some-callback?data={"data":"object"}

The WebView has to be monitored for URLs which are invoked and start with https://localhost/mobile-sdk-callback/. Those URLs represents callbacks.

5.1Initialize

When the window has been loaded fully and all listeners have been attached the callback initializeCallback is invoked. There will be no further data.

5.2Frame Height Change

When the frame height changes the callback heightChangeCallback is invoked with the height (in px) in the data parameter.

5.3Replace Primary Action

If the primary action of the payment form is replaced, the callback replacePrimaryAction is invoked with the label of the action as parameter. The submit button in your application should be updated with the passed label and should trigger the trigger action when pressed.

5.4Reset Primary Action

If the primary action of the payment form has been replaced and is reset to default behavour, the callback resetPrimaryAction is invoked. The submit button’s label should be restored to the initial value and the submit action should be triggered when pressed.

5.5Validation

When the validation is triggered the result of this will be reported back through the callback validationCallback. The data parameter will contain a result object:

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

5.6Awaiting Final Status

When the payment process was completed it can happen that we have no final result (success / failure). In this case we invoke the callback awaitingFinalResultCallback. The data parameter will contain the transaction ID. Normally a final state success or failure is reached within seconds. Sometimes it can take also minutes.

5.7Success

When the payment process completes successfully the callback successCallback is invoked. The data parameter will contain the transaction ID. Successfully the transaction is at least authorized.

5.8Failed

When the payment process fails the callback failureCallback is invoked. The data parameter will contain the transaction ID. Failed means the transaction is in the state failed.

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>

7Tokenization

The available tokens can be fetched with the operation fetchOneClickTokensWithCredentials on the Transaction Service. The processing of a transaction with such a token can be done by using processOneClickTokenWithCredentials. The deletion of a token can be executed with the operation deleteOneClickTokenWithCredentials.

Further operations can be carried out by the regular Token Service and Token Version Service.