Get started

Learn how to implement the Skipify SDK

Introduction

The Email lookup and Skipify Button use the Skipify SDK for a range of features. This guide shows you how to set up the SDK on your website. The various features of the SDK are further enumerated in additional articles in this section.

🚧

This section requires you to have set up your Skipify Portal

Haven't set that up yet? No worries! Reach out to your friendly implementation engineer and they'll make sure your account is properly set up.

Loading the Skipify SDK

Skipify provides several options to integrate the Connected Checkout experience into your website. To get started, you can load the SDK using:

<!--- TEST ---!>
<script src="https://storage.googleapis.com/checkout-sdk-stage/custom/custom.iife.js"></script>
<!--- LIVE ---!>
<script src="https://storage.googleapis.com/checkout-sdk/custom/custom.iife.js"></script>
$ npm install @skipifycheckout/checkout-sdk
$ yarn add @skipifycheckout/checkout-sdk

Initializing the Skipify SDK

Once you have completed the installation using one of the methods above, you can initialize the Skipify client SDK using:

const skipifySdk = new window.skipify({
  merchantId: '<your-merchantId>',
});
import Skipify from '@skipifycheckout/checkout-sdk';

const skipifySdk = new Skipify({
  merchantId: '<your-merchantId>',
});

Requirements to use the Skipify SDK

Merchant Domains

❗️

Important

Provide relevant domains for testing in lower environments that will need to be whitelisted by your Skipify Implementation Engineer

