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 merchant account

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.

1. Set up your merchant account including relevant configurations for your use case
2. Implement the Email Look up, Skipify Button via the Skipify SDK which includes synchronous webhooks
3. Implement asynchronous webhooks

SDK Technical Flow

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 engineer during onboarding.

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>',
});

Skipify Email Lookup

Email Lookup will launch the Connected Checkout experience for recognized shoppers using any email field on your checkout page.

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

Methods

• email is used to configure Email Lookup. Pass merchantReference, your unique reference related to the order or cart.
• enable is used to activate the Email Lookup functionality on your specified input field.

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.

skipifySdk.button("your-merchantReference").render( < your-container > );

Methods

• button is used to confirgure the Skipify Button component instance. Pass merchantReference, your unique reference related to the order or cart.
• render is used to add the button on your website via the specified container.

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

Event standard request parameters

ORDER_RESOLVE Event

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

Example Request and Response for ORDER_RESOLVE

{
"eventName": "ORDER_RESOLVE",  
"eventType": "sync",
"live": false, // this can be either true or false depending on the environment 
"payload": {
  "merchantReference": "YOUR MERCHANT REFERENCE", // this is your unique order or cart reference
  "merchantId": "YOUR MERCHANT ID" // this is your skipify merchant ID
 }
}

 {
	"cart": [
		{
			"itemId": "IT123123",
			"title": "Line item one",
			"quantity": 1, // integer
      "productType": "physical",
			"price": {
				"value": 1050,  // $10.50
				"uom": "USD"
			},
			"image": {
				"url": "URL HERE",
				"alt": "text"
			}
		},
		{
			"itemId": "IT4435343",
      "title": "line item 2",
			"quantity": 2, // integer
      "productType": "physical",
			"price": {
				"value": 2125, // $21.25 
				"uom": "USD"
			},
			"image": {
				"url": "URL HERE",
				"alt": "text"
			}
		}
	]
}

 {
	"cart": [
		{
			"itemId": "ORDER12312441232",
			"title": "ORDER 512300",
			"quantity": 1,    // integer
      "productType": "physical",
			"price": {
				"value": 5300,  // total order amount $53.00
				"uom": "USD"
			},
			"image": {            // optional
				"url": "URL HERE",  // optional
				"alt": "text"      // optional
			}
		}
	]
}

Request Parameters

For this event the request parameters are only the standard parameters

Response Parameters

Cart Object Parameters

Unit object Parameters

image object Parameters

ORDER_CHANGE EVENT

This event will be used to return more details and/or shopper-made updates 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

{
"eventName": "ORDER_CHANGE",
"eventType": "sync",
"live": false,
"payload": {
  "cart" :[], // your cart details here
  "shippingAddress": {  
    "firstName": "John",
    "lastName": "Doeg",
    "address1": "123 main street",
    "city": "New York",
    "localityCode": "NY",
    "zipCode": "10001",
    "countryCode": "USA"
  },
   "merchantReference": "YOUR MERCHANT REFERENCE",
   "merchantId":"YOUR MERCHANT ID",
   "shippingOption" : "Selected shipping option ID",
   "discountCode": "discount code entered by shopper" // wont be sent if shipper hasnt entered one
  }
}

{
"shippingOptions": [
 { "optionType": "FLAT", "id": "fast-option-id", "optionName": "Fast Shipping", "defaultFee": { "value": 800, "uom": "USD" } },      
 { "optionType": "FLAT", "id": "free-option-id", "optionName": "Free Shipping", "defaultFee": { "value": 900, "uom": "USD" } }
],
"taxDetails": [
 {
  "value": 200,  // minor unit integer
  "uom": "USD"
 }
],
"discountAmount": {
 "value": 1000,  // minor unit integer
 "uom": "USD"
}
}

Request Parameters

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

Cart Object Parameters

ShippingAddress Object Parameters

ShippingOptions Object Parameters

TaxDetails Object Parameters

Response Parameters

Cart Object Parameters

ShippingAddress Object Parameters

ShippingOptions Object Parameters

TaxDetails Object Parameters

DiscountAmount Object

ORDER_VERIFY Event

This 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

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.