====== Magento 2 React Checkout Pro Extension ======

===== Extension context =====

This is a Toweringmedia Magento 2 extension guide in the Checkout and Payments category. Use this page for installation, configuration, validation, and go-live troubleshooting.

- **Module name**: `Toweringmedia_ReactCheckoutPro`
- **Composer package**: `toweringmedia/module-react-checkout-pro`
- **Primary storefront change**: Replaces `/checkout` with React Checkout Pro.

===== Quick links =====

- [[magento2:extensions:start|Magento 2 extension index]]
- [[magento2:start|Magento 2 docs home]]
- [[magento2:extensions:toweringmedia-module-moneris|Magento 2 Moneris Payment Extension]]
- [[magento2:extensions:toweringmedia-module-authorizenet|Magento 2 Authorize.Net Payment Extension]]
- [[magento2:extensions:toweringmedia-module-react-checkout-pro-express|Magento 2 React Checkout Pro Express Extension]]

===== Overview =====

React Checkout Pro is a modern Magento 2 checkout replacement built for autosave-first behavior and faster completion.

- Replaces default checkout flow with a React-based single-page experience.
- Saves contact, address, shipping, and payment selections as the shopper interacts.
- Supports guest checkout or account-required checkout based on Magento guest policy.
- Supports optional Express wallet add-on and optional payment/anti-bot integrations.

===== Before you configure =====

- Magento 2.4.x with CLI access.
- Module installed and enabled.
- Admin access to:
  - `Stores > Configuration > Sales > Checkout React Pro`
- Confirm Magento guest policy in:
  - `Stores > Configuration > Sales > Checkout > Checkout Options > Allow Guest Checkout`

==== Base + add-on compatibility ====

- **Base (required)**: `toweringmedia/module-react-checkout-pro`
- **Express add-on**: `toweringmedia/module-react-checkout-pro-express`
  - Requires `Toweringmedia_AuthorizeNet` and HTTPS storefront.
- **Payments**:
  - Moneris: `toweringmedia/module-moneris`
  - Authorize.Net: `toweringmedia/module-authorizenet`
- **Anti-bot (optional)**:
  - `toweringmedia/hyva-recaptcha-v3`
- **Shipping base guides**:

===== Step-by-step configuration workflow =====

==== 1) Install and enable ====

From Magento root:

<code bash>
composer require toweringmedia/module-react-checkout-pro
php bin/magento module:enable Toweringmedia_ReactCheckoutPro
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento toweringmedia:react-checkout-pro:collect
php bin/magento cache:flush
</code>

==== 2) Enable checkout takeover ====

Go to:
`Stores > Configuration > Sales > Checkout React Pro > Checkout`

Set:
- **Enable React Checkout Pro** = **Yes**

==== 3) Apply safe starting values ====

Set:
- **Enable Express Checkout Section** = **No** (enable only after Express dependencies are complete)
- **Enable Discount Code Field** = **Yes**
- **Show Vendor Name (Debug)** = **No**
- **Enable "Show more options"** = **Yes**
- **"Show more options" label** = `Show more options`

==== 4) Validate account policy behavior in frontend ====

- If guest checkout is enabled (`checkout/options/guest_checkout = 1`), guest flow is available.
- If guest checkout is disabled (`checkout/options/guest_checkout = 0`), checkout shows **Account required** and blocks order placement until sign-in/account creation requirements are met.

{{:magento2:extensions:screenshots:toweringmedia-module-react-checkout-pro-admin-top.png|React Checkout Pro frontend state}}
{{:magento2:extensions:screenshots:toweringmedia-module-react-checkout-pro-admin-fields.png|React Checkout Pro account required state when guest checkout is disabled}}

===== Configuration reference =====

