Bread SDK Installation

This guide seeks to provide step-by-step instructions you can follow to successfully render Bread placements within your front-end customer journey.

A default Bread placement, will render "as low as" text, which launches the Bread modal when clicked.

📘

Integration Key

Before you begin, you must already have an integrationKey for your associated Preview / Production environments. You can access the integration key within the Account Settings section of your Bread Merchant portal.

Step 1: Loading the Bread SDK on your site

In order to load Bread on your site, add the appropriate Preview / Production JS script tags below within your base template's head tags or towards the top of your body section so that it loads on every page within your website.

Loading Bread via the SDK

//Bread Preview JS script
<script src="https://connect-preview.breadpayments.com/sdk.js"></script>

//Bread Production JS script
<script src="https://connect.breadpayments.com/sdk.js"></script>

Step 2: Configuring Bread Placements

Bread placements must be configured with JS before they can be rendered on the page.

Render Placements Overview

1. Load Bread SDK script
2. Call BreadPayments.setup function
3. Add HTML that matches Placements domID
4. Call BreadPayments.registerPlacements function
5. Using BreadPayments.on function, register events for INSTALLMENT:APPLICATION_DECISIONED and INSTALLMENT:APPLICATION_CHECKOUT

Take the following steps to configure Bread.

Bread Setup

Loading the Bread SDK script will give you access to the BreadPayments object. The BreadPayments.setup function must be called and passed an integrationKey and buyer object.

BreadPayments.setup({
  integrationKey: "your-integration-key",
  buyer: buyer,
});

A buyer object is required when allowCheckout is set to true, and must include shippingAddress at a minimum. It is highly recommended to pass all additional buyer information to the extent possible, to ensure the Bread modal can be pre-populated with information for an expedited checkout experience.

The buyer object is optional when allowCheckout is set to false(more on allowCheckout later).

An example buyer object with fully populated data:

const buyer = {
  givenName: "John",
  familyName: "Smith",
  additionalName: "C.",
  birthDate: "1974-08-21",
  email: "[email protected]",
  phone: "2123344141",
  billingAddress: {
    address1: "323 something 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",
  },
};

Bread Placements

Bread placements are used to provide order information, tax, discounts and other data to the Bread modal before launch. Bread placements can be passed a large set of data to generate "As Low As $XX/month" text, and allow customers to prequalify and checkout for certain amounts. Bread placements can also be configured with minimal information solely to encourage prequalification. These placements are particularly useful on pages with no product visible, such as a financing page.

Each placement has a domID attribute. This tells the placement where it should render on the page. You will need to add the matching HTML element with ID to your page. A placement with a domID of bread-checkout-btn will require the following div on the page.

<div id="bread-checkout-btn"></div>

An example of a placement with product information populated and allowing for checkout:

const placement = {
  financingType: "installment",
  locationType: "checkout",
  domID: "bread-checkout-btn",
  allowCheckout: true,
  order: {
    items: [
      {
        name: "Smooth Product",
        sku: "09-021302",
        category: "",
        unitPrice: {
          value: 11000,
          currency: "USD",
        },
        unitTax: {
          value: 0,
          currency: "USD",
        },
        brand: "Brand Name",
        quantity: 1,
        shippingDescription: "Ground",
        shippingProvider: "UPS",
        shippingCost: {
          value: 0,
          currency: "USD",
        },
      },
    ],
    subTotal: {
      value: 11000,
      currency: "USD",
    },
    totalTax: {
      value: 3000,
      currency: "USD",
    },
    totalShipping: {
      value: 0,
      currency: "USD",
    },
    totalDiscounts: {
      value: 0,
      currency: "USD",
    },
    totalPrice: {
      value: 14000,
      currency: "USD",
    },
  },
};

👍

items array

It is highly recommended that you enrich the items array with information about the products in a customer's cart (e.g. name, SKU, price, etc). These details are displayed during the final step of the checkout process, and will also be included in the Merchant and Member portals.

An example of a placement typically found on Product Detail pages that are only used for prequalification for a specific item total, with no checkout allowed:

const placement = {
    financingType: "installment",
    locationType: "product",
    domID: "bread-checkout-btn",
    allowCheckout: false,
    order: {
      items: [],
      subTotal: {
        value: 11000,
        currency: "USD",
      },
      totalTax: {
        value: 0,
        currency: "USD",
      },
      totalShipping: {
        value: 0,
        currency: "USD",
      },
      totalDiscounts: {
        value: 0,
        currency: "USD",
      },
      totalPrice: {
        value: 11000,
        currency: "USD",
      },
    }
};

