> 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/salesforce-commerce-cloud.md).

# Salesforce Commerce Cloud (SFCC)

Add Apple Wallet and Google Wallet buttons to a Salesforce Commerce Cloud storefront with a cartridge, server-side HMAC signing and The Wallet Crew SDK.

This integration explains how to add a **unique “Add to Wallet” button** to a Salesforce Commerce Cloud storefront. Common placements are the **My Account** area (loyalty or membership pass) and authenticated pages where a stable identifier is available (for example a gift card list). Pick & collect pages can also be a fit when a pickup pass is used as an in-store scan token.

## SFCC concepts used in this integration

Salesforce Commerce Cloud storefront code is packaged and deployed as **cartridges**. A cartridge can add controllers, scripts, templates, and configuration metadata, then be plugged into a site by adding it to the **cartridge path**.

This guide assumes one dedicated cartridge is created for The Wallet Crew integration, typically named like `int_TheWalletCrew`. The cartridge is then referenced by:

* the storefront application (SFRA or SiteGenesis)
* Business Manager configuration (site preferences and, optionally, custom objects)

Cartridge order matters because SFCC resolves templates and scripts by scanning the cartridge path from left to right.

The sample below targets SFRA: controllers and ISML templates, with the button added in an account template or a remote include. No SiteGenesis sample is provided: a SiteGenesis storefront adapts the entry points (pipelines) and keeps the same security model, with the HMAC computed server-side.

## 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 SFCC customer number as the external identifier key `sfcc.customerNo`.

## 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 identifier available on authenticated pages, such as:
  * SFCC `CustomerNo` (typical for loyalty cards)
  * pickup reference (typical for pick & collect pickup passes)
  * gift card id (when gift cards are stored in SFCC or a connected system)
* The external identifier key name agreed during onboarding (example: `sfcc.customerNo`).

## Implement the integration as a cartridge

{% stepper %}
{% step %}

#### Add the cartridge to the cartridge path

After deploying the integration cartridge to the instance, add it to the site’s cartridge path in Business Manager. The cartridge should be placed **before** the base storefront cartridge so overrides resolve correctly.

In Business Manager, open **Administration → Sites → Manage Sites**, select the site, then open the **Settings** tab. Add the cartridge to the **Cartridges** field (a colon-separated list: cartridges on the left take precedence) and click **Apply**.

{% hint style="info" %}
The key point is the **site-level cartridge path** (not the Business Manager one).
{% endhint %}
{% endstep %}

{% step %}

#### Store tenant configuration as site preferences

Tenant values and secrets should remain server-side. In SFCC, this is typically done with **custom site preferences**.

At minimum, these values are usually required.

<details>

<summary><strong>Recommended preferences (IDs, types, examples)</strong></summary>

These values are typically created as **site-level custom preferences** (not organization-level).

* `theWalletCrewTenantId` (String)\
  Example: `<tenantId>`
* `theWalletCrewHmacSecret` (Password)\
  Example: `<your-secret>`
* `theWalletCrewDefaultPassType` (String)\
  Example: `user`
* `theWalletCrewExternalIdentifierKey` (String)\
  Example: `sfcc.customerNo`
* `theWalletCrewLanguage` (String, optional)\
  Example: `fr`\
  When omitted, the SDK uses browser language detection.

</details>
{% endstep %}

{% step %}

#### Compute the HMAC server-side

SFCC server-side scripts can compute a SHA-256 HMAC using the tenant secret and the exact identifier value.

Common implementation choices:

* a helper script exposed by the cartridge, used by account controllers
* a decorator pattern that enriches the view model with `identifier` and `identifierHmac`
  {% endstep %}

{% step %}

#### Render the “Add to Wallet” button in ISML

The integration cartridge typically provides an ISML partial that can be included where needed (account dashboard, gift card list, pick & collect page).
{% endstep %}
{% endstepper %}

## External identifier conventions

### Recommended key naming convention

Keys are typically:

* namespaced with a prefix like `sfcc.`
* written in camelCase, without `_`

Examples:

* `sfcc.customerNo`
* `sfcc.pickupRef`
* `sfcc.giftCardId`

In the attribute, the key `sfcc.customerNo` is written `sfcc.customer_No`: see [How the Add to Wallet button works](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works). The prefix `neostore` is the platform's former name and is kept in technical identifiers.

{% hint style="info" %}
If The Wallet Crew tenant is already configured with a key, changing it can impact existing installations. A key naming change should be treated as a migration topic.
{% endhint %}

## Copy/paste SFRA reference implementation (controller + ISML partial)

This reference implementation uses:

* **site preferences** to store tenant configuration
* a **server-side HMAC helper**
* a **remote include controller** that renders an ISML partial

It is designed to be pasted into a dedicated cartridge (example: `int_TheWalletCrew`) and called from an account page.

### Cartridge file layout

