Hosted Fields

Overview

Splitit's Hosted Fields is a unique, low-PCI compliance product that allows you to fully integrate Splitit into the checkout process on your website, both stylistically and functionally. Hosted Fields utilize individual iFrames plugged directly into the Splitit servers, but since you can extensively customize them, they look and feel like they are native to your site.

Hosted Fields Demo

Usage

To use Hosted Fields, you begin by starting a plan using Splitit APIs on your server. A plan number is returned that you then send to your front end. On your front end, you import the Hosted Fields library and generate a stylable Hosted Fields instance by interacting with your browser's window object, providing it with the plan number. You can subsequently manipulate your Hosted Fields instance in various ways.

Step-by-Step Guide

1. Establish a Plan on Your Server

A. Authenticate

Fetch a bearer token using the instructions under "Authentication". Attach it as a header to all subsequent API calls.

B. Initiate the Plan

Initiate a new Splitit plan, adding your own TerminalId from your merchant portal as well as any data you'd like to pass initially. In the object that is returned, note the plan number in the field InstallmentPlanNumber. (For testing purposes, you can generate plan numbers at the Splitit test plan URL).

2. Set Up Your Front End

A. Add a Container <div>

Set a <div> in your HTML to receive your Hosted Fields:

<div id="flex-form"></div>

B. Import the Hosted Fields Library:

<script src="https://flex-form.sandbox.splitit.com/flex-form.js"></script>

C. Spawn a Hosted Fields instance

Spawn a Hosted Fields instance by calling a function on your browser's window object:

var hostedFields = window.Splitit.FlexForm.setup({
		showOnReady: true,  // optional; show form immediately or not
        container: 'flex-form', //this is variable but must match your HTML
        ipn: "{{ the plan number from your Initiate call }}",
        culture: 'en-US', // language/culture; see https://developers.splitit.com/on-site-messaging/installation#languages-supported-by-on-site-messaging-iso-639-1-values for a list
        nameField: {   // optional
			hide: true										
		},
		paymentButton: {    // hides payment button if you are using a custom implementation
			isCustom: true   
		}
		numberOfInstallments: 5,  // optional
        billingAddress: {   // optional
            addressLine: '260 Madison Avenue.',
            addressLine2: 'Apartment 1',
            city: 'New York',
            state: 'NY',
            country: 'USA',
            zip: '10016'
        },
        consumerData: {  //optional
            fullName: 'John Smith',
            email: 'JohnS@splitit.com',
            phoneNumber: '1-844-775-4848',
            cultureName: 'en-us'
        },
        onError(error) {  //Callback for error
            alert('ERROR - ' + JSON.stringify(error));
        },
        onSuccess(data) {  //Callback for success
            alert('SUCCESS - ' + JSON.stringify(data));
            console.log('data:', data);
        }
	   }).ready((manage) => {
		console.log('~ READY CALLBACK', manage);
	});
    

In your instance, you must provide your container name, the Installment Plan Number from your backend call, your desired culture (i.e., language), your number of desired installments, along with as much shopper data as you'd like to send.

You can add any code you'd like after .ready, which will execute once the instance has completely spawned.

NOTE: You should spawn the instance only when your shopper selects Splitit as a payment method, not when the page is loaded.

D. Style Your Hosted Fields Instance

Style your Hosted Fields by calling window.Splitit.FlexForm.setStyles() and passing in an object with your desired styles:

window.Splitit.FlexForm.setStyles({
'--spt-color-primary': '#732c70',  //changes color of all installments texts, “total” text, as well as checkbox background
'--spt-color-pay-button': '#000',  //changes color of activated pay button
'--spt-color-pay-button-text': '#fff', /// changes text color on pay button 
'--spt-color-pay-button-disabled': '#00000033',  //changes color of pay button when it’s disabled (which it is by default before shopper checks out)
'--spt-color-border-focused': '#732c70',  // changes border color of card number field, expiration date field and CVV field when they are in focus
'--spt-color-border-idle':  //changes border color of card number field, expiration date field and CVV field when they are not in focus
'rgba(203, 203, 203, 0.54)', 
'--spt-color-border-error': '#ff0000',  //changes border color of card number field, expiration date field and CVV field when an error is triggered 
'--spt-color-error': '#ff0000',  // changes color of error texts pertaining to card number field, expiration date field and CVV field
'--spt-color-labels': '#757575', //changes color of labels above card field, expiration date field and CVV field
'--spt-color-main-shade': '#ece8ee', //changes highlight behind installment choices
'--spt-color-link': 'rgb(125, 166, 222)' // changes color of link texts, i.e. "Learn More", "Terms and Conditions" and "Privacy Policy"
'--spt-color-text': '#000' // changes color of text designated by "primary-text" class
})

E. Access Additional Hosted Fields Functionality

(This section assumes that you have spawned a Hosted Fields instance that you attached to a variable hostedFields.)

1. Change the language ("culture") of your Hosted Fields by calling:

hostedFields.changeLanguage:({your desired language})

See list of languages/cultures here.

2. Trigger the pay button from an element other than the pay button by calling:

hostedFields.pay()

3. Activate a callback that will execute when your Hosted Fields instance is ready by calling:

hostedFields.ready(console.log('form is ready'))

4. Hide your Hosted Fields by calling:

hostedFields.hide()

5. Show your Hosted Fields by calling:

hostedFields.show()

6. Toggle (show/hide) your Hosted Fields by calling:

hostedFields.toggle()

7. Return a boolean declaring whether all your Hosted Field inputs are valid (and T&Cs are checked) by calling:

console.log(hostedFields.isValid())

8. Check if all of your Hosted Fields inputs are valid and highlight the ones that aren't valid by calling:

hostedFields.triggerValidation()

9. Fetch the number of installments that has been selected by calling:

hostedFields.getSelectedNumInstallments()

10. Get the active plan's installment plan number (IPN) by accessing the variable ipn:

console.log(hostedFields.ipn)

11. Destroy your Hosted Fields instance by calling:

hostedFields.destroy()

12. Update the number of installments by calling the following function, and providing an integer:

hostedFields.updateInstallmentOption({number of installments})

13. Mark the Terms and Conditions field as signed by calling:

hostedFields.updateTermsSigned()

14. Call a function to update address and shopper details by calling:

  var data = {
    billingAddress: {
    	addressLine: 'addressline string',
    	addressLine2: 'addressline2 string',
    	city: 'city string',
    	state: 'state string',
    	country: 'country string',
    	zip: 'zip string'
  }, 
   consumerData: {
    	fullName: 'fullname string',
    	email: 'email string',
    	phoneNumber: 'phone number string',
    	cultureName: 'culture name string'
   } 
  }

hostedFields.updateDetails(data)