An example of a placement without an item total provided that only allows prequalification and no checkout:

const noProductPlacement = {
    allowCheckout: false,
    domID: "bread-prequal-btn",
};

📘

allowCheckout

allowCheckout should be set to false on any pages (e.g. product detail pages, cart pages) where a customer should NOT be permitted to complete a checkout. The Bread experience on these pages serves purely to return an application decision to the customer.

allowCheckout should be set to true on pages where a customer should be permitted to complete a checkout (e.g. checkout page).

Create Bread Placements

Now that Bread is set up and the placements are configured, you can call the BreadPayments.registerPlacements function.

The registerPlacements function takes an array of placements and generate Bread placements on the page. Every placement will launch a Bread modal when clicked.

const placements = [
  {
    financingType: "installment",
    locationType: "checkout",
    domID: "bread-checkout-btn",
    allowCheckout: true,
    order: {
      items: [
        {
          name: "Smooth Product",
          sku: "09-021302",
          category: "",
          unitPrice: {
            value: 11000,
            currency: "USD",
          },
          unitTax: {
            value: 0,
            currency: "USD",
          },
          brand: "Brand Name",
          quantity: 1,
          shippingDescription: "Ground",
          shippingProvider: "UPS",
          shippingCost: {
            value: 0,
            currency: "USD",
          },
        },
      ],
      subTotal: {
        value: 11000,
        currency: "USD",
      },
      totalTax: {
        value: 3000,
        currency: "USD",
      },
      totalShipping: {
        value: 0,
        currency: "USD",
      },
      totalDiscounts: {
        value: 0,
        currency: "USD",
      },
      totalPrice: {
        value: 14000,
        currency: "USD",
      },
    },
  },
];

BreadPayments.registerPlacements(placements);

📘

Error Messages in Console

After a Bread placement is rendered you may see two 401 Errors in the console. These are requests sent to Bread's backend servers to verify if there is an existing buyer or application so those terms can be reflected in the placement text.

In cases of a new customer, Bread will show two 401 errors in the console, however, these errors do not impact Bread functionality and can be ignored.

Step 3: Handling Bread Applications and Checkouts

Bread emits many events during the customer application and checkout experience. The BreadPayments.on function can be used to register event handlers for these events. You must register the below two events to render placements on any given page:

1. INSTALLMENT:APPLICATION_DECISIONED: Runs after a customer receives an application decision. The callback to the event handler will be provided, for example, with detail on the customer’s eligible payment agreements (e.g. terms) if they were approved for an application.
2. INSTALLMENT:APPLICATION_CHECKOUT: Runs after a customer completes a checkout. The callback to the event handler will be supplied with the transactionId for the checkout.

An example INSTALLMENT:APPLICATION_DECISIONED callback:

// callback runs after customer application result
BreadPayments.on("INSTALLMENT:APPLICATION_DECISIONED", (installmentResult) => {
  console.log(installmentResult);
});

An example INSTALLMENT:APPLICATION_CHECKOUT callback:

// callback runs after customer completes checkout 
BreadPayments.on("INSTALLMENT:APPLICATION_CHECKOUT", (installmentResult) => {
  console.log(installmentResult);
});

When you are successfully able to render placements, refer to our Development and Testing guidelines for details on how to place test checkouts, move from Preview to Production, in addition to integration best practices.

📘

Note

Empty functions can be passed if neither event satisfies a use case on a given page.INSTALLMENT:APPLICATION_CHECKOUT will not run if allowCheckout is configured to false.

Handling a Checkout

When a customer completes the Bread checkout flow in the modal, a transaction is created in Bread's systems in a "Pending" state.

In order to update Bread order states via merchant Order Management Systems, the Bread transactionID must be stored server-side for future requests to the Bread Transaction API. The transactionID can be accessed via the INSTALLMENT:APPLICATION_CHECKOUT event handler.

BreadPayments.on("INSTALLMENT:APPLICATION_CHECKOUT", (installmentResult) => {
  // Handle successful installment checkout
  console.log("Checkout Successful");
  console.log(installmentResult); // installmentResult object
  const transactionID = installmentResult.transactionID;
  console.log(transactionID); // Bread transaction ID
  /*
     add logic here to store transactionID server side to update order states in the future
  */
})

Handling order management states is done through API requests on the backend of the integration.

BreadPayments Reference

Properties related to the BreadPayments object that is loaded by the SDK

Events

Callback functions can be configured using the BreadPayments.on function for the below events.