> 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/fr/e-commerce.md).

# E-commerce

Ajouter des boutons Wallet aux parcours e-commerce pour distribuer des cartes Apple Wallet et Google Wallet liées au compte, puis les utiliser en magasin avec le scan POS.

L’intégration du commerce électronique est généralement un **omnicanal** sujet. L’objectif est de permettre aux clients d’utiliser le même compte en ligne et en magasin, sans nécessiter d’application mobile. Une carte Wallet sert d’identifiant persistant et scannable qui relie l’identité e-commerce aux systèmes en magasin via l’intégration POS.

Cette approche réduit la dépendance aux e-mails de caisse et aux connexions au compte au point de vente. Elle simplifie aussi la reconnaissance client, l’attribution de la fidélité et l’utilisation des avantages sur l’ensemble des canaux.

<details>

<summary><strong>Exemples concrets</strong></summary>

* Fidélité retail : une carte de fidélité est ajoutée depuis la page du compte e-commerce, puis scannée en magasin pour rattacher les achats au profil.
* Clienteling : le code-barres d’une carte d’adhésion est scanné pour récupérer le niveau et les avantages dans le POS ou les outils de clienteling.
* Cartes-cadeaux : une carte-cadeau Wallet est ajoutée depuis l’espace compte, puis mise à jour à mesure que le solde évolue après les utilisations.
* Click & collect : une carte de retrait est émise pour le parcours de collecte, puis scannée en magasin pour libérer la commande.

</details>

## Cas d’usage omnicanaux principaux

Dans la plupart des programmes retail, les cartes Wallet distribuées depuis l’e-commerce sont **liées au compte**, pas **liées à la commande**. La carte représente une relation continue (fidélité, adhésion, valeur stockée). Elle reste stable dans le temps et se met à jour lorsque le profil client change.

Schémas courants :

* **Carte de fidélité / d’adhésion**: identifiant client + points + niveau + avantages.
* **Carte-cadeau Wallet**: valeur stockée + code-barres/QR pour l’utilisation + mises à jour du solde.
* **Reconnaissance client au POS**: identifiant scannable qui permet la recherche du profil et l’attribution omnicanale.
* **Carte de retrait (pick & collect)**: liée à la commande, utilisée lorsqu’un scan en magasin est nécessaire pour libérer une commande préparée.

## Où placer « Add to Wallet » dans l’e-commerce

Le placement doit correspondre au moment où la carte devient utile comme identifiant de compte. En pratique, c’est généralement lorsque le client est authentifié, ou lorsque l’inscription est terminée.

{% stepper %}
{% step %}

### Espace Mon compte / profil (principal)

L’espace compte est l’emplacement le plus stable. Il fonctionne pour la fidélité et l’adhésion, prend en charge les parcours de réinstallation et évite de lier le cycle de vie de la carte à une seule commande.
{% endstep %}

{% step %}

### Moments post-inscription / post-connexion (secondaire)

Après une inscription ou une connexion, un CTA « Add to Wallet » peut être affiché dans le cadre de l’onboarding. C’est souvent le moment le plus propice pour les nouveaux membres du programme.
{% endstep %}

{% step %}

### E-mail transactionnel (solution de repli)

L’e-mail est utile comme canal de récupération. Il aide lorsque le CTA web est manqué, lorsque l’achat est finalisé sur ordinateur, ou lorsque le client change d’appareil.
{% endstep %}

{% step %}

### Pages pick & collect (exception liée à la commande)

Lorsque la carte est utilisée comme jeton de retrait, le meilleur emplacement se trouve dans le parcours pick & collect (page de confirmation et/ou page de retrait dédiée). Cela limite les cartes liées à la commande aux cas où un scan en magasin est opérationnellement nécessaire.
{% endstep %}
{% endstepper %}

## Mises à jour et cycle de vie (événements de profil → mises à jour de la carte)

Lorsque les données de profil changent, la carte peut être mise à jour. Les applications Wallet peuvent afficher les mises à jour sous forme de notifications natives. Cela rend la carte plus fiable et réduit les frictions au point de vente.

Déclencheurs de mise à jour typiques dans une configuration omnicanale :

