Get started with the Skipify SDK
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 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.
- Set up your merchant account including relevant configurations for your use case
- Implement the Email Look up, Skipify Button via the Skipify SDK which includes synchronous webhooks
- 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. PassmerchantReference
, 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. PassmerchantReference
, 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 | Implementation required | Response required | Description |
---|---|---|---|
ORDER_RESOLVE | yes | yes | This event will be used to return further details about your order |
ORDER_CHANGE | no | yes | This 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_VERIFY | no | yes | This 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
param | description |
---|---|
eventName | STRING: Skipify event code name |
eventType | STRING: sync |
live | Boolean: true or false |
payload | Object 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 cart : cart object shippingOption: selected shipping option ID discountCode : discount code String |
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
param | description |
---|---|
eventName | STRING: Skipify event code name |
eventType | STRING: sync |
live | Boolean: true or false |
payload | Object 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 cart : cart object shippingOption: selected shipping option ID discountCode : discount code String |
Response Parameters
Parameter Name | Type | Description |
---|---|---|
cart | cart object | This will be the cart items |
Cart Object Parameters
Parameter Name | Type | Required | Description |
---|---|---|---|
title | string | ✅ | The title of the item(s) |
itemId | string | ✅ | This is the ID of your line item |
productType | string | ✅ | The type of product Example: shirt, pizza |
quantity | integer | ✅ | Line item quantity |
description | string | ✅ | This will be the cart items |
price | unit object | ✅ | These are the amounts for each product / item |
image | price object | {url:"", alt:""} |
Unit object Parameters
Parameter Name | Type | Required | Description |
---|---|---|---|
value | integer | ✅ | The value of an item. The last two digits are cents, so $20.50 would be sent as 2050. |
uom | string | ✅ | Three 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 Name | Type | Description |
---|---|---|
url | string | Url of the image |
alt | string | A text to be displayed on hover |
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
Parameter Name | Type | Description |
---|---|---|
cart | cart object | This will be the cart items |
shippingAddress | shippingAddress object | The shipping address details Example: { "firstName": "John", "lastName": "Doe", "address1": "123 Main St", "address2": "Apt 1", "city": "San Francisco", "localityCode":"CA", "zipCode": "94105", "countryCode":"US" } |
shippingOptions | shippingOptions object | An array of Shipping details |
taxDetails | taxDetails object | An object of Tax details |
discountCode | String | This is the discount code that the user inputs on the Skipify experience if applicable. |
Cart Object Parameters
Parameter Name | Type | Required | Description |
---|---|---|---|
title | string | ✅ | The title of the item(s) |
itemId | string | ✅ | This is the ID of your line item |
productType | string | ✅ | The type of product Example: shirt, pizza |
quantity | integer | ✅ | Line item quantity |
description | string | ✅ | This will be the cart items |
price | unit object | ✅ | These are the amounts for each product / item |
image | price object | {url:"", alt:""} |
ShippingAddress Object Parameters
Parameter Name | Type | Description |
---|---|---|
firstname | string | First Name |
lastname | string | Last Name |
address1 | string | Street address |
address2 | string | Street address |
city | string | City name |
localityCode | string | Locality code could be state, region, territory, province, etc... |
zipCode | string | Zip code |
countryCode | string | Country Code |
ShippingOptions Object Parameters
Parameter Name | Type | Description |
---|---|---|
id | string | The unique ID of the shipping method |
optionName | string | The name associated with the shipping method Example: USPS Ground, UPS Express, etc |
defaultFee | object | The price associated with the shipping method |
optionType | string | ‘FLAT’, ‘PERITEM’, ‘WEIGHT_RANGE’, ‘PRICE_RANGE’ |
TaxDetails Object Parameters
Parameter Name | Type | Description |
---|---|---|
value | integer | The value of an item. The last two digits are cents, so $20.50 would be sent as 2050. |
uom | string | Three 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 Name | Type | Description |
---|---|---|
cart | cart object | This will be the cart items |
shippingAddress | shippingAddress object | The shipping address details |
shippingOptions | shippingOptions object | An array of Shipping details |
taxDetails | taxDetails object | An array of Tax details |
discountAmount | discountAmount object | This is the discount value |
Cart Object Parameters
Parameter Name | Type | Required | Description |
---|---|---|---|
title | string | ✅ | The title of the item(s) |
itemId | string | ✅ | This is the ID of your line item |
productType | string | ✅ | The type of product Example: shirt, pizza |
quantity | integer | ✅ | Line item quantity |
description | string | ✅ | This will be the cart items |
price | unit object | ✅ | These are the amounts for each product / item |
image | price object | {url:"", alt:""} |
ShippingAddress Object Parameters
Parameter Name | Type | Description |
---|---|---|
firstname | string | First Name |
lastname | string | Last Name |
address1 | string | Street address |
address2 | string | Street address |
city | string | City name |
localityCode | string | Locality code could be state, region, territory, province, etc... |
zipCode | string | Zip code |
countryCode | string | Country Code |
ShippingOptions Object Parameters
Parameter Name | Type | Description |
---|---|---|
id | string | The unique ID of the shipping method |
optionName | string | The name associated with the shipping method Example: USPS Ground, UPS Express, etc |
defaultFee | object | The price associated with the shipping method |
optionType | string | ‘FLAT’, ‘PERITEM’, ‘WEIGHT_RANGE’, ‘PRICE_RANGE’ |
TaxDetails Object Parameters
Parameter Name | Type | Description |
---|---|---|
value | integer | The value of an item. The last two digits are cents, so $20.50 would be sent as 2050. |
uom | string | Three 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 Name | Type | Required | Description |
---|---|---|---|
value | integer | ✅ | The amount of the Discount for the discountCode applied for this order (if applicable). The last two digits are cents, so $20.50 would be sent as 2050. |
uom | string | ✅ | Three 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
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.
Updated about 19 hours ago