SDK Initialization

Suggest Edits

Importing the Sunlight SDK Library

To get started with the Sunlight SDK, you'll need to include the SDK library in your web application. This can be done by adding the SDK's JavaScript file to your HTML code. Use the following URL to import the SDK library, replacing x.y.z with the desired version number:

<!-- Include the Sunlight SDK JavaScript file -->
<script src="https://connect.sunlightapi.com/sunlight-connect-x.y.z.js"></script>

Initializing the Sunlight SDK

Once the library is included, you can initialize the SDK by calling the SunlightConnect.initialize() method and providing a configuration object that defines the attributes and behaviors of the SDK. The configuration object contains the following fields:

Field NameTypeRequiredDescription
configuration.userIdStringYesThe unique identifier of the user, obtained from the /api/create_user endpoint of the Sunlight API.
configuration.tokenStringYesThe session token associated with the user, obtained from the /api/generate_token endpoint of the Sunlight API. This token is used to authenticate the user session.
configuration.customizationIdStringNoThe identifier of a customization entity, obtained from the /api/customizations/create endpoint of the Sunlight API. This field specifies the list of merchants to display to the user, based on the selected customization. If not provided, the full list of merchants will be displayed.
configuration.cardPayloadObjectNoAn object that specifies the method and content used to receive card information from the user. This field allows you to customize how card data is collected and processed. If not provided, a default card input method will be used. (see below)
configuration.cardExtraFieldsObjectNoAn object that specifies additional information about the user that may be required by certain services during the card switch process. for more information visit Configuring the Card Extra Fields section

The cardPayload object within the SDK configuration specifies how card data will be received and used for the card switch process. This object provides flexibility in determining how card information is collected and processed. The cardPayload object can contain any of the following optional fields:

  1. cardIdentifier: A reference to the card details. Sunlight will exchange this identifier with the actual card details during the card switch process. This option is useful when you have a secure way to reference stored card details.
  2. cardDetails: The full card details, including the primary account number (PAN), card verification value (CVV), and expiration date. This option is useful when you have the full card details available for the switch process.
  3. No cardPayload field: If neither the cardIdentifier nor the cardDetails field is provided, the SDK will display a manual card details form for the user to input their card information. This option is useful for testing the SDK and for cases where card details need to be collected directly from the user.

Here are examples of how to configure the cardPayload object for each of the options:

Using a Card Identifier

SunlightConnect.initialize({
  // Other configuration fields...
  cardPayload: {
    cardIdentifier: 'your-card-reference'
  }
});

Using Card Details

SunlightConnect.initialize({
  // Other configuration fields...
  cardPayload: {
    cardDetails: {
      pan: '4111111111111111',
      cvv: '123',
      expDate: '12/25'
    }
  }
});

Using the Default Manual Card Entry Form

SunlightConnect.initialize({
  // Other configuration fields...
  // No cardPayload field provided
});

By configuring the cardPayload object according to your use case, you can tailor the card switch process to meet the specific needs of your application and users.

Here is a full example of how to initialize the Sunlight SDK with cardDetails object:

  // Initialize the Sunlight SDK with the required configuration object
  SunlightConnect.initialize({
    userId: '9c9e7402-b642-4b99-98ec-865e5bcea4c2', // Replace with the actual external_user_id
    token: 'your-session-token',   // Replace with the actual session token
    customizationId: '9K69Q5BYC8YW',  // Replace with the actual customization ID, if applicable
    cardPayload: {
    	cardDetails: {
      	pan: '4111111111111111',
      	cvv: '123',
      	expDate: '12/25'
    	}
  }
  });

After the SDK is initialized, you can open the SDK for the users to be able to use it and connect their services:

//application launch 
SunlightConnect.initialize({/* configuration object */}).open();

SDK Display Modes

By default, the SDK opens in a popup mode, providing users with a separate window to interact with the card switch process. However, you have the flexibility to embed the SDK within a specific HTML element on your page for a more integrated user experience.

To embed the SDK within a specific HTML element, simply pass the ID of the element as an argument to the open() function. For example:

<body>
  <div id="my-amazing-div"></div>
</body>
<script>
  // Embed the SDK inside the element with ID "my-amazing-div"
  sunlightConnect.open('my-amazing-div');
</script>

On the other hand, if you do not provide any HTML element ID to the open() function, the SDK will open in a popup mode:

// No element ID passed, invoking popup mode
sunlightConnect.open();

Updated 2 months ago