====== Magento 2 React Checkout Pro Bundle — User Guide ======

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

This is a Toweringmedia Magento 2 extension guide for the **React Checkout Pro Bundle**: a Hyvä-friendly, React-based checkout package with optional wallet payments. Use this page for installation, high-level configuration, and the **Apple Pay** setup workflow with **Authorize.net**, **React Checkout Pro**, and Magento Admin.

===== Product page =====

  * [[https://toweringmedia.com/magento-2-react-checkout-pro-bundle|Magento 2 React Checkout Pro Bundle — Shopify-Style Checkout Experience]]

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

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

===== Overview =====

The bundle delivers a **fast, single-page checkout** built in React—autosave-first, mobile-friendly, and aligned with production Magento practices (no unnecessary headless complexity).

  * Replaces the default multi-step checkout with one clear flow and step unlocking.
  * **Shopify-like autosave**: contact, addresses, shipping, and payment selections persist as the shopper moves through checkout.
  * Works with **guest checkout** or stricter account rules, depending on Magento checkout options.
  * Wallet flows (Apple Pay, Google Pay, PayPal) depend on installed payment modules, HTTPS, and correct merchant configuration—see the **Apple Pay** section below for a full Authorize.net + React Checkout Pro walkthrough.

**Example placeholders** used throughout this guide (not real clients): ''example.com'', ''staging.example.com'', ''merchant.com.example.production'', **Example Store**, **Example Company**.

===== What this extension does =====

  * React-based checkout optimized for conversion and performance
  * Single-page, step-unlocking checkout with autosave (no manual “Save” per step)
  * Optional express / wallet experiences when Express and payment modules are configured
  * Strong fit for Hyvä-compatible storefronts alongside standard Magento admin configuration

===== Installation =====

Install and validate in **staging** before production rollout.

<code bash>
cd /path/to/magento
# Install from your licensed Composer package (metapackage name from your agreement)
# composer require your-vendor/your-bundle-package
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
</code>

If your bundle ships a React Checkout Pro asset collection step, run the documented CLI for your release (for example ''toweringmedia:react-checkout-pro:collect'') after upgrade.

===== Configuration (high level) =====

  * React Checkout Pro: ''Stores > Configuration > Sales > Checkout React Pro'' (checkout takeover, express section, payment layout)—see [[magento2:extensions:toweringmedia-module-react-checkout-pro|React Checkout Pro Extension]].
  * Authorize.net (Toweringmedia): ''Stores > Configuration > Sales > Payment Methods > Authorize.Net (Toweringmedia)''—see [[magento2:extensions:toweringmedia-module-authorizenet|Authorize.Net Extension]].
  * **Apple Pay domain association (React Checkout Pro)**: ''Stores > Configuration > Toweringmedia > React Checkout Pro > Apple Pay (domain verification)''—detailed in the next section.
  * After changing payment or checkout config: flush Magento cache (and any **LiteMage / LiteSpeed** cache), and run your normal **Hyvä / React Checkout Pro** frontend build if your deployment process requires it.

===== Apple Pay Setup for Magento with Authorize.net and React Checkout Pro =====

This section walks through the complete Apple Pay setup for Magento when the checkout uses **Toweringmedia React Checkout Pro** and payments are processed through **Authorize.net**. Apple Pay setup has three separate pieces that are easy to mix up:

  * **Domain verification**: proves to Apple that the checkout domain is allowed to show Apple Pay.
  * **Payment Processing Certificate**: generated from an **Authorize.net CSR** and used by the processor.
  * **Merchant Identity Certificate**: generated from a **server CSR** and used by Magento for Apple Pay merchant validation.

Do these in order. The files are not interchangeable.

**Example values** (placeholders only):

^ Item ^ Example ^
| Staging domain | ''staging.example.com'' |
| Live domain | ''example.com'' |
| Apple Merchant ID | ''merchant.com.example.production'' |
| Apple Pay display name | **Example Store** |

The same Apple Merchant ID can usually be used for staging and production. Every domain or subdomain where the Apple Pay button appears must still be added and verified in Apple Developer, for example ''staging.example.com'', ''example.com'', and ''www.example.com''.

**File and certificate reference**

^ File ^ Purpose ^ Used for ^
| ''CertificateRequest_csr.txt'' | CSR generated by **Authorize.net** | Upload to Apple when creating the **Apple Pay Payment Processing Certificate** |
| ''apple_pay.cer'' | **Apple Pay Payment Processing Certificate** downloaded from Apple | Generated from the Authorize.net CSR; retain for processor/payment records |
| ''applepay_merchant_identity.key'' | **Private key** generated on the **server** | Paste into Magento Admin as **Apple Pay Merchant Key (PEM)**—**never** give this to Apple |
| ''applepay_merchant_identity.csr'' | CSR generated **from the server private key** | Upload to Apple when creating the **Apple Pay Merchant Identity Certificate** |
| ''merchant_id.cer'' (or saved as ''merchant_identity.cer'') | **Merchant Identity Certificate** downloaded from Apple | Upload to server, convert to PEM, paste into Magento as **Apple Pay Merchant Cert (PEM)** |

**Critical security rules**

  * Never upload the ''.key'' private key file to Apple.
  * Never place Apple Pay private keys or identity certificate files under ''pub/''.
  * Never commit Apple Pay keys, CSRs, or certificates to Git.
  * Never paste real private key contents, certificate contents, merchant credentials, or client domains into public docs or tickets.
  * The only Apple Pay file that should be publicly reachable is ''/.well-known/apple-developer-merchantid-domain-association''.

**Step 1: Create or open the Apple Merchant ID**

In Apple Developer:

  - Go to **Certificates, Identifiers & Profiles**.
  - Open **Identifiers**.
  - Filter by **Merchant IDs**.
  - Create or open the Merchant ID, for example ''merchant.com.example.production''.

Use a clear merchant identifier that belongs to the store/brand and environment strategy. For this reusable example, use ''merchant.com.example.production''.

----

**Step 2: Add and verify the checkout domain**

Inside the Apple Merchant ID, scroll to **Merchant Domains** and add each checkout hostname **without** a protocol:

  * ''staging.example.com''
  * ''example.com''
  * ''www.example.com''

Only add domains where Apple Pay actually appears. Apple verifies each domain by requesting this public URL:

''/.well-known/apple-developer-merchantid-domain-association''

Example staging verification URL:

<code>
https://staging.example.com/.well-known/apple-developer-merchantid-domain-association
</code>

That URL must return the raw plain text association file contents. It must not return a Magento 404 page, generic HTML, a redirect, a login page, HTTP auth, or a maintenance interstitial.

**Step 3: Configure the React Checkout Pro domain association file**

In Magento Admin, open:

''Stores → Configuration → Toweringmedia → React Checkout Pro → Apple Pay (domain verification)''

Paste the **full Apple domain association file contents** into **Domain association file contents**. React Checkout Pro should then serve that content from:

''/.well-known/apple-developer-merchantid-domain-association''

Re-test the public URL before clicking **Verify** in Apple Developer:

<code>
https://staging.example.com/.well-known/apple-developer-merchantid-domain-association
</code>

Expected result: plain text only. If the response is HTML, a 404, a redirect, or blocked by staging restrictions, fix that before continuing.

----

**Step 4: Generate the Authorize.net Apple Pay CSR**

In Authorize.net:

  - Go to **Account** → **Digital Payment Solutions** → **Apple Pay**.
  - Enter the Apple Merchant ID, for example ''merchant.com.example.production''.
  - Click **Generate Apple CSR**.
  - Download the CSR, for example ''CertificateRequest_csr.txt''.

This CSR belongs to Authorize.net. It is used only for the Apple Pay **Payment Processing Certificate**.

**Step 5: Create the Apple Pay Payment Processing Certificate**

In Apple Developer:

  - Go to **Certificates, Identifiers & Profiles** → **Identifiers** → **Merchant IDs**.
  - Open ''merchant.com.example.production''.
  - Under **Apple Pay Payment Processing Certificate**, choose **Create Certificate**.
  - Upload ''CertificateRequest_csr.txt'' from Authorize.net.
  - Download the resulting certificate, for example ''apple_pay.cer''.

Do not upload a ''.cer'' file where Apple asks for a CSR. Do not upload the server-generated Merchant Identity CSR in this Payment Processing Certificate step.

----

**Step 6: Generate the Merchant Identity private key and CSR on the Magento server**

The Merchant Identity certificate/key pair is what Magento uses for Apple Pay merchant validation. It is separate from the Authorize.net payment processing certificate.

Run from the Magento root:

<code bash>
cd /path/to/magento/root
mkdir -p var/applepay
chmod 700 var/applepay
cd var/applepay

openssl genrsa -out applepay_merchant_identity.key 2048
chmod 600 applepay_merchant_identity.key

openssl req -new \
  -key applepay_merchant_identity.key \
  -out applepay_merchant_identity.csr \
  -subj "/CN=merchant.com.example.production/O=Example Company/C=US"
</code>

Result:

  * ''applepay_merchant_identity.key'' — private key; keep on the server and never upload to Apple.
  * ''applepay_merchant_identity.csr'' — CSR to upload to Apple for the Merchant Identity Certificate.

Download only ''applepay_merchant_identity.csr'' to your local machine for the Apple upload. Do not upload or share ''applepay_merchant_identity.key'' except through an approved secure backup process.

**Step 7: Create the Apple Pay Merchant Identity Certificate**

In Apple Developer:

  - Go to **Certificates, Identifiers & Profiles** → **Identifiers** → **Merchant IDs**.
  - Open ''merchant.com.example.production''.
  - Under **Apple Pay Merchant Identity Certificate**, choose **Create Certificate**.
  - Upload ''applepay_merchant_identity.csr'' from the Magento server.
  - Download the resulting certificate, for example ''merchant_id.cer''.

Do not upload these files in this step:

  * ''applepay_merchant_identity.key''
  * ''apple_pay.cer''
  * ''merchant_id.cer''
  * ''CertificateRequest_csr.txt''

The downloaded Merchant Identity certificate must match the private key generated on the server. If the CSR came from a different machine or different key, Magento merchant validation will fail.

----

**Step 8: Upload and convert the Merchant Identity certificate to PEM**

Upload Apple’s new certificate to:

''var/applepay/merchant_id.cer''

Then convert it on the server:

<code bash>
cd /path/to/magento/root/var/applepay
mv merchant_id.cer merchant_identity.cer

openssl x509 -inform DER \
  -in merchant_identity.cer \
  -out applepay_merchant_identity.pem
</code>

Result:

  * ''applepay_merchant_identity.pem'' — paste into Magento as the Merchant Cert PEM.
  * ''applepay_merchant_identity.key'' — paste into Magento as the Merchant Key PEM.

**Step 9: Configure Apple Pay in Magento Admin**

Open the relevant payment configuration screen, usually:

''Stores > Configuration > Sales > Payment Methods > Authorize.Net (Toweringmedia)''

Set:

^ Field ^ Value ^
| **Enable Apple Pay** | **Yes** |
| **Apple Pay Merchant ID** | ''merchant.com.example.production'' |
| **Apple Pay Display Name** | **Example Store** |
| **Apple Pay Domain** | ''staging.example.com'' |

Enter only the hostname in the domain field. Do not include the protocol prefix. For live, use ''example.com'' or ''www.example.com'', whichever domain actually hosts checkout and is verified in Apple Developer.

For **Apple Pay Merchant Cert (PEM)**, run:

<code bash>
cat var/applepay/applepay_merchant_identity.pem
</code>

Paste the full output. It must include:

<code>
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
</code>

For **Apple Pay Merchant Key (PEM)**, run:

<code bash>
cat var/applepay/applepay_merchant_identity.key
</code>

Paste the full output. It must include either:

<code>
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
</code>

or:

<code>
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
</code>

Leave **Apple Pay Key Passphrase** blank unless the private key was intentionally created with a passphrase. The ''openssl genrsa'' command in this guide does not create a passphrase-protected key.

Save config at the correct website/store scope.

----

**Step 10: Flush cache and rebuild frontend assets if needed**

<code bash>
php bin/magento cache:clean config full_page
php bin/magento cache:flush
</code>

Also clear LiteMage/LiteSpeed or CDN cache if active. If checkout assets changed, run the project’s normal Hyvä / React Checkout Pro build process.

**Step 11: Test Apple Pay**

Use Safari on a device and Apple ID that support Apple Pay:

  * Open checkout on the HTTPS staging domain, for example ''staging.example.com''.
  * Confirm the Apple Pay button appears.
  * Click or tap Apple Pay.
  * Confirm the Apple Pay sheet opens.
  * Complete a controlled staging/sandbox test if configured.

If the sheet opens, merchant validation is usually working. If the button does not show or the sheet fails, continue with the checks below.

----

**Troubleshooting: Apple says “Invalid CSR”**

The wrong file was uploaded. A CSR usually starts with:

<code>
-----BEGIN CERTIFICATE REQUEST-----
</code>

or:

<code>
-----BEGIN NEW CERTIFICATE REQUEST-----
</code>

A certificate starts with:

<code>
-----BEGIN CERTIFICATE-----
</code>

Do not upload certificates where Apple asks for a CSR.

**Troubleshooting: Apple Pay button does not show**

Check:

  * Apple Pay is enabled in Magento Admin at the correct scope.
  * Checkout is loaded in Safari.
  * The device/account supports Apple Pay.
  * The payment method is enabled for the current website/store.
  * Express checkout or wallet display is enabled if React Checkout Pro controls wallet placement.
  * Magento, LiteMage/LiteSpeed, and CDN caches are cleared.

**Troubleshooting: Apple Pay sheet opens but merchant validation fails**

Check:

  * Apple Pay Domain exactly matches the current checkout domain.
  * Domain is verified in Apple Developer.
  * Domain association URL returns plain text publicly.
  * Merchant Identity Cert PEM and Merchant Identity Key PEM are complete and pasted into the correct fields.
  * The certificate was created from the CSR generated by the matching server private key.
  * HTTP auth, firewall, Cloudflare/WAF, redirects, or staging restrictions are not blocking Apple’s validation request.

**Troubleshooting: certificate/key mismatch**

Fix by creating a fresh matching pair:

  - Generate a new private key on the server.
  - Generate a new CSR from that key.
  - Upload the CSR to Apple under **Merchant Identity Certificate**.
  - Download the new certificate.
  - Convert the certificate to PEM.
  - Paste the new cert PEM and matching key PEM into Magento.

**Security notes**

Never place these files in ''pub/'':

  * ''applepay_merchant_identity.key''
  * ''applepay_merchant_identity.csr''
  * ''merchant_identity.cer''
  * ''applepay_merchant_identity.pem''

Recommended server location:

''var/applepay/''

<code bash>
chmod 700 var/applepay
chmod 600 var/applepay/applepay_merchant_identity.key
</code>

The only Apple Pay-related file that should be publicly accessible is:

''/.well-known/apple-developer-merchantid-domain-association''

React Checkout Pro can serve that file from Magento Admin configuration.

----

**Quick end-to-end checklist**

  - Apple Developer: create/open Merchant ID.
  - Apple Developer: add and verify ''staging.example.com''.
  - React Checkout Pro: paste Apple domain association file contents.
  - Authorize.net: generate Apple CSR.
  - Apple Developer: upload Authorize.net CSR under **Apple Pay Payment Processing Certificate**.
  - Server: generate Merchant Identity private key and CSR.
  - Apple Developer: upload server-generated CSR under **Apple Pay Merchant Identity Certificate**.
  - Server: upload new ''merchant_id.cer'' and convert to PEM.
  - Magento Admin: paste Merchant ID, display name, domain, Merchant Identity cert PEM, and private key PEM.
  - Magento: save config and flush cache.
  - Safari: test Apple Pay on staging.

===== Validation checklist =====

  * Settings save correctly at the expected **configuration scope**.
  * ''/checkout'' (or your bundle’s checkout route) loads React Checkout Pro as expected.
  * Primary card flow and **Apple Pay** (when enabled) behave correctly after cache clears.
  * No critical errors in logs for primary happy-path and payment tests.
  * Domain association URL returns **plain text** for each verified host.

===== Troubleshooting (general) =====

  * **No expected behavior**: verify module enablement, Composer versions, and config scope.
  * **Checkout or payment errors**: confirm related modules (React Checkout Pro, Authorize.net, Express) and Authorize.net credentials/sandbox vs production endpoints.
  * **Stale frontend**: flush Magento cache, front proxies (LiteSpeed/LiteMage, CDN), and redeploy static content when applicable.

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

  * [[magento2:extensions:start|Magento 2 extension index]]
  * [[start|Global docs home]]