The Bare Essentials

Magento Integration Overview

Bread’s Magento 1 integration consists of an extension that injects Bread at any or all of:

  • Product detail page: This feature presents the Bread button, with “as low as” dollars per month pricing on your product detail page. Customers can pre-qualify for credit directly, and optionally complete the purchase for a single product with financing on the spot without having to leave the page.
  • Shopping cart overview page: This feature presents the Bread button, with “as low as” dollars per month pricing on your cart page for a set of products. Customers can pre-qualify for credit directly, and optionally complete the purchase for their entire cart with financing on the spot without having to leave the page.
  • Payment method on checkout page: This feature keeps customers in your store’s existing Magento checkout flow, keeping the experience identical to your existing standard payment methods, and allowing customers to be approved for financing as their method of payment.
  • Magento admin-side order creation: If you have a showroom and use Magento for orders placed in person, you can create custom orders and allow your in-store customers to qualify for financing on the spot. Important note: this feature is for in-person customer interactions and not to be used for accepting orders over the phone with Bread.  For guidance on over-the-phone orders, please see documentation of Bread’s “carts” feature.

The integration involves the following steps:

  • Install and set up the Bread Magento extension
  • Customize the experience
    • Choose where you wish Bread to appear
    • Design the appearance of the Bread button
    • Customize the Bread experience
  • Manage transactions in Magento

Bread Extension Installation

The Bread extension contains everything you need to use Bread in your Magento store. Currently, the extension is privately distributed by Bread. To install it on your store:

  1. Contact your Bread Success point of contact to obtain the Bread Magento extension archive.
  2. Log into your Magento store’s admin back end. From the System menu, choose Magento Connect Manager.
  3. Use “Direct Package File Upload” to upload the .tar.gz archive.

The Magento extension is now installed and ready for configuration.

Bread Extension Configuration

Bread’s settings are found in your store in the Configuration page, located under the System menu. Once there, choose Payment Methods under Sales on the left.

Configure Bread Settings

  1. Make sure that Enable Bread is set to Yes.
  2. Set Sandbox (Test) Mode for integration and testing.
  3. Leave the Production API Key and Production API Secret Key fields blank for now.
  4. Enter the sandbox public and secret API Keys provided by your account manager in the fields labeled Sandbox API Key and Sandbox API Secret Key.
  5. Set Payment Action to Authorize & Capture to request for the immediate capture of funds upon checkout. Please speak with your Success account manager before enabling Authorize & Capture.
  6. Set Skip Checkout Review Step to Yes to redirect customers to your standard confirmation page upon completing a checkout with Bread.
  7. Click Save Config in the top right corner of the page.

Advanced Settings

  • Enable Targeted Financing Based on Cart Size: Enable this setting to offer promotional financing rates for a specific cart size (dollar amount) threshold
  • Create Accounts for New Customers: Enable this setting to automatically create new accounts for customers that check out with Bread
  • Enable Extra Logging: Enable this setting to turn on error logs for Bread

Settings: Product Details Page

  • Display on Product Details Page: Enable this setting to display Bread checkout buttons on all product detail pages
  • Allow Checkout from Bread Modal: Enable this setting to allow customers to complete a checkout with Bread directly from product detail pages
  • Display Lowest Available Price Per Month: Display an “as low as” price per month on Bread checkout buttons
  • Display as Label Only: Enable this setting to disable Bread buttons once the customer has successfully prequalified for credit
  • Display in New Window: Enable this setting to launch Bread checkout form in a new window instead of a modal
  • Custom CSS: Specify CSS to customize the style of your Bread checkout buttons (CSS should be compressed into a single-line string)
  • Use Default Button Size: Enable to use stock Bread button size or disable to allow for custom height and width

Settings: Category Pages

  • Display on Category Page: Enable this setting to display Bread checkout buttons on category pages
  • Display Lowest Available Price Per Month: Display an “as low as” price per month on Bread checkout buttons
  • Display as Label Only: Enable this setting to disable Bread buttons once the customer has successfully prequalified for credit
  • Display in New Window: Enable this setting to launch Bread checkout form in a new window instead of a modal
  • Custom CSS: Specify CSS to customize the style of your Bread checkout buttons (CSS should be compressed into a single-line string)
  • Use Default Button Size: Enable to use stock Bread button size or disable to allow for custom height and width

