Pre-built UI integration

An overview of how the intergration with the Accounting as a Service pre-built UI solution looks like.

When it comes to developing the integration and connecting your business application (e.g. your web shop) with the payment module, we provide you with a pre-built UI solution to be used for accepting payments. In addition to the integration based on our pre-built UI solution, all additional integration will be REST-based by consuming the endpoints of our API.

The pre-built UI solution mainly consists of a JavaScript-based UI component that you will have to integrate. The UI component enables you to fulfil PCI requirements by autonomously rendering all payment method forms and fields while encapsulating sensitive data in an iFrame and handling all communication with the Accounting as a Service REST API independently of your web shop.

While working with the frontend widget being part of the pre-built UI solution, we provide you with an out-of-the-box UI that you can use for accepting payments. This widget is highly customizable and can be adapted to your needs, allowing you to match the styling to your brand, and the language to your shopper. The integration is easy and works without extensive front-end development being needed.

Look & Feel

The pre-built UI can be easily styled according to you corporate layout. Please find one example below:

How it works

A high-level process overview showcasing a sample process using the frontend widget followed by the REST API being consumed.

How to implement

Before you start

Before you start with the implementation, here is some general information related to the integration of the pre-built UI solution that will help you to follow the step-by-step implementation as described below.

The WidgetAPI component library

To make use of the pre-built UI solution, you will have to integrate the component in your code handling the checkout procedure of your web shop. The widget is bundled as a JavaScript file that you can import in your code using the HTML tag <script type="text/javascript" src="..."></script> . For development purpose, the file should be referenced from the following address during your integration and testing work:

https://test.arvato-payment.de/{merchantID}/Pmg.Site/Scripts/v2/WidgetApi.js

For production purpose, you will have to switch to the following address:

https://www.arvato-payment.de/{merchantID}/Pmg.Site/Scripts/v2/WidgetApi.js

The {merchantID} will be provided to you as part of your registration confirmation.

Using WidgetAPIOptions

In order to configure the widget, you will have to make use of Arvato.PayNext.WidgetApiOptions which is part of the WidgetAPI component library. The object type comes along with the following configuration options, of which some are mandatory.

function sucessCallback (response) {
    alert(response.PaymentTokens);
}

function errorCallback (error) {
        alert(error);
    }

function renderErrorCallback (error) {
        alert(error);
    }

function resizeCallback(response) {
        alert(“Widget content has been resized”);
    }

High-level overview of the steps-by-step implementation

Sequence-wise, you need to pass the following steps when using the pre-built UI solution:

• Step 1: Request a security token
• Step 2: Instantiate and configure a new Arvato.PayNext.WidgetApiOptions object (Hint: You will need the security token as part of the configuration to be set)
• Step 3: Instantiate a new Arvato.PayNext.WidgetApi object, show the widget using the render() method and ensure that the tokenize() method can be called for the processing and generation of the payment token.
• Step 4 Handle callbacks

For further processing, please refer to the payment-specific use cases, especially payment request.

Step 1: Request security token

Before you can initialize the frontend widget, you will have to request a security token, which needs to part of the widget configuration. To request a security token, make a POST /payments/{version}/token request. You will be returned by a new token that you can use for setting WidgetApiOptions.securityToken.

Sample request

GET /payments/v1/token HTTP/1.1
Host: api-test-aqount.finance.arvato.com
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "securityToken": "EEB8A443-AC0C-4A81-8015-0001D0446037",
    "version": "1.0"
}

Step 2: Initiate and configure WidgetApiOptions

Setting up the WidgetApiOptions object followed by the widget usually takes place in your frontend code. The following sample shows how to load the related library, create an instance of the object, and how to set the required properties. The given example assumes the merchantId to be AAAAA and the previously requested securityToken to be EEB8A443-AC0C-4A81-8015-0001D0446037.

