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
WebView and by listening on URLs invoked by the `WebView'.
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
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.
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:
Fetch the available payment methods by using the operation
fetchPossiblePaymentMethodsWithCredentials on the
Present a list of payment methods to the user.
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
the ID of payment method configuration to use. The URL should be invoked within a
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
validationCallback in this case.
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:
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
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
To hide the buttons in the payment form, append the URL parameter
replace-primary-action=1 to the payment URL.
Callbacks are triggered to give the mobile application to react to those events. A callback is triggered through invoking a URL prefixed with
The URL contains a name for the callback and optionally with some data attached. Example:
WebView has to be monitored for URLs which are invoked and start with
https://localhost/mobile-sdk-callback/. Those URLs represents callbacks.
When the window has been loaded fully and all listeners have been attached the callback
initializeCallback is invoked. There will be no further data.
When the frame height changes the callback
heightChangeCallback is invoked with the height (in px) in the data parameter.
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.
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.
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:
When the payment process was completed it can happen that we have no final result (success / failure). In this case we invoke the callback
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.
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
// This triggers the validation.
// This triggers the primary action if it has been replaced by the 'replacePrimaryAction' callback.
// This will submit the form and triggers the processing of the payment.
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
Further operations can be carried out by the regular
Token Service and
Token Version Service.