Settings: Shopping Cart Page

  • Display on Shopping Cart: Enable this setting to display Bread checkout buttons on the cart overview page
  • Allow Checkout from Bread Pop Up On Cart Page: Enable this setting to allow customers to complete a checkout with Bread directly from the cart overview page
  • Display Lowest Available Price Per Month: Display an “as low as” price per month on Bread checkout buttons
  • Display in New Window: Enable this setting to launch Bread checkout form in a new window instead of a modal
  • Use Product Detail Button CSS: Use the same custom CSS as the product detail page buttons
  • Custom CSS: (Set Use Product Detail Button CSS to No) Specify CSS to customize the style of your Bread checkout buttons (CSS should be compressed into a single-line string)
  • Use Default Button Size: Enable to use stock Bread button size or disable to allow for custom height and width

Settings: Payment Method at Checkout

  • Display as Payment Method on Checkout: Enable this setting to display Bread as a payment method on the Checkout page
  • Sort Order: Set the position of Bread in the payment method list
  • Display in New Window: Enable this setting to launch Bread checkout form in a new window instead of a modal
  • Use Product Detail Button CSS: Use the same custom CSS as the product detail page buttons
  • Custom CSS: (Set Use Product Detail Button CSS to No) Specify CSS to customize the style of your Bread checkout buttons (CSS should be compressed into a single-line string)
  • Use Default Button Size: Enable to use stock Bread button size or disable to allow for custom height and width
  • Incomplete Bread Checkout Error: This message is displayed if a customer starts a Bread checkout and cancels before completing

Bread is now installed in sandbox mode – which allows for safe integration and testing – on your site, using out-of-the box styles and placement, on product detail page, shopping cart page, admin, and checkout. Don’t worry – you’ll be able to change the appearance and placement of the Bread button and the Bread checkout flow.

Testing the Bread Extension

Notes on testing Bread in sandbox mode:
When filling out the Bread form, feel free to make up ‘borrower’ credentials – no real credit is pulled, and no texts or emails are sent by Bread.

A few things to note:

  1. Use a unique, random phone number (mash the number keys). Since customers are identified by phone number, using the same phone number repeatedly may result in a denial as the loan capacity associated with that phone number is exhausted.
  2. Birth Date: A birth date before 2000
  3. For the Last 4 SSN, use 0800 to simulate a credit approval or 0400 to simulate a credit denial.
  4. The one time 7-digit passcode is always 1234.

Product detail page

The Bread button appears near the “add to cart” button by default. It will show the dollars per month pricing for the customer for the given product. Note that for configurable products and products with custom options (or products that are both), the Bread button will automatically reconfigure based on the selected option. It will also provide a tooltip prompting the customer to choose a configuration if the product is not in a valid state.

Click on the button, and provide your test information per the above instructions to experience the Bread checkout flow and pre-qualify for a loan with Bread.

If you proceed to provide shipping address information, Bread will connect to your store’s existing tax and shipping logic to present tax and shipping in the final review screen.

Once you click Accept & Check Out, an order will be placed with Bread in your Magento order management system and you will be redirected to your standard order confirmation page.

If you were not logged into the Magento store and if you have enabled Auto-create customer account in your Bread extension settings, a customer account will be created with a temporary password which will be automatically emailed to the customer by your Magento store. Additionally, that new account will be logged in and associated with the order placed by Bread.

If you were already logged into the Magento store as a customer with default billing and shipping contact information, that information will be pre-populated into the Bread forms once you open them.

Cart overview page:

The Bread button appears near the “Proceed to Checkout” button by default. It will show the dollars per month pricing for the customer for the given cart.

Click on the button, and provide your test information per the above instructions to experience the Bread checkout flow and pre-qualify for a loan with Bread.

If you provide shipping address information, Bread will connect to your store’s existing tax and shipping logic to present tax and shipping in the final review screen. If you click “Accept and Checkout,” an order will be placed with Bread in your Magento order management system, and the customer will land on your standard order confirmation page.

If you were not logged into the Magento store and if you have enabled Auto-create customer account in your Bread extension settings, then a customer account will be created with a temporary password which will be automatically emailed to the customer by your Magento store. That new account will be logged in and associated with the order placed by Bread.

If you were already logged into the Magento store as a customer with default billing and shipping contact information, that information will be prefilled into the Bread forms once you open them.

Payment method at checkout

The Bread will appear as a payment method on the checkout page if Display as Payment Method on Checkout is enabled in the Bread configuration. The Bread option will display the price per month for the given cart, inclusive of tax and shipping already selected.

Select the Bread radio option and click the Continue button to launch the Bread modal. Provide your test information per the above instructions to experience the Bread checkout flow and pre-qualify for a loan with Bread.

