Magento 2 Integration Steps

STEP 1: Install and Configure Bread Extension

You can install the Bread Extension after downloading the plugin in one of the following locations:

Magento Marketplace:
Bread Github:

For a Composer installation follow the steps found here.

Zip File Installation Steps

In order to install the Bread Pay extension using a zip file:

  1. Make sure you download the most recent version
  2. Unzip contents into app/code/Bread/BreadCheckout folder
  3. For Canadian merchants only
    1. Copy file app/code/Bread/BreadCheckout/etc/adminhtml/ to app/code/Bread/BreadCheckout/etc/adminhtml/system.xml
    2. Copy file app/code/Bread/BreadCheckout/view/adminhtml/web/js/ to app/code/Bread/BreadCheckout/view/adminhtml/web/js/validation.js
  4. Enable module
    bin/magento module:enable Bread_BreadCheckout
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy

Basic Configurations

Find the Bread Extension’s settings in the Magento 2 admin by:

  1. Click on Stores on the left hand menu, select Configuration under Settings
  2. Under Configuration, click on the Sales menu and select Payment Methods
  3. Under Payment Methods, open Other Payment Methods and Bread Checkout

Basic Settings:

  1. Set Enabled to Yes
  2. API Mode should be set to Sandbox during integration testing, but should be switched over to Live once your integration is ready for production
  3. Set the Bread module version to Bread 2.0
  4. Find your sandbox API and secret keys in your Merchant Portal
  5. Enter your Integration Key into the Integration Key field
  6. Enter your API Key into the Sandbox API Public Key field
  7. Enter your Secret Key into the Sandbox API Secret Key field. You can access these keys within the Account Settings section of your Bread Merchant portal.
  8. 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
  9. Enable button on product details, cart, and/or checkout pages by changing one or more of Enabled on Product Details Page, Enabled on Cart Overview Page, and Display as Payment Method on Checkout to Yes.
  10. In the upper right corner, hit Save Config to save your settings
  11. Flush your Magento cache and reload your store on a page you’ve enabled Bread to confirm everything appears

With the basic settings above, you’ll be able to render Bread in the specified parts of your site.

STEP 2: Style the Bread Button

Bread is highly customizable, and the Bread button and modal can be styled to match your site’s theme.


Site Customizations & Third Party Apps

The Bread Pay plugin was designed to work with native Magento 2 features and functionality. The plugin does not support all third party applications available on the Magento 2 marketplace. Installing these applications or performing customizations to your product, cart, category, and checkout pages can result in issues loading Bread elements.

Button Styling

The Bread button will render on Product Detail and Cart pages in an anchor tag, and it can be styled with CSS via your site's stylesheet. In order to style the Bread button, add the below snippets to your stylesheet:

On Product Detail page:

#bread-checkout-btn a {
  /*Add your styles here*/

On Cart:

#bread-checkout-btn-2 a {
  /*Add your styles here*/

Positioning and Sizing

Positioning of the Bread button is controlled by the placement of the Bread page block in Magento. You will need to edit your Magento files directly to make position adjustments for the Bread button.

You can control the size of your Bread button with CSS, but you will first need to set Use default button size to No in the Bread Extension Settings of your Admin Dashboard.

Product Detail Page

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

Cart Overview Page

The identifier of the Bread block on the cart overview 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.

Both and breadcheckout.checkout.view blocks will place two

elements on the page with id attributes of bread-btn-cntnr and bread-checkout-btn.

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


Configurable Products

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 and override_tip.

STEP 3: Test the Bread Extension

We strongly recommend you test your Bread integration with your sandbox keys before pushing Bread live on your production site. You can leverage the following dummy data when testing Bread in sandbox mode.

  • Any name, address and email
  • Mobile Number: A random sequence of 10 digits – don’t use duplicates or sequential numbers (e.g. 555-555-5555 or 123-456-7890)
  • Birth Date: A birth date before 2000
  • Mobile Code / Token: 1234

In order to simulate an application denial, please use [email protected] as your email address in the application process.


Sandbox Testing

You will not receive emails nor text messages when testing in sandbox mode.

STEP 4: Going Live With Bread

Once you have completed testing the Bread integration, you can follow the next steps to turn Bread on for your customers:

  1. Access Live Merchant Portal: Ask your main Success point of contact for access to your live Merchant Portal
  2. Set Bread to Live: From within the Bread extension settings in your Magento admin portal, change API MODE to LIVE.
  3. Enter Production Keys: Log into your live merchant portal and find your Integration Key, and API and Secret Keys under Account Settings. Enter your API Key into API Public Key, your Secret Key into API Secret Key, and Integration Key into Integration Key.
  4. Hit Save Config.

You’re now live with Bread!