SDK Initialization
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 Name | Type | Required | Description |
---|---|---|---|
configuration.userId | String | Yes | The unique identifier of the user, obtained from the /api/create_user endpoint of the Sunlight API. |
configuration.token | String | Yes | The 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.customizationId | String | No | The 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.cardPayload | Object | No | An 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.cardExtraFields | Object | No | An 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:
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.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.- No
cardPayload
field: If neither thecardIdentifier
nor thecardDetails
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