@improntus/saas-app-storefront-mercadopago

NPM package that installs the Mercado Pago checkout redirect integration for Adobe Commerce dropins storefronts running on AEM Edge Delivery Services (EDS).

It packages the mercadopago-payment block and applies the required storefront integration patches for:

• checkout payment method rendering
• place-order Mercado Pago redirect flow
• guest/authenticated return handling
• checkout GraphQL fragment extension for OOPE payment configuration
• checkout overlay copy during Mercado Pago steps (monolithic and boilerplate loaders; see below)

Requirements

• Storefront based on Adobe Commerce dropins and EDS (for example, aem-boilerplate-commerce).
• Standard storefront structure (blocks, scripts/initializers, build.mjs).
• Mercado Pago payment method configured in Adobe Commerce as oope_mercadopago.
• Backend endpoint available in oope_payment_method_config.backend_integration_url (createPreferenceUrl).

Installation

Run from your storefront project root:

npm install @improntus/saas-app-storefront-mercadopago

The package runs postinstall automatically and does the following:

1. Copies assets/blocks/mercadopago-payment/* to blocks/mercadopago-payment/.
2. Patches scripts/initializers/index.js to load order-details-path-normalize.js.
3. Patches scripts/initializers/checkout.js to expose payment method data in the checkout transformer (supports both an existing CartModel.transformer and the default mountImmediately(initialize, { langDefinitions }) boilerplate shape).
4. Patches build.mjs so @dropins/storefront-checkout GraphQL includes oope_payment_method_config on the payment sub-fragments used by current boilerplate (AVAILABLE_PAYMENT_METHOD_FRAGMENT and SELECTED_PAYMENT_METHOD_FRAGMENT). Older installers used a monolithic CHECKOUT_DATA_FRAGMENT patch; new installs upgrade that shape when detected.
5. Patches checkout integration:
   • Monolithic checkout (single commerce-checkout.js with Stripe-style slots): updates blocks/commerce-checkout/commerce-checkout.js only.
   • Boilerplate / fragments checkout (createCheckoutFragment pattern): updates blocks/commerce-checkout/commerce-checkout.js and blocks/commerce-checkout/containers.js (PaymentMethods slot).

The installer resolves the host project using INIT_CWD / npm_config_local_prefix so postinstall still targets your storefront root (not node_modules).

Files installed by the package

Files are copied from the published package into your storefront project root (the folder where you ran npm install).

| Source (in package) | Destination (in your project) | | --- | --- | | assets/blocks/mercadopago-payment/* | blocks/mercadopago-payment/ |

In addition, the install script (scripts/install.js, run from postinstall or npx storefront-mercadopago-install) may modify the following host files when they exist and match known patterns. Edits are idempotent (already-applied changes are skipped). If a file is missing or does not match, the script prints manual follow-up in the install report.

| Host file | What the installer does | | --- | --- | | scripts/initializers/index.js | Prepends import '../../blocks/mercadopago-payment/order-details-path-normalize.js'; if that line is not already present. | | scripts/initializers/checkout.js | Ensures checkout exposes available_payment_methods / selected_payment_method via CartModel.transformer, or injects a models.CartModel.transformer block into mountImmediately(initialize, { … }) for boilerplate-shaped initializers. | | build.mjs | Merges or replaces overrideGQLOperations entries for @dropins/storefront-checkout so oope_payment_method_config is present on AVAILABLE_PAYMENT_METHOD_FRAGMENT and SELECTED_PAYMENT_METHOD_FRAGMENT (and upgrades a legacy monolithic CHECKOUT_DATA_FRAGMENT override when detected). | | blocks/commerce-checkout/commerce-checkout.js | Monolithic storefronts: Mercado Pago imports, payment slot, handlePlaceOrder / order/placed / return-from-MP hooks, and loader cleanup guard. Boilerplate storefronts (createCheckoutFragment): same integration points plus spinnerTarget, placeOrderApi, and related wiring expected by mercadopago-checkout.js. | | blocks/commerce-checkout/containers.js | Boilerplate / fragments checkout only: imports the Mercado Pago block and registers [mercadopagoCheckout.MERCADOPAGO_CHECKOUT_PAYMENT_CODE] in the PaymentMethods slot (next to the FASTLANE slot pattern the script looks for). |

GraphQL overrides and drop-in rebuild (required)

@dropins/build-tools applies GraphQL extensions to files under node_modules/@dropins/<package>/fragments.js. Your storefront then copies those packages into scripts/__dropins__/ (for example via postinstall.js). The browser loads drop-ins from scripts/__dropins__/ (see head.html import map), not directly from the copies you may still have open under node_modules.

After build.mjs changes (from this package or by hand), you must regenerate and copy drop-ins:

npm run install:dropins

That command is typically node build.mjs && node postinstall.js: merge GraphQL into node_modules, then refresh scripts/__dropins__.

Newer checkout fragment shape (AEM Boilerplate Commerce 7.x / storefront-checkout 3.2+)

In current checkout drop-ins, CHECKOUT_DATA_FRAGMENT references payment methods through spreads:

• ...AVAILABLE_PAYMENT_METHOD_FRAGMENT
• ...SELECTED_PAYMENT_METHOD_FRAGMENT

Therefore OOPE fields must be merged into AVAILABLE_PAYMENT_METHOD_FRAGMENT and SELECTED_PAYMENT_METHOD_FRAGMENT, not by replacing the entire CHECKOUT_DATA_FRAGMENT on Cart. The package installer writes that shape into build.mjs.

Upgrading from an older Mercado Pago build.mjs patch

If a previous install added a monolithic fragment CHECKOUT_DATA_FRAGMENT on Cart { ... oope_payment_method_config ... } block, re-run the installer (or npx storefront-mercadopago-install): it will replace that legacy block with the sub-fragment overrides when it recognizes the old template.

Checkout overlay messages (mercadopago-checkout.js)

blocks/mercadopago-payment/mercadopago-checkout.js shows user-facing status text while the checkout loader is visible:

| Step | Message (Spanish) | | --- | --- | | After return from Mercado Pago | Confirmando estado de tu pago… | | Place order (before order/placed) | Procesando tu pedido… | | Before redirect to Mercado Pago | Conectando con Mercado Pago para finalizar el pago… |

Monolithic checkout usually implements displayOverlaySpinner({ message, ariaLabel }); those options are passed through directly.

Boilerplate / fragments checkout often uses displayOverlaySpinner(loaderRef, $loader) only. The block still passes spinnerTarget: { loaderRef, $loader } from the installer’s commerce-checkout.js patch; mercadopago-checkout.js then renders a .checkout__overlay-spinner-message node inside the loader container so the same copy appears. Styles for that class are in mercadopago-payment.css (.checkout__loader, .checkout__overlay-spinner-message).

Re-run Installer Manually

If you need to run it again:

npx storefront-mercadopago-install

Or:

node node_modules/@improntus/saas-app-storefront-mercadopago/scripts/install.js

Optional Manual Integration (Without Auto-Patching)

If you prefer manual changes, apply the following in your storefront:

1. Copy assets/blocks/mercadopago-payment/ to blocks/mercadopago-payment/.
2. In scripts/initializers/index.js, add:
   • import '../../blocks/mercadopago-payment/order-details-path-normalize.js';
3. In scripts/initializers/checkout.js, ensure CartModel.transformer returns:
   • availablePaymentMethods: data?.available_payment_methods
   • selectedPaymentMethod: data?.selected_payment_method
4. In build.mjs, under overrideGQLOperations, add or merge a @dropins/storefront-checkout entry whose operations extend both payment fragments (current boilerplate). Minimal shape:

{
  npm: '@dropins/storefront-checkout',
  operations: [
    `
          fragment AVAILABLE_PAYMENT_METHOD_FRAGMENT on AvailablePaymentMethod {
            code
            title
            oope_payment_method_config {
              backend_integration_url
              custom_config {
                ... on CustomConfigKeyValue {
                  key
                  value
                }
              }
            }
          }
        `,
    `
          fragment SELECTED_PAYMENT_METHOD_FRAGMENT on SelectedPaymentMethod {
            code
            title
            purchase_order_number
            oope_payment_method_config {
              backend_integration_url
              custom_config {
                ... on CustomConfigKeyValue {
                  key
                  value
                }
              }
            }
          }
        `,
  ],
},

Then run npm run install:dropins so scripts/__dropins__/storefront-checkout/fragments.js picks up the merged queries.

Validation Checklist

• After build.mjs changes, npm run install:dropins completed without errors.
• scripts/__dropins__/storefront-checkout/fragments.js contains oope_payment_method_config under the payment fragments (search the file if unsure).
• Mercado Pago payment method (oope_mercadopago) appears in checkout.
• Selecting Mercado Pago renders helper/banner correctly.
• Clicking place order triggers preference creation and redirects to Mercado Pago.
• Returning from Mercado Pago to checkout resolves to order details/order status correctly.
• Guest return flow restores order token when required.
• Authenticated flow avoids incorrect public order-details route handling.

Author