Localhost will need to be added for local development (ex. https://localhost:5001)
If you are using Ionic (iOS) add (capacitor://localhost as your merchant domain)

In Production, domains are added in the Skipify Merchant Portal.

Merchants are required to provide a set of allowed domains that Skipify uses to validate before initializing the Skipify SDK. Only configured domains will be able to leverage the Skipify SDK. You will need to provide that information to your implementation specialist during onboarding.

Skipify Email Lookup

The Skipify Email Lookup will launch the Skipify checkout experience using any email field on your checkout page. To enable the Lookup, you will need to use the SDK’s email method to return an instance of the Skipify Lookup component. You can then use the enable method to set up the Lookup on your chosen input field.

skipifySdk.email("your merchant reference here").enable( < your - input - object > );

Methods

  • email is used to return the Skipify email lookup instance, you need to pass your Skipify merchant ID
  • enable is used to enable the listener on your input field, pass your input object

Skipify Button

To enable the Skipify Button on your website, you will need to use the button method to return a Skipify Button component instance. You can then use the render method to mount the button on your website on any page you choose. The button can render in any container element and the component will inherit the width of the container size.

Image showing a store web page with the Skipify button displayed at checkout
skipifySdk.button("your-merchantReference").render( < your container > );

Methods

  • button is used to return the Skipify Button component instance, you need to pass your unique merchant reference
  • render is used to add the button on your website pass your container for the button to be rendered

Synchronous Webhooks

Before Skipify can submit a payment on your behalf, we need to gather some information about the order. Since this information may differ between businesses, we require that you implement callbacks so that Skipify can obtain the information needed to facilitate a seamless user experience.

Skipify servers will send a request to your specified URL when needed. You will need to provide your implementation engineer a callback URL(s).

Overview

There are three events available via the SDK:

  • ORDER_RESOLVE - defines amount per line items or cart
  • ORDER_CHANGE - defines tax, shipping address, discounts
  • ORDER_VERIFY - validation before payment processing

Event Descriptions

EventImplementation requiredResponse requiredDescription
ORDER_RESOLVEyesyesThis event will be used to return further details about your order
ORDER_CHANGEnoyesThis webhook is used to retrieve additional information about the order as it relates to shipping, tax & discount adjustments, promos or any order quantity changes by your customer
ORDER_VERIFYnoyesThis webhook is used to validate the order details before a payment is processed. It’s an additional check to ensure information is accurate.

Event standard request parameters

paramdescription
eventNameSTRING: Skipify event code name
eventTypeSTRING: sync
liveBoolean: true or false
payload
{
merchantReference
merchantID
skipifyReference
metadata
}
merchantReference : STRING: Your unique reference related to the order or cart. This value will be passed to merchants PSP
merchantID: STRING: Your Skipify merchant ID
skipifyReference: STRING: Skipify unique identifier
metadata : any object

ORDER_RESOLVE Event

This event will be used to return more details about the order. Skipify will pass your unique merchant reference you defined when you initiated the SDK along with other parameters below:

Sample Request/Response Parameters

{
"merchantReference": "YOUR MERCHANT REFERENCE",
"merchantId":"YOUR MERCHANT ID",
"eventName": "ORDER_RESOLVE",
"eventType": "sync",
"live": false
}
 {
	"Cart": [
		{
			"itemID": "string",
			"title": "string 1",
			"quantity": 123, // integer
			"amount": {
				"value": 1,  // integer
				"uom": "USD"
			},
			"image": {
				"url": "URL HERE",
				"alt": "text"
			}
		},
		{
			"itemID": "string",
			"quantity": 456, // integer
			"amount": {
				"value": 2, // integer
				"uom": "USD"
			},
			"title": "string 2",
			"image": {
				"url": "URL HERE",
				"alt": "text"
			}
		}
	]
}

Request Parameters

For this event the request parameters are only the standard parameters

paramdescription
eventNameSTRING: Skipify event code name
eventTypeSTRING: sync
liveBoolean: true or false
payload
{
merchantReference
merchantID
skipifyReference
metadata
}
merchantReference : STRING: Your unique reference related to the order or cart. This value will be passed to merchants PSP
merchantID: STRING: Your Skipify merchant ID
skipifyReference: STRING: Skipify unique identifier
metadata : any object

Response Parameters

Parameter NameTypeDescription
cartcart objectThis will be the cart items

Cart Object Parameters

Parameter NameTypeDescription
titlestringThe title of the item(s)
itemIDstringThis is the ID of your line item
productTypestringThe type of product

Example: shirt, pizza
quantityintegerLine item quantity
descriptionstringThis will be the cart items
priceunit objectThese are the amounts for each product / item
imageprice object{url:"", alt:""}
Unit object Parameters
Parameter NameTypeDescription
valueintegerThe value of an item. The last two digits are cents, so $20.50 would be sent as 2050.
uomstringThree letter code to identify the currency. Skipify is only processing transactions in USD at this time. Make sure you are passing USD as a value.
image object Parameters
Parameter NameTypeDescription
urlstringUrl of the image
altstringA text to be displayed on hover

ORDER_CHANGE EVENT

This event will be used to return more details about the order. Skipify will pass your unique merchant reference you defined when you initiated the SDK along with other parameters below:

Sample Request/Respinse Parameters

{
	"merchantReference": "YOUR MERCHANT REFERENCE",
  "merchantId":"YOUR MERCHANT ID",
	"eventName": "ORDER_CHANGE",
	"eventType": "sync",
	"live": false,
  "cart" :[], // your cart details here
	"shippingAddress": {  
 		"firstName": "String",
 		"lastName": "String",
 		"address1": "String",
 		"address2": "String",
 		"city": "String",
 		"localityCode": "String",
 		"zipCode": "String",
 		"countryCode": "String"
	},
	"shippingOptions" : {},	// can be empty
	"taxDetails": {},	// can be empty
	"discountCode": "String",
}
  {
	"cart": [], // your cart details here, check previous event for example
	"shippingAddress": {
		"firstName": "String",
		"lastName": "String",
		"address1": "String",
		"address2": "String",
		"city": "String",
		"localityCode": "String",
		"zipCode": "String",
		"countryCode": "String"
	},
	"shippingOptions": [
		{
			"id": "String", 
			"optionName": "String",
			"optionType": "String",
			"defaultFee": {
				"value": 1,  // integer
				"uom": "String"
			}
		}
	],
	"taxDetails": [
		{
			"systemOfOriginId": "String",
			"value": 1,  // integer
			"uom": "String",
			"code": "String"
		}
	],
	"discountAmount": {
		"value": 1,  // integer
		"uom": "String"
	}
}

Request Parameters

For this event the request parameters are the standard parameters along with the following

Parameter NameTypeDescription
cartcart objectThis will be the cart items
shippingAddressshippingAddress objectThe shipping address details
Example:
{
"firstName": "John",
"lastName": "Doe",
"address1": "123 Main St",
"address2": "Apt 1",
"city": "San Francisco",
"localityCode":"CA",
"zipCode": "94105",
"countryCode":"US"
}
shippingOptionsshippingOptions objectAn array of Shipping details
taxDetailstaxDetails objectAn array of Tax details
discountCodeStringThis is the discount code that the user inputs on the Skipify experience if applicable.

Cart Object Parameters

Parameter NameTypeDescription
titlestringThe title of the item(s)
itemIDstringThis is the ID of your line item
productTypestringThe type of product

Example: shirt, pizza
quantityintegerLine item quantity
descriptionstringThis will be the cart items
priceunit objectThese are the amounts for each product / item
imageprice object{url:"", alt:""}

ShippingAddress Object Parameters

Parameter NameTypeDescription
firstnamestringFirst Name
lastnamestringLast Name
address1stringStreet address
address2stringStreet address
citystringCity name
localityCodestringLocality code could be state, region, territory, province, etc...
zipCodestringZip code
countryCodestringCountry Code

ShippingOptions Object Parameters

Parameter NameTypeDescription
idstringThe unique ID of the shipping method
optionNamestringThe name associated with the shipping method

Example: USPS Ground, UPS Express, etc
defaultFeeobjectThe price associated with the shipping method
optionTypestring‘FLAT’, ‘PERITEM’, ‘WEIGHT_RANGE’, ‘PRICE_RANGE’

TaxDetails Object Parameters

Parameter NameTypeDescription
valueintegerThe value of an item. The last two digits are cents, so $20.50 would be sent as 2050.
uomstringThree letter code to identify the currency. Skipify is only processing transactions in USD at this time. Make sure you are passing USD as a value.

Response Parameters

Parameter NameTypeDescription
cartcart objectThis will be the cart items
shippingAddressshippingAddress objectThe shipping address details
shippingOptionsshippingOptions objectAn array of Shipping details
taxDetailstaxDetails objectAn array of Tax details
discountAmountdiscountAmount objectThis is the discount value

Cart Object Parameters

Parameter NameTypeDescription
titlestringThe title of the item(s)
itemIDstringThis is the ID of your line item
productTypestringThe type of product

Example: shirt, pizza
quantityintegerLine item quantity
descriptionstringThis will be the cart items
priceunit objectThese are the amounts for each product / item
imageprice object{url:"", alt:""}

ShippingAddress Object Parameters

Parameter NameTypeDescription
firstnamestringFirst Name
lastnamestringLast Name
address1stringStreet address
address2stringStreet address
citystringCity name
localityCodestringLocality code could be state, region, territory, province, etc...
zipCodestringZip code
countryCodestringCountry Code

ShippingOptions Object Parameters

Parameter NameTypeDescription
idstringThe unique ID of the shipping method
optionNamestringThe name associated with the shipping method

Example: USPS Ground, UPS Express, etc
defaultFeeobjectThe price associated with the shipping method
optionTypestring‘FLAT’, ‘PERITEM’, ‘WEIGHT_RANGE’, ‘PRICE_RANGE’

TaxDetails Object Parameters

Parameter NameTypeDescription
valueintegerThe value of an item. The last two digits are cents, so $20.50 would be sent as 2050.
uomstringThree letter code to identify the currency. Skipify is only processing transactions in USD at this time. Make sure you are passing USD as a value.

DiscountAmount Object

Parameter NameTypeDescription
valueintegerThe value of an item. The last two digits are cents, so $20.50 would be sent as 2050.
uomstringThree letter code to identify the currency. Skipify is only processing transactions in USD at this time. Make sure you are passing USD as a value.

ORDER_VERIFY Event

his event is used to validate the order details before a payment is processed. It’s an optional additional check you can use to ensure the order can be completed before the payment is authorized. This is helpful to use with rapidly changing inventory or order lifecycle changes.

Request Parameters

Currently, Skipify will pass the order information compiled from other events including product information, shipping address, pricing information, and if applicable, shipping options and discount codes.

example:

{
	"merchantReference": "YOUR MERCHANT REFERENCE",
	"merchantId": "YOUR MERCHANT ID",
	"eventName": "ORDER_VERIFY",
	"eventType": "sync",
	"live": false,
	"cart": [],   //your cart details here
	"shippingAddress": {
		"firstName": "String",
		"lastName": "String",
		"address1": "String",
		"address2": "String",
		"city": "String",
		"localityCode": "String",
		"zipCode": "String",
		"countryCode": "String"
	},
	"shippingOptions": [
		{
			"id": "String",
			"optionName": "String",
			"optionType": "String",
			"defaultFee": {
				"value": 1000, // integer
				"uom": "USD"
			}
		}
	],
	"taxDetails": [
		{
			"systemOfOriginId": "String",
			"value": 500, // integer
			"uom": "USD",
			"code": "String" 
		}
	],
	"discountAmount": {
		"value": 0, //integer
		"uom": "USD"
	}
}

Response Parameters

Skipify needs to know if the order information passed in the request can be fulfilled.

Valid responses could be:

  • An empty array that signifies the order can be fulfilled
  • Passing the same properties back

📘

Note

An error produced during this step means that the order can not be fulfilled. Skipify will prompt the user to make adjustments to the order before triggering this callback again.


Skipify baner with link to contact us form