Installation of SDK
Before You Start
Fully integrating EDS across your site requires an integrationKey. Your account manager will provide you with these credentials before you begin the integration process.
Step 1: Add JS script to your site
Add the following js script to your base template so that it loads on all pages, replacing with the integrationKey your account manager provided.
<!-- Load this inline script before making any calls to the SDK -->
<!-- The inline script stubs out the SDK methods, so calls can be made to the SDK before it is finished loading -->
<script>
if(window.BreadPayments=window.BreadPayments||{snippetVersion:"1.3.1"},!BreadPayments.init){var b=BreadPayments;b.on=function(){var t=["on"].concat(Array.prototype.slice.call(arguments));(b.q=b.q||[]).push(t)},b.submitRtps=function(){var t=["submitRtps"].concat(Array.prototype.slice.call(arguments));(b.q=b.q||[]).push(t)},b.setup=function(){var t=["setup"].concat(Array.prototype.slice.call(arguments));(b.q=b.q||[]).push(t)},b.checkout=function(){var t=["checkout"].concat(Array.prototype.slice.call(arguments));(b.q=b.q||[]).push(t)},b.registerPlacements=function(){var t=["registerPlacements"].concat(Array.prototype.slice.call(arguments));(b.q=b.q||[]).push(t)}}
</script>
<script
src="https://brand-sdk.kmsmep.com/unified/unified.sdk.js"
async
data-bread-payments-key="<YOUR INTEGRATION KEY>">
</script>
Note: the script url is subject to change
Adding the js script will install a namespace, BreadPayments, to the window which can be accessed as window.BreadPayments. The namespace will include the setup(), on(), and submitRtps() methods (expanded on in the next sections).
Step 2: Adding and Configuring Placements
Adding Placements Through the Customer Experience
Placements are dynamic text callouts which notify customers of their financing options and will launch the prequalification process for customers to apply for CARD and Bread Pay INSTALLMENT products when clicked.
To render a Placement, add a
<div>element where you’d like to display the callout on your site. The Placement<div>will require an id attribute. You can add multiple Placements throughout your site, but each will require a unique id.<div id="placement-pdp"></div> <div id="placement-checkout"></div>
Configuring the Setup and RegisterPlacements Methods
The setup() and registerPlacements() methods are responsible for configuring basic options and rendering each placement on the page which will launch the CARD or INSTALLMENT experience when a Placement is clicked. The setup() method is used to pass configuration options, including integration keys and buyer information. The registerPlacements() method is used to configure the placements on each page, and it will contain information on the order. Add the setup() and registerPlacements() methods on pages where you intend to display Placements.
For example, the setup() and `registerPlacements()** methods could be called as follows:
window.BreadPayments.setup({
loyaltyID: “xxxxxx”, //optional
storeNumber: “1234567”,
env: 'STAGE', // STAGE | PROD
});
window.BreadPayments.registerPlacements([{
financingType: "card",
locationType: "checkout",
placementId: "xxxxxx" // unique id per location
domID: "placement1",
order: { // required for price based messaging
totalPrice: {
value: 110000,
currency: 'USD'
}
}
}]);
window.BreadPayments.setup({
loyaltyID: “xxxxxx”,
storeNumber: “1234567”,
buyer: {
givenName: "Jack",
familyName: "Seamus",
additionalName: "C.",
birthDate: "1974-08-21",
email: "[email protected]",
phone: "+13235323423",
billingAddress: {
address1: "323 somethibng lane",
address2: "apt. B",
country: "US",
locality: "NYC",
region: "NY",
postalCode: "11222",
},
shippingAddress: {
address1: "323 something lane",
address2: "apt. B",
country: "US",
locality: "NYC",
region: "NY",
postalCode: "11222",
},
}
});
window.BreadPayments.registerPlacements([{
financingType: "installments",
locationType: "checkout",
domID: "placement1",
allowCheckout: true,
order: {
items: [{
name: "Men's Classic Clog",
sku: "441122",
category: "Shoe",
unitPrice: {
value: 100000,
currency: 'USD'
},
unitTax: {
value: 0,
currency: 'USD'
},
shippingDescription: '2 - Day Shipping',
shippingCost: {
value: 10000,
currency: 'USD'
},
brand: "Crocs",
quantity: 1,
shippingProvider: "UPS",
}],
subTotal: {
value: 100000,
currency: 'USD'
},
totalTax: {
value: 0,
currency: 'USD'
},
totalShipping: {
value: 10000,
currency: 'USD'
},
totalDiscounts: {
value: 0,
currency: 'USD'
},
totalPrice: {
value: 110000,
currency: 'USD'
}
}
}]);
Step 3: Configuring Callbacks and Checkout Handling
Various events are emitted as an applicant proceeds through the EDS application/checkout experience, and the on() method is used to register event handlers for these events. The following are the main events that can be used to facilitate the application and checkout processes. They register a callback and provide data to the event handler that can be handled in the callback:
- CARD:RECEIVE_APPLICATION_RESULT - emitted after an application has been processed.
- CARD:SUBMIT_APPLICATION - emitted after a customer submitted an application.
- INSTALLMENT:APPLICATION_CHECKOUT - emitted when an applicant completes their installment checkout.
- INSTALLMENT:APPLICATION_DECISIONED - emitted when an applicant receives their prequalification decision for installments.
Each of these main events is expanded on in the next sections.
Handling a Card Application Result
After a CARD application has been processed, the `CARD:RECEIVE_APPLICATION_RESULT event is emitted. Merchants can leverage this event to handle next steps once an application is fully processed. If the application is approved, a callId will be provided in the applicationResult. The callId is valid for 15 minutes and should be sent to your server and exchanged for an account id via the account lookup service. The account id can be stored for immediate and future use.
window.BreadPayments.on("CARD:RECEIVE_APPLICATION_RESULT",(cardResult) => {
// Handle Application Result
switch(cardResult.result){
case 'APPROVED':
// Handle approved case
break;
case 'PENDING':
// Handle pending case
break;
case 'ACCOUNT_EXISTS':
// Handle account exists case
break;
case 'DECLINED':
// Handle declined case
break;
case 'ERROR':
// Handle error case
break;
}
});
See CardResult for response details.
Handling a CARD Application Submit
This event is emitted after a customer submits their application, and it is available to merchants for analytics purposes.
window.BreadPayments.on('CARD:SUBMIT_APPLICATION', () => {
// Handle Application Submitted
});
Handling an Installments Application
After a customer completes an application and their prequalification decision is returned, the SDK will emit the INSTALLMENT:APPLICATION_DECISIONED event. The callback to the event handler will be provided with detail on the customer’s eligible payment agreements (e.g. terms) if they were approved for an installment.
window.BreadPayments.on("INSTALLMENT:APPLICATION_DECISIONED", (installmentResult) => {
// Handle successful installment checkout
});
Handling an Installments Checkout
After an applicant completes their application and fully checks out for an installment, the SDK will emit the INSTALLMENT:APPLICATION_CHECKOUT event. The callback to the event handler will be supplied with the transactionId for the installment checkout. The transactionId should be stored on your server and used on requests to the REST API for transaction management (more detail in the next section).
window.BreadPayments.on("INSTALLMENT:APPLICATION_CHECKOUT", (installmentResult) => {
// Handle successful installment checkout
});
See InstallmentResult for response details.
Events Definition List
Enhanced Digital Suite supports various events. See Events for further details.
Updated 15 days ago