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.

To use Hosted Fields, you initiate an installment plan on your backend server, while simultaneously calling the Hosted Fields UI library on your front end. When your shopper types in a card number on your front end and clicks Continue, Splitit automatically evaluates their creditworthiness and presents them with plans for which they are eligible. They then select a plan, accept terms and conditions and a privacy policy, and click Pay.

Hosted Fields Demo

Step-By-Step Usage Guide

1. Establish a Plan on Your Server

A. Authenticate

Fetch a bearer token using the instructions here. 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 Hub (Merchant Hub -> Merchants Management -> Select Merchant -> Terminals), as well as any data you'd like to pass initially. In the object that is returned, note the plan number. (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 (sandbox):

<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 
        paymentButton: {    // hides payment button if you are using a custom implementation
            isCustom: false   
        },
        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), 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': '#000000',  // changes color of learn more text, continue button, pay button, edit credit card details text, plan details text/hide command, terms and conditions text/title, privacy policy text/title  
  '--spt-color-pay-button': '#ff007f',  // changes color of activated buttons
  '--spt-color-pay-button-text': '#000000', // changes text color on pay button and continue button
  '--spt-color-pay-button-disabled': '#39FF14',  // changes color of buttons when disabled
  '--spt-color-border-focused': '#39FF14',  // changes border color of full name field, card number field, expiration date field and CVV field when they are in focus
  '--spt-color-border-idle': 'rgba(255, 108, 80, 0.54)',  // changes border color of full name field, card number field, expiration date field and CVV field when they are not in focus
  '--spt-color-border-error': '#39FF14',  //changes border color of full name field, card number field, expiration date field and CVV field when an error is triggered 
  '--spt-color-error': '#39FF14',  // changes color of error texts pertaining to full name field, card number field, expiration date field and CVV field,
  '--spt-color-text': '#39FF14', // changes color of text designated by "primary-text" class,
  '--spt-color-labels': '#39FF14', // changes color of labels above entire form; also labels within full name field, card number field, expiration date field and CVV field; and labels within credit card and payment plans sections on second page
 '--spt-color-main-shade': '#39FF14', //changes highlight color behind installment choices
 '--spt-color-link': 'rgb(57, 255, 20)' // changes mouseover color of Learn More
 '--spt-color-warning': '##39FF14'   // changes warning color
 '--spt-color-info-holder': 'rgba(8, 124, 208, 0.15)', // changes color of background of bottommost info box
 '--spt-color-linear-gradient-from':
    'linear-gradient(277deg, rgba(8, 124, 208, 0) -0.85%, rgba(8, 124, 208, 0.15) 100%), var(--card-primary, #fff)',
 '--spt-color-linear-gradient-to':
    'linear-gradient(277deg, rgba(8, 124, 208, 0.15) -0.85%, rgba(8, 124, 208, 0) 100%), var(--card-primary, #fff)' //sets gradient color behind selected installment option
})

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)