E-commerce
Add wallet buttons to e-commerce journeys to distribute account-linked Apple Wallet and Google Wallet passes, then use them in store with POS scanning.
E-commerce integration is typically an omnichannel topic. The goal is to let customers use the same account online and in-store, without requiring a mobile app. A wallet pass acts as a persistent, scannable credential that links the e-commerce identity to in-store systems through POS integration.
This approach reduces dependency on checkout emails and account logins at the point of sale. It also simplifies customer recognition, loyalty attribution, and benefit redemption across channels.
Core omnichannel use cases
In most retail programs, wallet passes distributed from e-commerce are account-linked, not order-linked. The pass represents an ongoing relationship (loyalty, membership, stored value). It stays stable over time and updates when the customer profile changes.
Common patterns:
Loyalty / membership pass: customer identifier + points + tier + benefits.
Wallet gift card: stored value + barcode/QR for redemption + balance updates.
Customer recognition at POS: scannable identifier that unlocks profile lookup and omnichannel attribution.
Pickup pass (pick & collect): order-linked, used when an in-store scan is required to release a prepared order.
Where to place “Add to Wallet” in e-commerce
Placement should match the moment the pass becomes useful as an account credential. In practice, this is usually when a customer is authenticated, or when enrolment is completed.
Updates and lifecycle (profile events → pass updates)
When profile data changes, the pass can be updated. Wallet apps can surface updates as native notifications. This keeps the pass trustworthy and reduces friction at the point of sale.
Typical update triggers in an omnichannel setup:
Points and tier changes after purchase (online or in-store)
Benefit eligibility changes (new perks, expired perks, special statuses)
Gift card balance changes after redemption or reload
Store preference changes (preferred store, local store list)
Pick & collect status changes (ready, delayed, collected) when a pickup pass is used
Pass content checklist (what to include)
The pass should answer “who is this customer account” and “what is currently available”. Everything else belongs behind a link to authenticated pages.
Recommended fields:
Brand name and support contact (email/phone/URL)
Membership / loyalty identifier (visible + scannable barcode/QR when needed)
Points balance, tier, and tier progress (when applicable)
Benefit summary (what can be used in-store and online)
Store list or store locator deep link (when relevant)
Deep links (account page, loyalty dashboard, gift card management, customer service)
If a pick & collect pass is implemented, the pass typically adds:
Pickup reference (not the full order)
Pickup location and window
Pickup QR/barcode used by staff
Implementation with The Wallet Crew
E-commerce integration typically combines distribution, profile linkage, and in-store scanning:
Create (or retrieve) the pass from a stable customer identifier (CRM id, loyalty id, e-commerce customer id).
Expose an “Add to Wallet” CTA in the e-commerce account journey.
Connect POS scanning so the pass can be used for identification and redemption in-store.
Send profile events to The Wallet Crew so the pass stays current (points, tier, balances, benefits).
The same “Add to Wallet” button can be embedded on any brand-controlled website page when a stable identifier or pass identifier is available server-side.
POS integration (what completes the omnichannel loop)
A wallet pass becomes the “missing link” between online and physical channels when it is scannable at the point of sale.
The common pattern is:
the pass encodes a stable identifier in a barcode/QR (or a secure token resolved server-side)
staff scan the pass at checkout
the POS (or a connected loyalty/CRM layer) uses that identifier to retrieve the customer profile, apply benefits, and attribute the transaction
POS integrations are documented under Point of Sale (POS).
How the Add to Wallet button works
This section owns the SDK explanation. The platform guides below link here and describe only what differs.
The browser SDK (called cinto in its script path and API) renders the right call to action for the device. On iOS, the button downloads an Apple Wallet pass. On Android, it opens Google Wallet. On desktop, it redirects to a hosted pass page that can be scanned or opened on a phone.
The SDK retrieves or creates a pass from three values:
a pass template (
passType, example:user)an external identifier: a key such as
sfcc.customerNoand the stable value of the logged-in customeran HMAC signature of that value, which proves that the brand backend issued the identifier
Rules that apply to every storefront:
Compute the HMAC server-side with the tenant secret. Never compute it in the browser, and never render the secret in HTML. Only the HMAC reaches the storefront. (The Shopify Liquid snippet is an exception, with its own risk: see Shopify.)
Include the SDK loader once per page. When a page has several buttons, load it in a shared partial and repeat only the button markup.
Do not cache customer-specific pages or fragments across customers. Check page cache, reverse proxy and CDN.
If the storefront sends a Content Security Policy, allow
https://sdk.neostore.cloudinscript-src.Keep identifier keys stable and namespaced (
magento.customerId). Changing a key on a live tenant is a migration.
The tenant secret is a general secret of The Wallet Crew: Secret 1 or Secret 2, in Settings → Access control → API keys & secrets, General secrets tab. The platform accepts an HMAC computed with either secret. To rotate, set the new value in the secret the storefront does not use, switch the storefront to it, then replace the old secret.
For generic SDK usage (pass id mode, platform detection, desktop QR customization), see On your website.
The prefix neostore is the platform's former name and is kept in technical identifiers. The SDK attributes (data-neostore-*), the script address (sdk.neostore.cloud) and the neostore.cinto.initialize call are real names and must be written as shown.
Attribute names are lowercased by the browser. In a data-neostore-externalIdentifiers-<key>-value (or -hmac) attribute, an underscore followed by a letter is read as that letter in uppercase: customer_Id and customer_id are both read as customerId. Write each uppercase letter of the key with an underscore before it, for example sfcc.customer_No for the key sfcc.customerNo. The escape applies to the attribute name only, not to the signed value.
A key that must contain an underscore cannot be passed as an attribute: pass it in the externalIdentifiers option of neostore.cinto.initialize() instead, for example { externalIdentifiers: { "sfcc.customer_no": { value: "...", hmac: "..." } } }.
Validate any storefront integration the same way:
On iOS Safari, the button reads Add to Apple Wallet.
On Android Chrome, it reads Add to Google Wallet.
On desktop, it redirects to a hosted pass page.
After installation, the pass is visible in Apple Wallet or Google Wallet.
The diagram shows how the storefront signs the identifier before the browser asks for the pass.
Troubleshooting
The button does not render
Common causes are a blocked SDK script (CSP) or missing markup. The final HTML should contain the SDK loader and the SDK container element (<div data-neostore-addToWalletButton ...>).
Clicking the button leads to an error
This usually means the external identifier or HMAC does not match what The Wallet Crew expects. Confirm:
the external identifier key name matches the one configured for the tenant
the identifier value matches exactly what is signed server-side (no trimming, formatting, or type changes)
the HMAC was computed with the correct tenant secret
The button renders for the wrong customer
This typically indicates HTML caching across sessions. Ensure that:
customer-specific pages are not cached at page level
remote includes or fragments used for account widgets are not cached across customers
any reverse proxy or CDN respects session cookies for authenticated pages
E-commerce platform guides
Use the platform-specific guides below when a storefront integration is required (typically in account pages or authenticated areas).
App theme block, or the Liquid snippet from the connector's Code snippet tab
The snippet signs customer.id in Liquid with the tenant general secret, embedded in the theme (see the warning on the Shopify page)
Cartridge with a controller and an ISML partial
Site preference of type Password
Module with a layout, a block and a PHTML template
app/etc/env.php or an environment variable
For in-store scanning with Shopify POS, see Shopify POS.
E-commerce platforms not listed
See Integrate software without a listed connector. For a custom storefront, use a custom connector: tenant scripting can call the storefront API and create, retrieve, or update passes.
FAQ
Last updated

