Splitit Flex Fields - Wiki

Library version: 1.7.24

All you need to set up Splitit Flex fields is described here. Please follow the instructions below, and use your sandbox API key to try out the Flex Fields functionality!

General Data Flow

Flex fields plugin is loaded to the web page, all the sensitive credit card data fields are securely loaded within our iframe components.
Obtain the public token by calling Initiate API method server-side or use our SDK for simplified invocation sufficient in most cases. Public token is required to initialize front-end JS component. In the server-side call, no sensitive credit card data is sent.
Pass the public otken obtained server side to client side FlexFields component. This can be done either while rendering the page for the first time, or when page is rendered fetch the token with AJAX.
When "Pay" button is clicked, our SDK will collect the sensitive credit card data and send it securely to our servers. It is also possible to create your own "Place Order" button and trigger checkout yourself.

Getting started

The next few code examples provide a minimal setup to obtain the working example. Each of those can be further customized and adjusted as explained in this section.

Step 1: Setup some server-side code

As a prerequisite for the server-side code, you should reference or install Splitit SDK for your specific language within your server-side project. It provides the classes and methods to seamlessly invoke Splitit REST API, which is necessary for integrating the FlexFleids plugin into your website. The SDK with the corresponding installation instructions can be found on our github repository. If your language is not yet supported for SDK, you will have to build the REST API calls manually according to this documentation.

