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 payment information, and 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 implementation steps:

1. Look up shopper in our network using shopper lookup function
2. Display the Authentication Component to initiate and complete authentication of shoppers.
3. Display the Payment Carousel Component to display payment information for successfully authenticated shoppers.
4. 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>

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 skipify merchant ID
});

Embedded Components SDK Technical Flow

Shopper look up function

You can implement the lookup function using either:

• Embedded Components SDK lookup function
• API Only Flow's POST /shoppers/lookup

The SDK's 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 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: '',  // get your email from an input field or from logged in shopper information
  phone: '', // optional
};

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

{
    "challengeId": "7dc412fe-54b3-4f18-8985-8a7653ead125",
    "flags": {
        "potentialPaymentMethods": true, // indicates shopper may have payment methods with our financial partners or saved with Skipify
        "phoneRequired": false,
        "partnerProvidedPhone": false
    },
    "metadata": {
        "maskedEmail": "r***@s***.com",
        "maskedPhone": "6866"
    },
    "defaults": {		// default authentication challenge channel
        "destination": "phone",
        "maskedChannel": "6866"
    }
}

The next step is to render theAuthentication Component. If potentialPaymentMethods is false - you can continue to pass that details and the shopper will be prompted to enter their payment details manually.

Authentication Component

The Authentication Component handles shopper authentication process.

Render the Authentication Component at a specified location using the prior lookupResults. Alternatively, you can render the Payment 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. An input field must be used for the overlay option.

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 shoppers:

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

const options = {
  onSuccess: (authenticationResult) => { 
    // store auth result
  },
  onError: (error) => {
  // handle your error flow
  },
  phone: '', // optional to send, unless lookupResults flags{}.phoneRequired = true
  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: "embedded" // or overlay the Authentiation Component
  config: { // Optional
    theme: "light" // or "dark"
    fontFamily: "default", //  or "serif", "sans-serif"
    fontSize: "medium", //   "medium"
	}
};

// Container to render in
const container = document.getElementById("my-container-id");

// render the Authentication Component
skipifySdk.authentication(lookupResults, options),render(container); // note, must be an input field for display mode: overlay

{
    "shopperId": "87b2e945-230a-49cc-a8b7-fd4e042b6385",
    "sessionId": "991bac4b-6f0b-4fa5-912a-c1317497d480"
}

{
    "challengeId": "7dc412fe-54b3-4f18-8985-8a7653ead125",
    "flags": {
        "potentialPaymentMethods": true,
        "phoneRequired": false,
        "partnerProvidedPhone": false
    },
    "metadata": {
        "maskedEmail": "r***@s***.com",
        "maskedPhone": "6866"
    },
    "defaults": {
        "destination": "phone",
        "maskedChannel": "6866"
    }
}

Payment Carousel Component

The Payment 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 Payment Carousel Componentusing either:

• lookupResults if you would like to handle the authentication process and payment info presentation in the same step
• authenticationResult 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.

const options = {
  onSelect: (PaymentSelection) => {
    // the payment info the shopper selects for checkout which will be used to submit the payment later
  },
  onError: (error) => {
  // handle your error here
  },
  orderTotal: 80, // your order total
  phone: '', 	// Optional
  config: { // Optional
    theme: "light" // or "dark"
    fontFamily: "default", //  or "serif", "sans-serif"
    fontSize: "medium", //   "medium"
	}
};

// render the Card Carousel Component at a specified location
const carouselContainer = document.getElementById("merchant-carousel-container");

 // Render the Payment Carousel Component based on auth results or lookup results
 if(authenticationResult)
 {
    skipifySdk.carousel(authenticationResult, options).render(carouselContainer);
 }
 else{ // shopper not authenticated using lookup results instead
    skipifySdk.carousel(lookupResults, options).render(carouselContainer);
 }

{
    "paymentId": "8420a18b-3245-4694-b2fd-e8f3b99bf360",
    "sessionId": "991bac4b-6f0b-4fa5-912a-c1317497d480"
}

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

Payment Submission

Skipify authorizing on your behalf

The default flow is for Skipify to process the transaction on your behalf.

Once the shopper selects a payment method and finalizes the checkout. Use the /v1/payments end point to send an authorization call. Skipify will authorize the transaction by connecting to your PSP and return the results synchronously.

POST /v1/payments

{
  "paymentId": "73c335b2-0dad-4e4a-b10b-950614f80953",
  "amount": "5000",
  "sessionId": "ae5686ad-bcc0-425a-bc84-7e9a142b61d3",
  "merchantReference": "YOUR MERCHANT REFERENCE HERE"
}

{
  "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

Retrieve tokens to authorize outside of Skipify

🚧

Requires approval for and additional configurations

Reach out to your implementation engineer to ensure your use case is approved. Once approved, your merchantAccount will be configured to allow for token retreival

Skipify provides the ability for merchants to submit authorizations themselves to offer true psp agnostic support.

Implement /v1/tokens using sessionId and the selected paymentId to request retrieval of the payment information so that you can then submit the authorization directly to your PSP of choice. The network token and data needed to process the transaction is returned synchronously.

POST /v1/tokens

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

{
  "token": "5454545454545454", 
  "cryptogram": "SGVsbG8gV29ybGQ=",
	"shopperData": {
   	"email": "[email protected]",
   	"phone": "123 453",
   	"firstName": "John",
   	"lastName": "Doe",
   	"uuid": "c72c8efd-3081-4c92-800a-9e91f8805fc7"
 },
  "billingAddress:{
  	"address1": "123 1/2 Duboce Ave",
    "address2": null,
    "city": "San Francisco",
    "countryCode": "US",
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNumber": "2604250218",
    "localityCode": "CA",
    "zipCode": "94103"
    },
  "merchantReference": "ORDER 123" 
}

Theming

Skipify allows merchants to customize the appearance of the Authentication and Carousel components via a config object in options. The available options are:

• theme: Sets the component's color theme. Acceptable values are:
  • "light" (default)
  • "dark"
• fontFamily: Determines the font style. Acceptable values are:
  • "default" (maps to Poppins, default)
  • "serif" (maps to Times New Roman)
  • "sans-serif" (maps to Arial)
• fontSize: Specifies the font theme size. Acceptable values include:
  • "small"
  • "medium" (default)
  • "large"
    
    

  config: { // Optional
    theme: "light" // or "dark"
    fontFamily: "default", //  or "serif", "sans-serif"
    fontSize: "medium", //   "medium"
	}