<!DOCTYPE html>
<html>
...
<!-- Minimal list of HTML elements to be referenced in the following JS code -->
<div id="content"></div>
<input type="button" id="Tokenize" value="Tokenize" />
<div id="widgetContent"></div>
<div id="resultDiv"></div>

<!-- Load jQuery as we will needed it -->
<script type="text/javascript" src="https://code.jquery.com/jquery-2.1.4.min.js"></script>

<!-- Load widget component library using merchant specific URL -->
<script type="text/javascript" src="https://test.arvato-payment.de/AAAAA/Pmg.Site/Scripts/v2/WidgetApi.js">
</script>

<!-- Configure the widget -->
<script type="text/javascript">

var merchantID = "AAAAA";
var securityToken = 'EEB8A443-AC0C-4A81-8015-0001D0446037';

// Initiate WidgetApiOptions
var widgetApiOptions = new Arvato.PayNext.WidgetApiOptions();
widgetApiOptions.tokenizationServiceUrl = 'https://test.arvato-payment.de/' + merchantID +
    '/Pmg.Site/WidgetApi/Home/Index';
widgetApiOptions.securityToken = securityToken;
widgetApiOptions.placeHolder = 'widgetContent';
widgetApiOptions.countryCode = 'DE';
widgetApiOptions.currencyCode = 'EUR';
widgetApiOptions.culture = 'de-DE';
widgetApiOptions.paymentMethods = 'Visa';
widgetApiOptions.successCallback = successCallback;

// The callback function to be executed upon success
function successCallback(response) {
    document.getElementById("resultDiv").innerHTML = "Success! Payment Token Received: " +
        response.PaymentToken;
}

...

Step 3: Initiate and show widget

Once the WidgetApiOptions object has been set up, the widget can be initiated and shown. To continue with the example above, let's continue at the point where WidgetApiOptions has been fully configured.

// Initiate WidgetApiOptions
var widgetApiOptions = new Arvato.PayNext.WidgetApiOptions();
...

// Once the page has been fully loaded
$(document).ready(function () {
    // Initiate and show the widget
    var widget = new Arvato.PayNext.WidgetApi(widgetApiOptions);
    widget.render();

    // Allow to trigger tokenization process
    $('#Tokenize').click(function () {
        widget.tokenize();
    });
});

Calling the render() method will show the widget and therefore start the payment method selection process. Once the payment method has been selected and all relevant user data has been collected, the tokenize() method can be called. From this point on, you will have to wait until any of the callback methods (i.e. successCallback or errorCallback) will be called by the widget to proceed with your business logic. In case of successCallback, you will be provided with the payment token which is the prerequisite for requesting the payment execution in the next step.

Step 4: Handle callbacks

When handling the callbacks, you should be aware of the structure of the WidgetApiCallbackResponse object that will be returned as response by the callback.

WidgetApiCallbackResponse

JsonError

These are callback types you need to be aware of:

Handle successCallback

The callback is triggered when the tokenization process has been successfully executed. In this case, the response object will contain the payment token and the payment method name. At this stage of the process, common next steps would be to provide the customer with a confirmation page and (once you received final confirmation) to request the payment execution.

Sample response object

{
    "Success": true,
    "PaymentToken": "936DA01F-9ABD-4D9D-80C7-02AF85C822A8",
    "PaymentMethodName": "Visa"
}

Handle errorCallback

The callback is triggered in case of the tokenization process running into an error. Here is a list of potential reasons causing the tokenization process to fail:

• Security token has expired
• Timeout occurred
• Service not reachable
• Validation errors occured

Sample response object

{
    "Success": false,
    "Error": {
        "ErrorCode": null,
        "ErrorType": "UnknownError",
        "Message": "Input string was not in a correct format.",
        "Details": "",
        "InnerErrors": null
    },
}

Handle renderErrorCallback

The callback is triggered upon server errors occurring during the rendition of the iFrame. Here is a list of potential reasons causing the rendition process to fail:

• Cannot render the iFrame
• Invalid request
• Invalid response

See also

• Payment methods
• Payment request