> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/e-commerce/adobe-commerce-magento.md).

# Adobe Commerce (Magento)

Magento (Adobe Commerce) integration to add Apple Wallet and Google Wallet “Add to Wallet” buttons in My Account for loyalty cards and gift cards.

This guide adds an “Add to Wallet” button to the **My Account** area of **Adobe Commerce (Magento 2)**, for a loyalty or membership pass (or a wallet gift card), using an identifier available in the Adobe Commerce customer session.

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-54466c25c788732b1d188eee7d08928f86e5a51d%2Fadobe-commerce-my-account-add-to-wallet.png?alt=media" alt="Adobe Commerce My Account page showing an “Add to Wallet” button."><figcaption><p>Target result: one “Add to Wallet” button rendered for the logged-in customer in My Account.</p></figcaption></figure>

Adobe Commerce and Magento Open Source share the same Magento 2 storefront architecture. The implementation patterns in this page apply to both, with minor differences in deployment and security configuration.

## How it works

The SDK, the HMAC rule, caching and CSP are explained in [How the Add to Wallet button works](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works). This guide uses the Magento customer identifier as the external identifier key `magento.customerId`.

## Prerequisites

* A pass template and pass issuance already configured in The Wallet Crew.
* The Wallet Crew tenant id available (used by the SDK script URL).
* A stable customer identifier available in the session on the account page. This identifier is used by The Wallet Crew to retrieve or create the pass. The identifier key name (example: `magento.customerId`) is defined during project onboarding.

## Add the button to the Adobe Commerce customer account page

Adobe Commerce storefront pages are built from **layout XML** and **PHTML templates**. Rendering the button from a Magento block keeps secrets server-side and enables safe escaping for HTML attributes.

The reference implementation below adds the button to the default customer dashboard page (`customer/account`).

### Store the secret used to compute HMAC

The HMAC secret must stay server-side. Two common options are used in Adobe Commerce projects.

**Option A (recommended): store values in `app/etc/env.php`**

Store values in deployment config so they are not editable from the Adobe Commerce Admin.

{% code title="app/etc/env.php (example)" %}

```php
<?php
return [
    // ...
    'walletcrew' => [
        'tenant_id' => '<tenantId>',
        'hmac_secret' => '<hmacSecret>',
    ],
];
```

{% endcode %}

**Option B: store the secret as an environment variable**

This keeps secrets out of the codebase and out of the database. It also works well with container deployments.

{% code title="Environment variables (example)" %}

```
THEWALLETCREW_TENANT_ID=<tenantId>
THEWALLETCREW_HMAC_SECRET=<hmacSecret>
```

{% endcode %}

{% hint style="info" %}
In **Adobe Commerce Cloud**, environment variables are often used as the source of truth for secrets. The `app/etc/env.php` file is commonly generated during deployment.
{% endhint %}

### Reference implementation (layout XML + block + PHTML)

This implementation creates:

* a **Block** class that reads the logged-in customer id and computes the HMAC
* a **PHTML template** that renders the SDK loader + `<div data-neostore-addToWalletButton ...>`
* a **layout XML** entry that inserts the block in the customer account dashboard

It also requires a minimal module scaffold so Adobe Commerce can load the files. The prefix `neostore` is the platform's former name and is kept in technical identifiers.

{% code title="app/code/Vendor/WalletCrewCinto/registration.php" %}

```php
<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Vendor_WalletCrewCinto',
    __DIR__
);
```

{% endcode %}

{% code title="app/code/Vendor/WalletCrewCinto/etc/module.xml" %}

```xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_WalletCrewCinto" setup_version="1.0.0"/>
</config>
```

{% endcode %}

After the files are deployed, enable the module and refresh generated files and caches.

{% code title="Enable the module (example)" %}

```bash
bin/magento module:enable Vendor_WalletCrewCinto
bin/magento setup:upgrade
bin/magento cache:flush
```

{% endcode %}

{% stepper %}
{% step %}

#### Add the layout XML on the customer dashboard

Add a layout update to inject a block into the dashboard content container.

{% code title="app/code/Vendor/WalletCrewCinto/view/frontend/layout/customer\_account\_index.xml" %}

```xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Vendor\WalletCrewCinto\Block\AddToWallet"
                   name="walletcrew.add_to_wallet"
                   template="Vendor_WalletCrewCinto::add-to-wallet.phtml"
                   cacheable="false"/>
        </referenceContainer>
    </body>
</page>
```

{% endcode %}

`cacheable="false"` ensures customer-specific identifiers are not cached across sessions.
{% endstep %}

{% step %}

#### Implement the Block (compute HMAC server-side)

The block reads the logged-in customer id and computes `hash_hmac('sha256', $value, $secret)`.

{% code title="app/code/Vendor/WalletCrewCinto/Block/AddToWallet.php" %}

