5.6. Payment method selection page embedding

5.6.1. Introduction

When Paytrail payment service has been integrated using either REST interface or form interface, the payment process can be shortened and made easier from the customer's point of view by implementing payment method selection embedding. In this case the payment methods are available directly at the end of a webshop's order process instead of having to move first to Paytrail service to select the payment method.

Figure 5.4. Payment method selection page embedding

Payment method selection page embedding

The payment method selection page embedding is easy to implement once the payment service has been first integrated with REST or form interface. It can be enabled by adding a small JavaScript code to the payment button page. We recommend adding the code to the end of the page before the closing body tag. In this case JavaScript is run last without slowing down page rendering.

This feature degrades gracefully: even if JavaScript is disabled by the customer's browser, the original payment button will still appear on the payment page just as it was shown before adding JavaScript code.

JavaScript interface offers two methods; one is used for the chosen payment interface. initWithToken request is used for the REST implementation and initWithForm request is used for the form interface implementation.

Note

Payment method selection page embedding widget uses jQuery in order to enable cross-browser compatibility. The module downloads jQuery library version 1.7 automatically from Google cloud services if jQuery is not available or jQuery version is unsupported. Required jQuery version is 1.4.3 or later.

5.6.2. Versions

5.6.3. Embedding when using the REST interface

initWithToken(string elementId, string token, object options)
string elementId
Id value for the html element describing an optional view for moving to the payment selection. This element is replaced with the payment method selection page widget once the widget has been downloaded. If JavaScript is not enabled, the customer will see this optional view, which typically is a direct link ("Pay here" button) to the payment method selection page.
string token
The REST interface returns a token value, which is sent as a parameter to the request.
object options
Options is a data structure, which allows adding extra parameters for the design and functionality of the payment method selection page widget. The parameters are described in chapter parameters.

Example 5.13. Payment method selection page embedding with JSON interface

<p id="payment">
  <a href="https://payment.paytrail.com/payment/load/token/0123456789abcdefg">Go to payments</a>
</p>

...

<script type="text/javascript" src="//payment.paytrail.com/js/payment-widget-v1.0.min.js"></script>
<script type="text/javascript">
SV.widget.initWithToken('payment', '0123456789abcdefg', {charset: 'ISO-8859-1'});
</script>
          

5.6.4. Embedding when using the form interface

initWithForm(string formId, object options)
string formId
The form element id value data is sent to the payment service. The form element is replaced with a payment selection element once it has been downloaded. If JavaScript is not enabled, the customer can send this form normally and go to the payment selection page. Therefore, remember to keep a visible send button in the form.
object options
Options is a data structure, which allows adding extra parameters for the design and functionality of the payment method selection page widget. The parameters are described in chapter parameters.

Example 5.14. Payment method selection page embedding with form interface

<form id="payment">
  <input type="hidden" name="MERCHANT_ID" value="12345" />
  ...
  <input type="submit" value="Go to payments" />
</form>

...

<script type="text/javascript" src="//payment.paytrail.com/js/payment-widget-v1.0.min.js"></script>
<script type="text/javascript">
SV.widget.initWithForm('payment', {charset:'ISO-8859-1'});
</script>
          

5.6.5. Parameters

The last parameter of initWithToken and initWithForm is an object named options. This object can be used to customise the design and functionality of the payment method selection widget. All parameters of the options structure are optional and their default values are presented in parenthesis.

charset
Character set for the page. Supported character sets are "UTF-8" and "ISO-8859-1". Parameter is not required for the REST implementation. (Default: "UTF-8").
debug
The widget can be set to test mode with this parameter (value 1). When in test mode the widget reports its functionality to the FireBug tool (default: 0)
defaultLocale
Default localisation for the widget. Supported localisations are da_DK, de_DE, et_EE, en_US, fr_FR, no_NO, ru_RU, fi_FI and sv_SE.
height
Widget height in pixels. 0 is also an acceptable value, the widget height is then automatically determined based on the content. If the widget height is set too small for the content to fit in, a vertical scroll bar is shown in the widget (default: 0)
locales
List of the available localisations. See supported localisations in defaultLocale field description. (default: all available localisations are shown in alphabetical order)
widgetId
You can define the widget element's root-id manually if you wish to handle the element dynamically, or the default id is in use. (default: "sv-widget")
width
Widget width in pixels. (default: 500)

5.6.6. Localisation

The payment method selection page embedding supports the following localisations: fi_FI (Finnish), en_US (English), da_DK (Danish), de_DE (German), et_EE (Estonian), fr_FR (French), ru_RU (Russian) and sv_SE (Swedish). The traditional payment method selection page supports fi_FI (Finnish), en_US (English) and sv_SE (Swedish).

Note

Payment method provider services only support localisations fi_FI, en_US and sv_SE or a subset of those. If the customer has selected such a localisation that is not supported by the payment method provider service, localisation en_US is preferred.