Magento 2 Integration Steps

STEP 1: Install and Configure Bread Extension

You can install the Bread Extension by downloading a zip file of the plugin, found here or on our github, and unzipping the contents into the app/code/Bread/BreadCheckout folder within the Magento app. In addition, you can install the extension via composer.

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. Find your sandbox API and secret keys from your Bread sandbox merchant portal, under Account Settings
  4. Enter your API Key into the Sandbox API Public Key field
  5. Enter your Secret Key into the Sandbox API Secret Key field
  6. 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
  7. 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.
  8. In the upper right corner, hit Save Config to save your settings
  9. 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, but there are additional settings which allow you to fine-tune the extension’s functionality.


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.

Button Styling

The Bread button can be styled using custom CSS, however, the CSS must be supplied through the Bread Plugin settings under the Bread Button Design field in the Bread Extension settings. The CSS must be compressed into a single-line string (using a service such as CSS Minifier) before being added to the Bread Button Design field.


The Bread button can also be styled through a visual builder in the Merchant Portal.

Note: Please review the Style The Bread Button for an explanation of the Bread button HTML structure and different button states. All CSS values contained in quotes should use double quotes.

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>

Note: 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.

Modal Styling

To customize the styling of the modal, please see our documentation here

STEP 3: Test The Bread Extension

We strongly recommend you test your Bread integration with your sandbox API keys and our sandbox domain 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
  • Last 4 Digits of SSN: 07xx (Any 4-digit number starting with 07, such as 0789) to simulate approval, or 0400 to simulate denial
  • Mobile Code / Token: 1234

Note: You will not receive emails nor text messages when testing in sandbox mode. Please refer our Testing documentation for additional guidelines.

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. Enter Production Keys: Log into your live merchant portal and find your API and Secret Keys under Account Settings. Enter your API Key into API Public Key and enter your Secret Key into API Secret Key. Make sure you hit Save Config in the upper right hand corner.
  3. Customize Bread Modal: Log into your live merchant portal and select Checkout Settings. Customize your Bread modal (these settings are not automatically carried over from your sandbox merchant portal.
  4. Get My Rate Buttons: If you’re making use of Bread Apply “Get My Rate” buttons, make sure to change the data-api-key attribute to your live API key for each button. See Bread Apply docs for more details.
  5. Set Bread to Live: From within the Bread extension settings in your Magento admin portal, change API MODE to LIVE. Hit Save Config.

You’re now live with Bread!