```php
<?php
declare(strict_types=1);

namespace Vendor\WalletCrewCinto\Block;

use Magento\Customer\Model\Session as CustomerSession;
use Magento\Framework\App\DeploymentConfig;
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;

final class AddToWallet extends Template
{
    public function __construct(
        Template\Context $context,
        private readonly CustomerSession $customerSession,
        private readonly DeploymentConfig $deploymentConfig,
        private readonly Escaper $escaper,
        array $data = []
    ) {
        parent::__construct($context, $data);
    }

    public function getTenantId(): string
    {
        $fromEnvPhp = (string)($this->deploymentConfig->get('walletcrew/tenant_id') ?? '');
        if ($fromEnvPhp !== '') {
            return $fromEnvPhp;
        }

        return (string)(getenv('THEWALLETCREW_TENANT_ID'));
    }

    public function getCustomerId(): ?string
    {
        $id = $this->customerSession->getCustomerId();
        return $id ? (string)$id : null;
    }

    public function getCustomerIdHmac(): ?string
    {
        $customerId = $this->getCustomerId();
        if ($customerId === null) {
            return null;
        }

        $secret = (string)($this->deploymentConfig->get('walletcrew/hmac_secret') ?? '');
        if ($secret === '') {
            $secret = (string)(getenv('THEWALLETCREW_HMAC_SECRET'));
        }
        if ($secret === '') {
            return null;
        }

        return hash_hmac('sha256', $customerId, $secret);
    }

    public function escAttr(?string $value): string
    {
        return $this->escaper->escapeHtmlAttr((string)$value);
    }
}
```

{% endcode %}

{% hint style="info" %}
This example uses the Magento customer id as `magento.customerId`. If a CRM id is stored on the customer entity, it can be used instead.
{% endhint %}
{% endstep %}

{% step %}

#### Render the button in a PHTML template

The template injects tenant id, customer id, and HMAC from the block.

{% code title="app/code/Vendor/WalletCrewCinto/view/frontend/templates/add-to-wallet.phtml" %}

```php
<?php
/** @var \Vendor\WalletCrewCinto\Block\AddToWallet $block */
$tenantId = $block->getTenantId();
$customerId = $block->getCustomerId();
$hmac = $block->getCustomerIdHmac();

if (!$tenantId || !$customerId || !$hmac) {
    return;
}
?>

<script type="text/javascript">
(function (n, e, o) {
var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";s.async=1;
s.onload=function(){neostore.cinto.initialize(e,o)};n.body.appendChild(s);
})(document, "<?= $block->escAttr($tenantId) ?>", { language: "fr" });
</script>

<div data-neostore-addToWalletButton
     data-neostore-passType="user"
     data-neostore-externalIdentifiers-magento.customer_Id-value="<?= $block->escAttr($customerId) ?>"
     data-neostore-externalIdentifiers-magento.customer_Id-hmac="<?= $block->escAttr($hmac) ?>"
></div>
```

{% endcode %}

Browsers lowercase attribute names, so the key `magento.customerId` is written `magento.customer_Id` in the attribute: the SDK reads an underscore followed by a letter as that letter in uppercase. See [How the Add to Wallet button works](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works).

`fr` is a sample value. If a different language is required, update `{ language: "fr" }`. If omitted, the SDK uses the browser language.

{% hint style="info" %}
The full SDK documentation (options, desktop fallback, and platform detection) is available in [On your website](https://docs.thewalletcrew.io/guides-enrolment/enrolment/on-your-website.md).
{% endhint %}
{% endstep %}
{% endstepper %}

### Optional: Adobe Commerce CSP allowlist

If the SDK script is blocked by a Content Security Policy, see the [CSP rule](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works).

{% hint style="info" %}
Magento CSP configuration differs across versions and setups. If CSP is enabled, alignment with the project’s existing CSP strategy is required.
{% endhint %}

If the project uses Magento’s CSP whitelist mechanism, allowlisting the SDK host for `script-src` is usually enough.

{% code title="app/code/Vendor/WalletCrewCinto/etc/csp\_whitelist.xml (example)" %}

```xml
<?xml version="1.0"?>
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <policy id="script-src">
            <values>
                <value id="walletcrew-sdk" type="host">https://sdk.neostore.cloud</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>
```

{% endcode %}

{% hint style="warning" %}
Adobe Commerce projects often centralize CSP management (report-only vs enforced). The allowlist location and process should match project conventions.
{% endhint %}

## Validate the result

Follow the [validation steps](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works) of the e-commerce overview.

## Troubleshooting

Start with the [troubleshooting checks](https://docs.thewalletcrew.io/connectors/e-commerce.md#troubleshooting) of the e-commerce overview. In the attribute, the key `magento.customerId` is written `magento.customer_Id`.

**The wrong language is displayed**

Set `{ language: "fr" }` (or another ISO 639 language code) in the `initialize()` options.

## FAQ

<details>

<summary><strong>Does this require a custom module?</strong></summary>

Not strictly. A theme override can be enough when server-side values for the customer identifier and HMAC can be rendered. A custom module is usually preferred because it keeps HMAC computation out of templates and centralizes secret loading (deployment config or environment variables).

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/connectors/e-commerce/adobe-commerce-magento.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
