Overview

Embedded Components are a flexible way to integrate the Skipify Commerce Identity Cloud solution by offering a modular integration design.

The Embedded Components SDK provides prebuilt components, while letting Skipify take care of shopper authentication, presenting autofilled payment information, helping orchestrate payment submission and more.

Design where you want to embed prebuilt UI components to customize your checkout flow, or to further enhance shopper journeys on your website.

🚧
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.

Embedded Components SDK Technical Flow - Summary Overview

High level Embedded Components SDK implementation flow:

Send data to the SDK's built-in email lookup function to look up in-network or recognized shoppers.
Render the Authentication Component to initiate and complete authentication of shoppers.
Render the Card Carousel Component to present in-network and/or manually saved payment information and functionalities for successfully authenticated shoppers.
Once checkout is finalized, use the selected payment method information to submit the payment.

Loading the Skipify Embedded Components SDK

To get started, you can load the SDK using:

<!-- TEST -->
<script src="https://stagecdn.skipify.com/sdk/components-sdk.js"></script>
<!-- LIVE -->
<script src="https://cdn.skipify.com/sdk/components-sdk.js"></script>

$ npm install @{}

$ yarn add @{}

Initializing the Skipify Embedded Components SDK

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

const skipifyComponentsSdk = new window.skipify({
  merchantId: '<your_merchantId>',
});

import Skipify from '@{}';

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

Embedded Components SDK Technical Flow

Email look up function

You can implement the email lookup function using either:

Embedded Components SDK email lookup function
API Only Flow's POST /shoppers/lookup * {beta pg gated}

The SDK's email lookup function will confirm if shoppers are recognized or in-network. This occurs seamlessly behind the scenes and will not impact your UI flow.

Pass shopper identifiers from your checkout UI to the email lookup function. Shopper recognition results are passed back vialookupResults.

If phone was not originally provided but lookupResults requests it:

collect phone in your UI and pass the data upon rendering the Authentication Component
let the Authentication Component prompt the shopper for phone collection

const shopper = {
  email: '[email protected]',
  phone: '', // optional
};

type SkipifyLookupResult = {
  challengeId: string,
  status: LookupStatus,
  metadata?: {
    maskedEmail?: string,
    maskedPhone?: string,
  },
  defaults?: {
    maskedChannel?: string,
    destination?: string,
  }
};

skipifySdk.lookup(shopper).then((results: SkipifyLookupResult) => { 
  // store results object to use in later functions
  const lookupResults = results;
});

The next step is to render theAuthentication Component. You can choose to present the Authentication Component for the below shopper pools based on the LookupStatus

recognized shoppers only -- these shoppers have in-network payment methods that will be presented
also unrecognized shoppers -- these shoppers do not have in-network payment methods to be presented in the Card Carousel Component. Shoppers can manually enter payment info into the Card Carousel.

Authentication Component

The Authentication Component handles the end to end shopper authentication process.

Render the Authentication Component at a specified location using the prior lookupResults. Alternatively, you can render the Card Carousel Component to handle both authentication and payment info presentation in the same location.

Use the displayMode parameter to configure whether the Authentication Component should be embedded or overlay

The SDK presents the shopper with a consent UI to accept the authentication request. Use the optional sendOtp boolean to streamline the experience for returning Skipify users:

true: bypass the consent UI for returning Skipify shoppers and skip straight to the OTP UI
false: show the consent UI for all shoppers

Once the shopper accepts the consent request, Skipify initiates the authentication process (currently OTP). Shopper inputs the necessary information in the UI to complete authentication.

The SDK triggers the appropriate callback to confirm if the shopper was successfully authenticated. AuthenticationResult is passed back if successful.

// successfully authenticated shoppers
type AuthenticationResult = {
  shopperId: string, // UUID representing the shopper
  sessionId: string, // UUID session identifier  
};

// authentication results returned via callbacks
const options = {
  onSuccess: (results: AuthenticationResult) => { 
    // store auth result here
    const authResult = results;
  },
  onError: (error) => {},
  phone: '', // optional to send if status from lookup requests it
  sendOtp: boolean // auto send returning Skipify shoppers to OTP screen, bypassing the consent screen. This will trigger a challenge sent to the shopper upon rendering the component
};

// render the Authentication Component at a specified location
const containerId = "merchant-auth-container";

// render the Authentication Component for recognized shoppers // need to edit for unrecognized use case
skipifySdk.authentication(lookupResults, options),render(containerId);

// successfully authenticated shoppers
type AuthenticationResult = {
  shopperId: string, // UUID representing the shopper
  sessionId: string, // UUID session identifier  
};