* `cartridge/scripts/TheWalletCrew/hmac.js`
* `cartridge/controllers/TheWalletCrew.js`
* `cartridge/templates/default/TheWalletCrew/addToWalletButton.isml`

### 1) HMAC helper (`cartridge/scripts/TheWalletCrew/hmac.js`)

The Wallet Crew compares the hexadecimal HMAC without regard to case, so lower case and upper case are both accepted.

{% code title="cartridge/scripts/TheWalletCrew/hmac.js" %}

```javascript
'use strict';

var Mac = require('dw/crypto/Mac');
var Encoding = require('dw/crypto/Encoding');

/**
 * HMAC-SHA256 over the raw identifier string (UTF-8), encoded as hex.
 * Output is lowercased to match the SDK examples.
 */
function hmacSha256Hex(secret, identifierValue) {
    var mac = new Mac(Mac.HMAC_SHA_256);
    var bytes = mac.digest(identifierValue, secret);
    return Encoding.toHex(bytes).toLowerCase();
}

module.exports = {
    hmacSha256Hex: hmacSha256Hex
};
```

{% endcode %}

### 2) Controller (`cartridge/controllers/TheWalletCrew.js`)

This controller renders a widget that is safe to include as a remote include.

{% code title="cartridge/controllers/TheWalletCrew\.js" %}

```javascript
'use strict';

var server = require('server');
var Site = require('dw/system/Site');

var theWalletCrewHmac = require('*/cartridge/scripts/TheWalletCrew/hmac');

server.get('Button', function (req, res, next) {
    // Disable caching to avoid serving one customer’s identifier to another.
    // Cache-control strategy differs across SFRA baselines, so keep it explicit.
    res.setHttpHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
    res.setHttpHeader('Pragma', 'no-cache');

    var site = Site.getCurrent();
    var tenantId = site.getCustomPreferenceValue('theWalletCrewTenantId');
    var secret = site.getCustomPreferenceValue('theWalletCrewHmacSecret');
    var passType = site.getCustomPreferenceValue('theWalletCrewDefaultPassType') || 'user';
    var externalKey = site.getCustomPreferenceValue('theWalletCrewExternalIdentifierKey') || 'sfcc.customerNo';
    var language = site.getCustomPreferenceValue('theWalletCrewLanguage');

    // Example identifier: logged-in customer number.
    var identifierValue = (customer && customer.profile) ? customer.profile.customerNo : null;

    if (!tenantId || !secret || !identifierValue) {
        res.render('TheWalletCrew/addToWalletButton', { enabled: false });
        return next();
    }

    var identifierHmac = theWalletCrewHmac.hmacSha256Hex(secret, identifierValue);

    // Attribute names are lowercased by the browser: the SDK reads "_x" as "X".
    // Escape each uppercase letter of the key (sfcc.customerNo -> sfcc.customer_No).
    var attributeKey = externalKey.replace(/([A-Z])/g, '_$1');

    res.render('TheWalletCrew/addToWalletButton', {
        enabled: true,
        tenantId: tenantId,
        passType: passType,
        language: language,
        attributeKey: attributeKey,
        identifierValue: identifierValue,
        identifierHmac: identifierHmac
    });

    return next();
});

module.exports = server.exports();
```

{% endcode %}

### 3) ISML partial (`cartridge/templates/default/TheWalletCrew/addToWalletButton.isml`)

{% code title="cartridge/templates/default/TheWalletCrew/addToWalletButton.isml" %}

```html
<isif condition="${pdict.enabled}">
    <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, "${pdict.tenantId}", <isprint value="${pdict.language ? ('{ \"language\": \"' + pdict.language + '\" }') : '{ }'}" encoding="off" />);
    </script>

    <div
        data-neostore-addToWalletButton
        data-neostore-passType="${pdict.passType}"
        data-neostore-externalIdentifiers-${pdict.attributeKey}-value="${pdict.identifierValue}"
        data-neostore-externalIdentifiers-${pdict.attributeKey}-hmac="${pdict.identifierHmac}">
    </div>
</isif>
```

{% endcode %}

### 4) Include the widget in an account template

In SFRA, remote includes are commonly used to avoid polluting the main controller and to keep caching explicit.

{% code title="Example include (ISML)" %}

```html
<isinclude url="${URLUtils.url('TheWalletCrew-Button')}" />
```

{% endcode %}

## Content Security Policy (CSP)

In SFRA projects, CSP is often managed via middleware and response headers. The change should follow the project’s existing CSP strategy (report-only vs enforced). See the [CSP rule](https://docs.thewalletcrew.io/connectors/e-commerce.md#how-the-add-to-wallet-button-works).

## 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

See the [troubleshooting checks](https://docs.thewalletcrew.io/connectors/e-commerce.md#troubleshooting) of the e-commerce overview. The external identifier key name must match the one configured for SFCC (example: `sfcc.customerNo`).


---

# 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/salesforce-commerce-cloud.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.
