# breadfinance/magento-v2-bread

`composer require breadfinance/magento-v2-bread`

Canonical URL: https://packagento.com/breadfinance/magento-v2-bread

## At a glance

- **Vendor**: breadfinance (https://packagento.com/breadfinance.md)
- **Latest version**: 2.4.9 — released 2026-05-12
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/breadfinance/magento-v2-bread and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require breadfinance/magento-v2-bread:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## README

Bread Pay Checkout for Magento 2
=============================

Helping retailers acquire and convert more customers.

Bread Pay Features
----------------------

* Full Funnel. Your shoppers can discover, pre-qualify, and check out from anywhere - your homepage, 
category page, product page, cart, or checkout. 
* Real-Time Decision. Pre-qualification is quick and easy. Let your customers learn 
about their purchase power in seconds without ever leaving your site.

Installation
------------

#### Install using Zip archive

1. Download repository as zip file

2. Unzip contents into `app/code/Bread/BreadCheckout` folder

3. Setup files ( For Canada Merchants )

- Copy file `app/code/Bread/BreadCheckout/etc/adminhtml/system.ca.xml` to `app/code/Bread/BreadCheckout/etc/adminhtml/system.xml`
- Copy file `app/code/Bread/BreadCheckout/view/adminhtml/web/js/validation.ca.js` to `app/code/Bread/BreadCheckout/view/adminhtml/web/js/validation.js`


4. Enable module
    ```bash
    bin/magento module:enable Bread_BreadCheckout
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy
    ```

#### Install using composer. 

1. Navigate to your Magento 2 root folder

2. Install the Bread Checkout module    
     ```bash
     composer require breadfinance/module-breadcheckout
     ```
3. For Canada Merchants only

- Copy file `app/code/Bread/BreadCheckout/etc/adminhtml/system.ca.xml` to `app/code/Bread/BreadCheckout/etc/adminhtml/system.xml`
- Copy file `app/code/Bread/BreadCheckout/view/adminhtml/web/js/validation.ca.js` to `app/code/Bread/BreadCheckout/view/adminhtml/web/js/validation.js`

4. Enable module
    ```bash
    bin/magento module:enable Bread_BreadCheckout
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy
    ```
    

### Usage instructions:

#### For US Merchants
See documentation at https://platform-docs.breadpayments.com/bread-onboarding/docs/magento-2-integration-steps
Contact your Bread Pay representative for login credentials.

#### For Canada Merchants
See documentation at https://rbcpayplan.readme.io/rbc-onboarding/docs/magento-2-integration-steps 
Contact your Payplan representative for login credentials.


### Development Environment Setup

This guide sets up a local Magento environment using [markshust/docker-magento](https://github.com/markshust/docker-magento). Refer to the repository for more details, configuration options, and available commands.


#### 1. Create Project Directory & Download Docker Template

```bash
mkdir docker-magento
cd docker-magento
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash
```

#### 2. Configure environment and versions
Open the compose.yaml file and confirm the PHP and DB versions matches your target environment.

For PHP 8.2, ensure the following line is present:
```
phpfpm:
  image: markoshust/magento-php:8.2-fpm-4
```

For MySQL, ensure compatible version is used. Magento currently (As of 6/2025) supports:

MySQL 8.0

MySQL 5.7

MariaDB 10.2 – 10.6

#### 2a. Trust Internal Root CA (e.g. Netskope) in Container
If you're on a corporate network that intercepts HTTPS traffic (e.g., via Netskope), you may encounter SSL errors like:

```
curl: (60) SSL certificate problem: self-signed certificate in certificate chain
```
To fix this, you must import your organization's root certificate into the container.

* Visit https://github.com in Chrome.

* Click the padlock icon → "Certificate is valid".

* In the Certification Path tab, select the top-level certificate (e.g., ca.alliancedata.goskope.com).

* Click View Certificate → Details → Copy to File.

* Save as Base-64 encoded X.509 (.CER) — name it netskope_root.cer.

* Place the file in the project root.

* Run these commands

```
docker cp <path-to-downloaded-certificate> phpfpm:/usr/local/share/ca-certificates/netskope_root.crt
```
```
docker exec -u 0 -it phpfpm bash
update-ca-certificates
```

* This will copy the cert into the phpfpm container and update the container’s trusted certificate store.

* You should now be able to run bin/download and composer install without SSL errors.


#### 3. Download Magento
Download the Magento version you want (replace 2.4.8 with your desired version):

```
bin/download 2.4.8
```

#### 4. Set Up Magento Environment
Run the following commands to complete setup and install sample data:

```
bin/setup magento.test
bin/magento sampledata:deploy
bin/magento setup:upgrade
```
Disable Two-Factor Authentication for local development:
```
bin/composer require markshust/magento2-module-disabletwofactorauth
bin/magento module:enable MarkShust_DisableTwoFactorAuth
bin/magento setup:upgrade
```

#### 5. Install Bread Magento Extension
Clone the Bread extension into app/code and enable the module:
```
cd src/app/code
mkdir Bread
cd Bread
git clone git@github.com:getbread/magento-v2-bread.git BreadCheckout
cd ../../../../

bin/magento module:enable Bread_BreadCheckout
bin/magento setup:upgrade
bin/magento cache:flush
```

### Resetting Your Local Magento Environment
To completely remove your local Magento installation and start fresh:

#### 1. Navigate to the root of your Magento project:

```
cd /path/to/your/magento-docker-dev
```
#### 2. Run the cleanup script and delete all files (including hidden ones):

```
bin/removeall
rm -rf .[^.]* * 
```
⚠️ Warning: This will permanently delete all files and directories in the current folder. Make sure you’re in the correct location before running this command.

## Changelog

== Changelog ==

= 2.4.9
* Current release
* Fix checkout issue when payment method is selected first

= 2.4.8
* Add Hyva theme and Hyva Checkout compatibility
* Add CSP (Content Security Policy) whitelist for Bread SDK domains
* Fix SDK loading for stores with strict CSP policies
* Fix PHP 8.4 implicit nullable parameter deprecations

= 2.4.7
* Support PHP 8.4

= 2.4.6
* Support PHP 8.3

= 2.4.5
* Use base_grand_total instead of base_total
* Prevent repeated calls to settle endpoint

= 2.4.4
* Fix error with product custom options

= 2.4.3
* Fix checkout issue with RBC

= 2.4.2
* Allow Submit Order in admin when creating customer cart

= 2.4.1
* Add support for CAD and USD on the same store using currency switcher

= 2.3.11
* Fix discount error when creating Admin cart

= 2.3.10
* Add support for In-store delivery

= 2.3.9
* Add compatibility with Mageplaza OSC

= 2.3.8
* Show billing address in payment method when using Amasty One Step Checkout

= 2.3.7
* Fixed issue with configurable products

= 2.3.6
* Mageplaza One Step Checkout compatibility

= 2.3.5
* Bread platform admin carts support

= 2.3.4
* Category page slow load bug fix

= 2.3.3
* PHP 8.2 comaptibility updates
* Healthcare mode refactor, healthcare checks have been moved to the SDK
* Closed https://github.com/getbread/magento-v2-bread/issues/189

= 2.3.2
* Replaced Zend_Http_Client with Laminas_Http
* Minor bug fixes

= 2.3.1
* ALA button now shows correctly for Bundled products under the view category section
* Fixed the fetch Auth token API end-point
* Extension is now PHP 8.2 compatible

## Recent Versions

| Version | Released |
|---|---|
| 2.4.9 | 2026-05-12 |
| 2.4.8 | 2026-02-17 |
| 2.4.6 | 2025-06-26 |
| 2.4.5 | 2025-03-14 |
| 2.4.4 | 2024-09-25 |
| 2.4.3 | 2024-08-22 |
| 2.3.11 | 2024-03-07 |
| 2.3.7 | 2023-08-22 |
| 2.3.6 | 2023-08-08 |
| 2.3.5 | 2023-06-07 |

Showing 10 of 55 versions. Full release history on https://packagento.com/breadfinance/magento-v2-bread.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| php | ~8.1.0\|\|~8.2.0\|\|~8.3.0\|\|~8.4.0 |

### Suggest

| Package | Constraint |
|---|---|
| hyva-themes/magento2-default-theme | Required for Hyva theme compatibility |
| hyva-themes/magento2-hyva-checkout | Required for Hyva Checkout integration |

## Quality

Latest release (2.4.9) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | not tested |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 1015 | 1015 warnings (ruleset: Magento2) — 576 auto-fixable with phpcbf |
| PHPMD | Warning | 113 | 113 rule violations (MissingImport:36, ExcessiveParameterList:13, UndefinedVariable:11, ExcessiveClassComplexity:8, UnusedLocalVariable:8) |
| Cpd | Warning | 8 | 8 duplicated chunks spanning 580 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Info | 1 | valid; 1 advisory note (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 392 | 392 | – | – |
| 2.4.8 | – | 393 | 393 | – |
| 2.4.9 | – | – | 393 | N/A |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["breadfinance/magento-v2-bread"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

breadfinance is a Magento 2 vendor on Packagento. See https://packagento.com/breadfinance.md for their full catalogue.