// authentication results returned via callbacks
const options = {
  onSuccess: (results: AuthenticationResult) => { 
    // store auth result here
    const authResult = results;
  },
  onError: (error) => {},
  phone: '', // optional to send if status from lookup requests it
  sendOtp: boolean, //  auto send returning Skipify shoppers to OTP screen, bypassing the consent screen. This will trigger a challenge sent to the shopper upon rendering the component
	displayMode: "overlay" // overlay instead of embed the Authentication Component
};

// render the Authentication Component at a specified location
const containerId = "merchant-auth-container";

// render the Authentication Component for recognized shoppers // need to edit for unrecognized use case
skipifySdk.authentication(lookupResults, options),render(containerId); // required for overlay, must be an input field for overlay

You will only be able to render the Card Carousel Component for successfully authenticated shoppers.

Card Carousel Component

The Card Carousel Component offers the following functionalities:

auto filling and presenting the shopper's payment information. This includes cards from in-network financial partners and/or cards the shopper may have manually added to their Skipify account
ability for shoppers to add/edit/delete manually added payment methods and info
ability for the shopper to select which payment method they would like to use for checkout
presenting and handling additional step-ups that the financial partner may require

Render the Card Carousel Componentusing either:

lookupResults if you would like to handle the authentication process and payment info presentation in the same step
AuthenticationResults if the shopper has already been successfully authenticated

The payment method that the shopper selects to use for checkout is summarized in PaymentSelection. Use this information to submit the payment in the final step.

type PaymentSelection = {
  paymentId: string, // represents the payment method
  sessionId: string, // represents the shopper's session
};

const options = {
  onSelect: (results: PaymentSelection) => {
    // the payment info the shopper selects for checkout which will be used to submit the payment later
    const cardResult = results;
  },
  onError: (error) => {},
  orderTotal: 80,
  phone: '', 	// Optional
};

// render the Card Carousel Component at a specified location
const carouselContainerId = "merchant-carousel-container";

// render the Card Carousel Component for recognized shoppers; handle both authentication and payment info presentation steps in the Card Carousel Component
skipifySdk.carousel(lookupResults, options).render(carouselContainerId);

type PaymentSelection = {
  paymentId: string, // represents the payment method
  sessionId: string, // represents the shopper's session
};

const options = {
  onSelect: (results: PaymentSelection) => {
    // the payment info the shopper selects for checkout which will be used to submit the payment later
    const cardResult = results;
  },
  onError: (error) => {},
  orderTotal: 80
};

// render the Card Carousel Component at a specified location
const carouselContainerId = "merchant-carousel-container";

// render the Card Carousel Component for successfully authenticated shoppers
skipifySdk.carousel(AuthenticationResult, options).render(carouselContainerId);

If the shopper's session times out, the Card Carousel Component will request authentication again.

Payment Submission

The shopper decides to finalize checkout on your UI. Implement /v1/payments using PaymentSelection to submit the payment with the previously selected payment info. Skipify will authorize on your behalf in this case.

The /v1/payments sync response will confirm the result of the transaction.

POST /v1/payments

{
  "paymentId": "73c335b2-0dad-4e4a-b10b-950614f80953",
  "amount": "5000",
  "sessionId": "ae5686ad-bcc0-425a-bc84-7e9a142b61d3",
  "merchantReference": "NjghZplGtIx3ap9zskLBhcyyVYyCrjumiWWYY0zRwm_L0BkMRnkx8NLceS49GIx.Gl.ciC"
}

{
  "transactionId": "edFa3DEa-BbA2-4912-fEac-ad0d0fdcd5D1",
  "pspTransactionId": "string",
  "status": "string",
  "amount": "string",
  "initialAmount": "string",
  "pspName": "string",
  "pspSupplemental": "string",
  "pspRawResponse": "string", // the raw response returned from the psp
  "completedAt": "string",
  "pspIdempotentKey": "string",
  "lastFour": "string",
  "networkType": "string",
  "isPartial": true
}

400 payment submission error
{
  "transactionId": "f84d418C-fed6-F6b9-5B76-F0BC97Ae50EC",
  "pspTransactionId": "string",
  "status": "string",
  "amount": "string",
  "initialAmount": "string",
  "pspName": "string",
  "pspSupplemental": "string",
  "pspRawResponse": "string",
  "completedAt": "string",
  "pspIdempotentKey": "string",
  "lastFour": "string",
  "networkType": "string",
  "isPartial": true,
  "pspError": {
    "type": "string",
    "message": "string",
    "pspErrorCode": "string"
  }
}

404 session not found

403 invalid API key

Overview

🚧This section requires you to have set up your merchant account

Embedded Components SDK Technical Flow - Summary Overview

Loading the Skipify Embedded Components SDK

Initializing the Skipify Embedded Components SDK

Embedded Components SDK Technical Flow

Email look up function

Authentication Component

Card Carousel Component

Payment Submission

🚧
This section requires you to have set up your merchant account