^ Field ^ Purpose ^ Recommended starting value ^
| `reactcheckoutpro/checkout/enabled` | Enable checkout takeover on `/checkout` | `Yes` |
| `reactcheckoutpro/checkout/enable_express_checkout` | Show/hide Express wallet section | `No` initially |
| `reactcheckoutpro/checkout/enable_discount_code` | Show coupon/discount field | `Yes` |
| `reactcheckoutpro/checkout/show_vendor_name` | Show vendor names for debugging | `No` |
| `reactcheckoutpro/checkout/payment_layout_json` | Drag/drop JSON override for payment grouping | blank initially |
| `reactcheckoutpro/checkout/payment_always_first` | Pin payment codes first | `toweringmedia_authorizenet` if used |
| `reactcheckoutpro/checkout/payment_primary` | Main payment list codes | primary gateway code(s) |
| `reactcheckoutpro/checkout/payment_more` | Payment codes under “more options” | `checkmo` (adjust per policy) |
| `reactcheckoutpro/checkout/payment_more_label` | Disclosure button label | `Show more options` |
| `reactcheckoutpro/checkout/payment_more_options_enabled` | Enable grouped payment list | `Yes` |
| `reactcheckoutpro/applepay/domain_association` | Apple Pay domain association file content | blank until Apple Pay setup |
| `reactcheckoutpro/dev/show_debug_panels` | Show checkout debug panels | `No` in production |
| `reactcheckoutpro/alerts/payment_failure_email_enabled` | Send payment-failure alert email | `No` initially |
| `shipping_guard/general/enabled` | Enable shipping guard protections | `Yes` |
| `shipping_guard/general/positive_cache_ttl` | Success cache TTL (minutes) | `15` |
| `shipping_guard/general/invalid_throttle` | Invalid-input retry throttle (seconds) | `60` |
| `shipping_guard/general/include_weight_subtotal` | Include cart weight/value in key | `Yes` |
| `shipping_guard/general/log_level` | Shipping guard diagnostics level | `errors` |

===== Go-live validation checklist =====

- [ ] `/checkout` loads React Checkout Pro for a normal cart.
- [ ] Autosave behavior works for contact, address, shipping, and payment steps.
- [ ] Virtual cart behavior is correct (shipping method hidden/skipped).
- [ ] Guest policy matches storefront behavior (`checkout/options/guest_checkout`).
- [ ] With guest disabled, **Account required** appears and Place Order remains blocked until requirements are met.
- [ ] Primary payment method can place an order successfully.
- [ ] Express buttons render only when Express + Authorize.Net + HTTPS requirements are satisfied.
- [ ] No critical JS console errors and no blocking Magento checkout errors in logs.

===== Troubleshooting by symptom =====

==== Checkout page is blank ====

- Check browser console for JavaScript runtime errors.
- Redeploy static content and flush cache:
<code bash>
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
</code>

==== “Account required” appears unexpectedly ====

- Confirm Magento guest setting:
  - `checkout/options/guest_checkout`
- If this is set to **No**, account-required behavior is expected.
- If this is set to **Yes**, recheck cached config and store scope.

==== Express buttons do not show ====

- Confirm `Toweringmedia_ReactCheckoutProExpress` is installed/enabled.
- Confirm `Toweringmedia_AuthorizeNet` is installed/enabled.
- Confirm **Enable Express Checkout Section** is enabled in Checkout React Pro config.
- Confirm storefront is HTTPS.

==== Payment appears but fields/tokenization fail ====

- For Moneris, verify hosted/direct setup and environment credentials.
- For Authorize.Net, verify gateway configuration and active method state.
- Hard refresh checkout to clear stale session/form key state.

==== Shipping quotes are missing or inconsistent ====

- Verify carrier modules (UPS/USPS/FedEx) are configured and active.
- Review Shipping Guard config for aggressive throttling behavior.
- Verify address/cart data completeness.

===== Related Magento 2 docs =====

- [[magento2:extensions:start|Magento 2 extension index]]
- [[magento2:start|Magento 2 docs home]]
- [[magento2:extensions:toweringmedia-module-moneris|Magento 2 Moneris Payment Extension]]
- [[magento2:extensions:toweringmedia-module-authorizenet|Magento 2 Authorize.Net Payment Extension]]
- [[magento2:extensions:toweringmedia-module-react-checkout-pro-express|Magento 2 React Checkout Pro Express Extension]]