After clicking Accept & Check Out, the customer will be redirected to your standard Magento confirmation order page if Skip Checkout Review Step is enabled. We recommend enabling this option for the best customer experience. However if Skip Checkout Review Step is disabled, the customer should now proceed to the final confirmation step of checkout and complete the order.

Troubleshooting

When troubleshooting issues with your Bread integration, you should turn on Enable extra logging under the Bread extension settings under Advanced Settings. This will enable error logging within Magento for the Bread extension.

Customizing Bread

Bread is intended to be highly customizable, to fit with your customers, your product category, and your store’s overall brand and experience. As such, you will make some decisions and apply some customizations:

  • Where should Bread appear in my customer’s journey?
  • Where on a page should Bread appear? How much space should the button take up?
  • How do I want the Bread button to appear?

Where should Bread appear in my customer’s journey?

In thinking through your Bread implementation, you should decide:

  • Should Bread be available on the product detail page?  (Controlled by the Enabled on Product Details Page option)
  • Should you allow customers to check out immediately from the product detail page? Alternatively, you can advertise an “as low as” price and allow customers to pre-qualify for financing, but not check out directly from product detail pages.  (Controlled by the Allow Checkout From Bread Pop Up On Product Page option.)
  • Should Bread be available on the cart overview page?  (Controlled by the Enabled on Cart Overview Page option)
  • Should you allow customers to check out immediately from the cart page? Alternatively, you can advertise an “as low as” price and allow customers to pre-qualify for financing, but not check out directly from cart pages. (Controlled by the Allow Checkout From Bread Pop Up On Cart Page option)
  • Should Bread be available on a payment method at checkout?  (Controlled by the Display as Payment Method on Checkout option)

Where on a page should Bread appear?  How much space should the button take up?

Positioning of the Bread button is controlled by the placement of the Bread page block in Magento.

Product detail page: The identifier of the Bread block on the product detail page is breadcheckout.prod.view. By default, it is placed in reference to the product.info.extrahint block. You may use your page templates to place it elsewhere on the page to match your design.

The block places two <div> elements on the page, with identifiers bread-btn-cntnr and bread-checkout-btn.

<div id="bread-btn-cntnr">
  <div id="bread-checkout-btn" title="Bread Checkout" class="button"></div
</div>

Use your site’s CSS to further size and position the Bread button. Note that if you wish to control the Bread button size yourself, you must change the setting Use default button size in the Bread configuration to No.

Additionally, for configurable products and products with custom options, the Bread block contains an overlay and tooltip to prevent customers from clicking on Bread if the product is not in a valid configuration state. You can style the overlay and tooltip in your site’s CSS. The overlay has the class name button-prevent and the tooltip has the class names buy_error_tip override_tip.

Shopping cart page: The identifier of the Bread block on the cart page is breadcheckout.checkout.view. By default, it is placed in reference to the checkout.cart.methods block. You may use your page templates to place it elsewhere on the page to match your design.

The block places two <div> elements on the page, with identifiers bread-btn-cntnr and bread-checkout-btn. Use your site’s CSS to further size and position the Bread button. Note that if you wish to control the Bread button size yourself, you must change the setting Use default button size in the Bread configuration to No.

Checkout and admin side payment method pages: The Bread block places a <div> element on the page, with identifier bread-checkout-btn. Use your site’s CSS to further size and position the Bread button. Note that if you wish to control the Bread button size yourself, you must change the setting Use default button size in the Bread configuration to No.

How do I want the Bread button to appear?

The Bread button is highly customizable, and you can make it appear and behave any way you like using CSS. Supply your custom Bread button CSS in the Bread Button Design field in the Bread extension configuration.

To get started with your custom CSS:

  1. Review Style the Bread Button for guidance on writing CSS for your Bread button.
  2. All CSS values contained in quotes should use double quotes. For example:
    #bread-button { font-family: "Times New Roman"; }
  3. Compress your CSS into a single-line string using a service such as CSS Minifier.

Handling orders after the checkout

The Bread extension integrates seamlessly with Magento so you can manage orders paid for with financing without leaving your standard order management system.

Actions taken in the Magento order management system for Bread app orders will be automatically reflected in Bread’s systems. Orders paid for with Bread will be noted under the payment section of the order as “Bread – pay over time.”

  • For orders that are Authorized, but not Settled, create and submit an Invoice in Magento once you have fulfilled the order
  • To cancel a Bread transaction, use the Void or Cancel order actions in Magento
  • To partially or completely refund a settled Bread transaction, create a Credit Memo on the invoice you previously created, and perform an online refund for the amount you wish to credit back to the customer