Run the following command in your Package Manager Console (if you're using .NET Core Razor pages for backend code):

install-package Splitit.SDK.Client

Run the following command in your Package Manager Console (if you're using .NET Core MVC for backend code):

install-package Splitit.SDK.Client

Create a new project and install splitit/sdk package with composer:

composer require splitit/sdk

Add new razor page to solution, and name it FlexFieldsExample. Insert the source code below instead of the OnGet() method in FlexFieldsExample.cshtml.cs file.
Show example source code

Add new View to /Views/Home folder, and name it FlexFieldsExample. Insert the source code below inside /Controllers/HomeController.cs file.
Show example source code

Add new page and name it server-side.php Insert the example source code in newly created page. This example uses config.php page to store credentials, but feel free to use your favorite mechanism.

Step 2: Add credit card placeholders to newly created page

Add new page and name it index.php. This will be the default page containing the credit card fields.

Show example source code

Step 3: Include flex fields javascript and default style

Important note: This script has to be added after the fields, preferrably right before the closing </body> tag.

If you're using .NET, it's likely you'll need to add all scripts within @section Scripts {}.

Show source code

Note: Script loaded this way will potentially be cached by browser or any intermediate software like CloudFlare. It is recommended for performance, but to force a new version, any suffix like ?v=some_random_number can be added.

Step 4: Wire-up flex fields

Show source code

The minimal setup using the recommended design can be found here: Splitit Examples - Classic Design. Feel free to inspect page source code for more information, or browse common scenarios. The source code for example site can be found on our examples github repository.

Key concepts

This sections describes the key concepts for Splitit FlexFields plugin.

Server side adjustments

To integrate Splitit FlexFields, it is necessary to have some server-side code since you never want to expose your API key, your username or password publicly. Having that in mind, you should call the /Initiate API call, preferably using one of the available Splitit SDKs. Some of the important server-side options are listed here, full documentation is available here.

attempt3DSecure flag: Initiates the 3D secure process if needed. Read more about it here.
autoCapture flag: For a scenario in which you would like to hold with the first charge until product is shipped (or some other reason), set property AutoCapture to false or leave null. The default value is false. This is the recommended setup for most scenarios. See the example source code.
requestedNumberOfInstallments: Defines the number of installment options shown to the user. This field is a hint which can be slightly adjusted by Splitit based on your account settings and permissions. In most cases, the installment options requested will be shown to user as defined. See the example source code

Defining the layout

Splitit FlexFields plugin comes with predefined layouts, and several key UI components: Credit card fields, installment picker, payment schedule, error box and "pay" button. Each of the components except sensitive credit card fields can be entirely customized, and it is possible to customize UI for all of the components and keep the existing functionality in place.

Each UI component is defined in HTML using standard div elements, and when FlexFields are initialized, appropriate UI is rendered within, after flexFields.show() function is called.

Supplying the data

To be able to complete the payment, the FlexFields component needs to obtain the public token obtained with server-side API code. This information can be passed to FlexFields JS component in two ways:

As part of the configuration parameters as shown in the getting started.
Later, by performing an AJAX call which will return the token. The token can be set by calling the flexFields.setPublicToken() function. Click here to see this example scenario in action.

Setting the customer information

For Splitit to work for customers (shoppers), we need to collect some of the basic information like billing address, full name and email. This information can be supplied in several different places:

Supplying the customer data via server-side /Initiate call. This is useful when on checkout page, all the data for customer is already known.
Supplying the customer data in Splitit.setup() function in Javascript. This is useful especially in SPA applications.
Supplying the customer data via Splitit.updateDetails() function in Javascript. Useful when customer can edit data on checkout page before performing the actual payment.

Credit card fields

Required. Credit card fields, such as card number, expiration date and CVV, contain sensitive credit card data, and each of them is rendered in its own iframe. It is not possible to implement those fields, but it is possible to customize the design, including validation errors and information. For more information on how to set the fields up, please click here.

Default configuration for sensitive fields is as follows:

The table below shows configuration options for each credit card field component. Each field requires a single selector property, which represents any valid CSS selector which returns one result. Id is not required as selector, but it's recommended to use it.

Field type	Description
number	Credit card number.
cvv	CVV field.
expirationDate	Expiration date input field in format MM/YY.
expirationMonth	Expiration month input field in format MM. Only possible to use alongside expirationYear.
expirationYear	Expiration year input field in format YY. Only possible to use alongside expirationMonth.

Installment picker

Recommended. Since Splitit is all about helping customers acquire the product and pay for it over time, we offer a few versions of installment picker UI component. It is possible to completely customize this component, or even implement your own installment picker. If you choose our recommended design, it is required to supply only container selector when initializing the FlexFields plugin. Based on the number of requested installment options passed in the /Initiate call, installment picker is rendered according to our carefully selected algoritm to maximize conversion.

For more information on each of the properties, refer to the following information.

Default configuration for installments picker is as follows:

The table below shows configuration options for the installment picker UI component.

Property	Values	Description
selector	Any valid CSS selector. Make sure only one element is returned.	Indicates the UI element which will contain the installment picker.

Loader component

In some cases, additional information needed to display installment picker options needs to be fetched from Splitit servers. In that situation, if FlexFields form needs to be shown and information is not yet ready, a loader is briefly shown to improve user experience and remain within the boundaries of the performance-optimized site. If the default loader is not suitable for your needs, custom loader can be implemented. For more information, refer to the loader documentation.

Loader configuration is set up with the following example:

The table below shows configuration options for loader property.

Supplied value	Type	Description
Element selector.	string	Any valid CSS selector. Make sure only one element is returned, and this element will be injected as loader.
HTML string.	string	Any valid HTML that will be injected as loader.
Callback function.	function	Function which will be called when loader needs to be rendered. The callback function accepts single parameter - the container element in which loader should be rendered.

Splitit error box

Optional. If any error occurs while filling the credit card fields or during processing of the payment request, they will be shown in this error box, if this component is defined. Error box can be styled or completely implemented from scratch. Show the default error box configuration source code.

Terms and conditions checkbox

Required. It is required to provide the selector for user to accept Splitit terms and conditions, alongside privacy policy. If you're using custom installment picker component, terms and conditions checkbox will be enabled for selection only when number of installments is provided. If you're using default installment picker, terms and conditions checkbox will be enabled for selection after the number of installment is chosen for the first time. Show the default terms & conditions configuration source code.

Payment button

Optional. Splitit FlexFields SDK can take care of rendering the payment button for you, and taking care of disabling it in time and enabling when possible. Also integrates loading indicator while payment is being processed.

For more information on each of the properties, refer to the following information.

Default configuration for payment button is as follows:

The table below shows configuration options for the payment button UI component.

Property	Values	Description
selector	Any valid CSS selector. Make sure only one element is returned, and it's type must be <button>	Indicates the UI element which will contain the payment button.
onClick	Callback function when button is clicked. Callback param 1: buttonInstance Callback param 2: flexFieldsInstance

The table bellow shows the methods available for buttonInstance if custom click event is captured:

Method name	Parameters	Returns	Description
setIsLoading(isLoading: boolean)	isLoading: boolean flag indicating whether loading animation should be displayed or not.	void	Sets the loading indicator on the button. This is called automatically when checkout() method for FlexFields instance is called.
enable()		void	Sets the button as enabled.
disable()		void	Sets the button as disabled.

Please refer to the source code below for example on how to respond to button click event:

Payment schedule

Optional. By default, payment schedule is shown within the installment picker control, but it is possible to specify separate container for payment schedule. One such example would be using a popup, or when entirely custom installment picker selector is implemented. Show the payment schedule configuration source code.

Common scenarios and examples

The section below explains some of the important routines and properties shipped with the FlexFields SDK.

Completing the payment process

When payment process is successfully completed, the onSuccess event is invoked. Usually, a notification message is displayed to user or the user is redirected to order confirmation page. The data provided in the event is the result of /Create API call that SDK does for you under the hood.
Note: in case of 3D secure process, this method is called after the 3Ds is successfully validated.

Click here to see the example source code

Fraud prevention

Splitit ensures that payment is processed securely and user's credit card information is appropriately protected. However, it is merchant's task to ensure that the payment is appropriately linked to the corresponding order and to verify that the payment was indeed completed for the appropriate amount.
As a help, we present a recommended practice to ensure the payment is correctly linked to the order. Few things should be considered here:

It is recommended to store installment plan number alongside other order data. This should be done after first server-side to /Initiate is performed and installment plan number is generated.

Click here to see the example source code

Responding to errors

If something goes wrong with the payment (credit card is invalid, installment number not supported, etc.), user will be notified automatically in the error box, if implemented. Regardless if default Splitit Error Box is used, it is possible to implement additional logic if error occurs.

Click here to see the example error handling or visit our example scenario to see it in action.

Dynamic interaction

When FlexFields is initialized, each field wrapper gains a new CSS class: splitit-flex-field and splitit-flex-field-type, where type can be one of: cvv, number, expiration-date, expiration-month, expiration-year. Furthermore, based on user interaction, each field gains additional CSS class:

focused When class is focused, focused CSS class is appended to the field wrapper.
valid When field is validated and considered valid, valid CSS class is appended to the field wrapper.
invalid When field is invalid (either client side error or server validation failed), invalid CSS class is appended to the field wrapper.

Based on above, it is possible to customize the styling in each of these states.

Click here to see the example source code

Additionally, when any of the fields is updated - either gains or loses focus, or becomes valid or invalid, JS event onFieldUpdate(fields) is raised which can be caught and custom logic can be executed if needed, one such example is shown here.

Listed below are properties available in each element of fields parameter received in onFieldUpdate(fields) event handler:

Property name	Type	Description
showValidationError	bool	Whether validation error should be shown or not. For instance, field can be invalid, but if it has never been focused, we don't want to mark it as invalid to user.
errors	Array of string	Errors associated to that particular field. Often just 1, but possible more.
type	string	Field type. One of: number,cvv,expirationDate,expirationYear,expirationMonth.
isFocused	bool (nullable)
isValid	bool (nullable)	If null, then it can be valid or invalid, and requires a server side validation.
cardType	string (nullable)	Only applicable if field type is number. One of: mastercard, visa, amex, dinersclub, discover, jcb, unknown

Classic and horizontal design

Splitit FlexFields SDK comes with several recommended UI designs:

Classic: Each field styled using wide paddings and rounded corners. To activate this design, add CSS class splitit-design-classic to the root field container.
Horizontal: Similar style, but credit card information is entered in one horizontal line instead of all fields separately. To activate this design, add CSS classes splitit-design-horizontal to the root field container.

See classic design example source code

See horizontal design example source code

Separate expiration year and month fields

It is possible to render expiration year and month separately, and not in single input. To achieve this, the following must be configured:

Set the proper HTML elements
Adjust the initialization script to bind the elements accordingly.

Click here to see the example source code

Sandbox vs production

This wiki uses sandbox environment as default environment for all the examples shown. Naturally, once you're satisfied with flex fields look & feel, you should use production environment instead. The simplest way is to load scripts and styles directly from production, as shown in this source code example.
Note: Do not forget to adjust the server side code as well, as explained here.

It might be needed to use the production version of the SDK library, but use it in sandbox API environment - and that is also possible by passing the sandbox flag when initializing FlexFields plugin.

Configuring 3D secure (v1)

To support 3D secure, several steps should be made:

Adjust server side code to support 3D and provide corresponding URL redirects.
Respond to onSuccess client event like you would without any 3DS process involved. It is also possible to react to 3D process initiation by subscribing to onRequire3ds1. This event is fired when payment data is sent to Splitit servers, and if user's credit card requires a 3D process to be completed. If you attach to this event, then you're responsbile to call redirect3ds1 with the parameters provided in onRequire3ds1 event.

For more information regarding server-side code adjustments, please see the server-side example source code. see the server-side example source code. see the server-side example source code.

For more information regarding client-side code adjustements, please see the client-side example source code.

Custom installment picker

It is possible to implement entirely custom installment picker. Please consider the following when implementing custom installment picker:

You can still utilize the default payment schedule UI component.
On each installment picker change, invoke setNumInstallments method of the initialized FlexFields instance.
Our installment picker implementation responds to specific errors which can be related to amount of installment user has picked and the credit card he provided, and highlights the installment picker in invalid color if any of those errors happen during payment processing. The error codes which are relevant are 5041, 5421 or 5801. See responding to errors section for more information.

See the example custom installment picker source code or visit our example page implementing custom picker.

Override default UI style

To override credit card fields or any of the UI components generated by FlexFields SDK, a set of CSS rules needs to be implemented. Listing the whole HTML element tree with all possible options will not be documented here, instead looking at the generated HTML is recommended and adjusting the styles accordingly. In further SDK versions, each breaking change will be documented and migration steps explained. Feel free to look at the example source code for one such styling

Custom payment button

If the default payment button does not fit, it is possible to implement custom payment button and connect it to SDK. Show the example source code.

Update the payment amount dynamically

In some scenarios, payment amount may need to be updated later in the process, when FlexFields plugin is already initialized. It should be used with caution, you should never expose it in production environment from client side since any user could alter the plan amount this way. Change the plan amount securely from server side using backchannel communication to Splitit servers based on your internal logic. For more information, visit our example page demonstrating the functionality.

FAQ

Configuration issues

FlexFields won't initialize - is something broken?
First thing to do is check developer console (usually F12 shortcut on browser). If FlexFields are initialized, you should see the message [splitit] FlexFields vX.X.X status: ready. If you don't see that message, look for console errors - usually marked in red color. Make sure you set the debug flag for more detailed error information.