* Modifications des points et du niveau après achat (en ligne ou en magasin)
* Modifications de l’éligibilité aux avantages (nouveaux avantages, avantages expirés, statuts spéciaux)
* Modifications du solde de la carte-cadeau après utilisation ou rechargement
* Modifications des préférences de magasin (magasin préféré, liste des magasins locaux)
* Modifications du statut pick & collect (prête, retardée, retirée) lorsqu’une carte de retrait est utilisée

{% hint style="info" %}
Les notifications Wallet sont liées à une carte installée. Elles ne nécessitent pas l’installation d’une application mobile.
{% endhint %}

## Liste de contrôle du contenu de la carte (quoi inclure)

La carte doit répondre à « quel est ce compte client » et « qu’est-ce qui est actuellement disponible ». Tout le reste doit se trouver derrière un lien vers des pages authentifiées.

Champs recommandés :

* Nom de la marque et contact du support (e-mail/téléphone/URL)
* Identifiant d’adhésion / de fidélité (visible + code-barres/QR scannable si nécessaire)
* Solde de points, niveau et progression du niveau (le cas échéant)
* Résumé des avantages (ce qui peut être utilisé en magasin et en ligne)
* Liste des magasins ou lien profond vers le localisateur de magasins (le cas échéant)
* Liens profonds (page du compte, tableau de bord de fidélité, gestion de carte-cadeau, service client)

Si une carte pick & collect est mise en place, la carte ajoute généralement :

* Référence de retrait (pas la commande complète)
* Lieu et créneau de retrait
* QR/code-barres de retrait utilisé par le personnel

## Mise en œuvre avec The Wallet Crew

L’intégration e-commerce combine généralement la distribution, le rattachement au profil et le scan en magasin :

1. Créer (ou récupérer) la carte à partir d’un identifiant client stable (id CRM, id de fidélité, id client e-commerce).
2. Afficher un CTA « Add to Wallet » dans le parcours compte e-commerce.
3. Connecter le scan POS afin que la carte puisse être utilisée pour l’identification et l’utilisation en magasin.
4. Envoyer les événements de profil à The Wallet Crew afin que la carte reste à jour (points, niveau, soldes, avantages).

Le même bouton « Add to Wallet » peut être intégré sur n’importe quelle page de site contrôlée par la marque lorsqu’un identifiant stable ou un identifiant de carte est disponible côté serveur.

### Intégration POS (ce qui complète la boucle omnicanale)

Une carte Wallet devient le « maillon manquant » entre les canaux en ligne et physiques lorsqu’elle peut être scannée au point de vente.

Le schéma courant est :

* la carte encode un identifiant stable dans un code-barres/QR (ou un jeton sécurisé résolu côté serveur)
* le personnel scanne la carte à la caisse
* le POS (ou une couche fidélité/CRM connectée) utilise cet identifiant pour récupérer le profil client, appliquer les avantages et attribuer la transaction

