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.