Les intégrations POS sont documentées sous [Point de vente (POS)](https://docs.thewalletcrew.io/connectors/fr/pos.md).

## Fonctionnement du bouton Ajouter à Wallet

Cette section contient l’explication du SDK. Les guides de plateforme ci-dessous pointent ici et ne décrivent que ce qui diffère.

Le SDK du navigateur (appelé `cinto` dans son chemin de script et son API) affiche le bon appel à l’action selon l’appareil. Sur iOS, le bouton télécharge une carte Apple Wallet. Sur Android, il ouvre Google Wallet. Sur ordinateur, il redirige vers une page de carte hébergée qui peut être scannée ou ouverte sur un téléphone.

Le SDK récupère ou crée une carte à partir de trois valeurs :

* un **modèle de carte** (`passType`, par exemple : `user`)
* un **identifiant externe**: une clé telle que `sfcc.customerNo` et la valeur stable du client connecté
* un **HMAC** signature de cette valeur, qui prouve que le back-end de la marque a émis l’identifiant

Règles applicables à chaque boutique :

* Calculez le HMAC côté serveur avec le secret du tenant. Ne le calculez jamais dans le navigateur, et n’affichez jamais le secret dans le HTML. Seul le HMAC parvient à la boutique. (L’extrait Shopify Liquid constitue une exception, avec son propre risque : voir [Shopify](https://docs.thewalletcrew.io/connectors/fr/e-commerce/shopify.md#liquid-code-snippet-without-the-app).)
* Incluez le chargeur du SDK une seule fois par page. Lorsqu’une page comporte plusieurs boutons, chargez-le dans un fragment partagé et répétez uniquement le balisage du bouton.
* Ne mettez pas en cache les pages ou fragments spécifiques aux clients d’un client à l’autre. Vérifiez le cache de page, le reverse proxy et le CDN.
* Si la boutique envoie une Content Security Policy, autorisez `https://sdk.neostore.cloud` dans `script-src`.
* Conservez des clés d’identifiant stables et nommées dans un espace de noms (`magento.customerId`). Changer une clé sur un tenant en production constitue une migration.

Le secret du tenant est un secret général de The Wallet Crew : **Secret 1** ou **Secret 2**, dans **Paramètres → Contrôle d’accès → Clés API et secrets**, **Secrets généraux** onglet. La plateforme accepte un HMAC calculé avec l’un ou l’autre secret. Pour procéder à la rotation, définissez la nouvelle valeur dans le secret que la boutique n’utilise pas, basculez la boutique dessus, puis remplacez l’ancien secret.

Pour une utilisation générique du SDK (mode d’identifiant de carte, détection de plateforme, personnalisation du QR pour ordinateur), voir [Sur votre site web](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/on-your-website.md).

Le préfixe `neostore` est l’ancien nom de la plateforme et est conservé dans les identifiants techniques. Les attributs du SDK (`data-neostore-*`), l’adresse du script (`sdk.neostore.cloud`) et l’ `neostore.cinto.initialize` appel sont des noms réels et doivent être écrits tels quels.

Les noms d’attributs sont mis en minuscules par le navigateur. Dans un `data-neostore-externalIdentifiers-<key>-value` (ou `-hmac`) , un underscore suivi d’une lettre est lu comme cette lettre en majuscule : `customer_Id` et `customer_id` sont tous deux lus comme `customerId`. Écrivez chaque lettre majuscule de la clé avec un underscore devant, par exemple `sfcc.customer_No` pour la clé `sfcc.customerNo`. L’échappement s’applique uniquement au nom de l’attribut, pas à la valeur signée.

Une clé qui doit contenir un underscore ne peut pas être transmise comme attribut : transmettez-la dans l’ `externalIdentifiers` option de `neostore.cinto.initialize()` à la place, par exemple `{ externalIdentifiers: { "sfcc.customer_no": { value: "...", hmac: "..." } } }`.

Validez toute intégration de boutique de la même manière :

1. Dans Safari sur iOS, le bouton affiche **Ajouter à Apple Wallet**.
2. Dans Chrome sur Android, il affiche **Ajouter à Google Wallet**.
3. Sur ordinateur, il redirige vers une page de carte hébergée.
4. Après installation, la carte est visible dans Apple Wallet ou Google Wallet.

Le schéma montre comment la boutique signe l’identifiant avant que le navigateur ne demande la carte.

```mermaid
sequenceDiagram
    participant B as Navigateur
    participant S as serveur de la boutique
    participant T as The Wallet Crew
    B->>S: Demande de la page du compte
    S->>S: Signe l’identifiant client avec le secret du tenant
    S-->>B: Page avec le bouton, l’identifiant et le HMAC
    B->>T: Le SDK se charge et envoie l’identifiant et le HMAC
    T-->>B: carte Apple Wallet ou Google Wallet
```

### Dépannage

#### Le bouton ne s’affiche pas

Les causes courantes sont un script SDK bloqué (CSP) ou un balisage manquant. Le HTML final doit contenir le chargeur du SDK et l’élément conteneur du SDK (`<div data-neostore-addToWalletButton ...>`).

#### Cliquer sur le bouton entraîne une erreur

Cela signifie généralement que l’identifiant externe ou le HMAC ne correspond pas à ce que The Wallet Crew attend. Vérifiez :

* le nom de la clé de l’identifiant externe correspond à celui configuré pour le tenant
* la valeur de l’identifiant correspond exactement à ce qui est signé côté serveur (aucun trimming, formatage ou changement de type)
* le HMAC a été calculé avec le bon secret de tenant

#### Le bouton s’affiche pour le mauvais client

Cela indique généralement un cache HTML partagé entre les sessions. Veillez à ce que :

* les pages spécifiques à un client ne soient pas mises en cache au niveau de la page
* les inclusions distantes ou fragments utilisés pour les widgets de compte ne soient pas mis en cache d’un client à l’autre
* tout reverse proxy ou CDN respecte les cookies de session pour les pages authentifiées

## Guides des plateformes e-commerce

Utilisez les guides spécifiques à la plateforme ci-dessous lorsqu’une intégration de boutique est requise (généralement sur les pages de compte ou les zones authentifiées).

| Plateforme                                                                                                       | Type d’intégration                                                                | Où se trouve le secret HMAC                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Shopify](https://docs.thewalletcrew.io/connectors/fr/e-commerce/shopify.md)                                     | Bloc du thème de l’application, ou l’extrait Liquid du **Extrait de code** onglet | L’extrait signe `customer.id` dans Liquid avec le secret général du tenant, intégré dans le thème (voir l’avertissement sur la [Shopify](https://docs.thewalletcrew.io/connectors/fr/e-commerce/shopify.md#liquid-code-snippet-without-the-app) page) |
| [Salesforce Commerce Cloud](https://docs.thewalletcrew.io/connectors/fr/e-commerce/salesforce-commerce-cloud.md) | Cartridge avec un contrôleur et un fragment ISML                                  | Préférence du site de type Password                                                                                                                                                                                                                   |
| [Adobe Commerce (Magento)](https://docs.thewalletcrew.io/connectors/fr/e-commerce/adobe-commerce-magento.md)     | Module avec une mise en page, un bloc et un modèle PHTML                          | `app/etc/env.php` ou une variable d’environnement                                                                                                                                                                                                     |
| [PrestaShop](https://docs.thewalletcrew.io/connectors/fr/e-commerce/prestashop.md)                               | Surcharge de module ou de thème                                                   | Variable d’environnement ou configuration du module                                                                                                                                                                                                   |

Pour le scan en magasin avec Shopify POS, voir [Shopify POS](https://docs.thewalletcrew.io/connectors/fr/pos/shopify-pos.md).

### Plateformes e-commerce non listées

Voir [Intégrer un logiciel sans connecteur répertorié](https://docs.thewalletcrew.io/connectors/fr/connecteurs-de-cartes-wallet.md). Pour une boutique personnalisée, utilisez un [connecteur personnalisé](https://docs.thewalletcrew.io/connectors/fr/custom-connector.md): le scripting du tenant peut appeler l’API de la boutique et créer, récupérer ou mettre à jour des cartes.

## FAQ

<details>

<summary><strong>« Add to Wallet » est-il pertinent uniquement pour les billets ou cartes d’embarquement ?</strong></summary>

Non. Les cartes Wallet fonctionnent bien comme identifiants clients. Les exemples courants incluent les cartes de fidélité et d’adhésion, les cartes-cadeaux Wallet, les confirmations de retrait et les réservations de services.

</details>

<details>

<summary><strong>La même approche peut-elle être utilisée pour les cartes-cadeaux ?</strong></summary>

Oui. Le même schéma fonctionne lorsque la carte-cadeau est émise comme modèle de carte dans The Wallet Crew et qu’un identifiant stable de carte-cadeau existe dans la boutique (ou dans un système connecté). L’espace compte peut afficher un bouton pour chaque carte-cadeau en remplaçant `data-neostore-passType` et la clé ainsi que la valeur de l’identifiant externe par l’identifiant de carte-cadeau, puis en signant cet identifiant avec le HMAC côté serveur.

</details>

<details>

<summary><strong>Le bouton peut-il être affiché ailleurs que sur la page du compte ?</strong></summary>

Oui. Le même SDK peut être utilisé sur n’importe quelle page authentifiée où un identifiant stable est disponible côté serveur. Les exemples courants incluent une page de liste de cartes-cadeaux, un tableau de bord de fidélité ou une page pick & collect lorsqu’une carte de retrait est utilisée comme jeton de scan en magasin.

</details>

<details>

<summary><strong>Une carte peut-elle être mise à jour après son ajout ?</strong></summary>

Oui. Les données de la carte peuvent être mises à jour après l’installation. Les clients peuvent également recevoir une notification Wallet lorsqu’une mise à jour se produit, selon le comportement et la configuration de la plateforme.

</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/fr/e-commerce.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.
