Comment émettre des wallet passes personnalisés via API

Une API wallet pass permet à votre backend de créer une carte pour chaque client, avec son nom, son solde, son code-barres et ses lieux, puis de la mettre à jour dès que vos données changent. Vous concevez un modèle une seule fois, vous envoyez les valeurs personnelles de chaque utilisateur, et vous récupérez un lien d’installation pour Apple Wallet ou un lien d’enregistrement (save link) pour Google Wallet.

Toutes les équipes n’en ont pas besoin. Les exemples s’appuient sur l’API Wallet passes de Pushwoosh, où chaque carte est rattachée à un User ID qui pilote aussi vos push, vos e-mails et vos parcours client. Ces valeurs personnelles sont des données clients : elles sont traitées sur une plateforme conforme au RGPD, certifiée ISO 27001:2022 et SOC 2 Type 2, avec des centres de données en UE et aux États-Unis.

Quand l’API l’emporte sur l’éditeur

L’éditeur est le bon outil pour concevoir une carte et pour des envois ponctuels ou de faible volume. L’API prend le relais quand les cartes dépendent de données qui vivent dans vos propres systèmes.

Regardez la colonne parcours avant d’écrire la moindre ligne de code. Si le déclencheur est une action client que Pushwoosh suit déjà, l’étape Issue Wallet Pass (émettre un wallet pass) dans Customer Journey rend souvent le code spécifique inutile.

Modèles et valeurs personnelles

Le principe est le même sur les 2 plateformes. Un modèle contient la mise en page, l’habillage de marque et la structure des champs. Les valeurs propres à chaque utilisateur le remplissent au moment de l’émission.

Les valeurs personnelles sont ce qui change d’1 client à l’autre : nom, numéro de membre, points, niveau, valeur du code-barres, date d’expiration, magasin le plus proche. Tout le reste vient du modèle : une modification du design s’applique donc à chaque nouvelle carte sans toucher à votre intégration. Pour un e-commerçant sur Shopify, WooCommerce ou PrestaShop, ces valeurs viennent naturellement du profil client et de l’historique de commandes.

Dans un parcours, l’étape Issue Wallet Pass reçoit les campagnes de cartes Apple et Google (apple_campaign_id, google_campaign_id) et les personal_values à renseigner. 1 seule étape peut émettre les 2 versions pour le même User ID, ce qui compte sur un marché français où iOS et Android sont à peu près à parité.

Le flux Apple Wallet

Tout ce que fait l’éditeur de cartes Apple est également disponible dans l’Apple Wallet PassKit API : créer, mettre à jour, lister, télécharger et supprimer des cartes.

Une intégration type compte 4 étapes.

Il vous faut un certificat Pass Type ID (.p12) par application et un compte Apple Developer (99 $ par an). La configuration est décrite dans la documentation de configuration des Wallet passes iOS.

Le flux Google Wallet

La Google Wallet API couvre le même cycle de vie pour les cartes Google.

Il vous faut un Issuer ID issu de la Google Pay & Wallet Console, avec le compte de service Pushwoosh invité sur votre émetteur, configuré une fois par application. La configuration est décrite dans la documentation de configuration Google Wallet.

Mettre à jour à grande échelle

C’est sur les mises à jour que l’API prouve sa valeur. Un registre de points ou un système de réservation peut mettre à jour une carte dès qu’une valeur change, de sorte que la carte dans le wallet du client correspond à votre source de vérité. Pendant le Black Friday ou les Soldes, quand les achats s’enchaînent, c’est ce qui garde les soldes de points exacts.

3 règles sécurisent les grandes séries de mises à jour :

• Partez de la carte actuelle. La mise à jour Apple attend l’objet complet de la carte : récupérez-la et ne modifiez que les valeurs qui ont bougé. La mise à jour Google, elle, applique un correctif partiel à l’objet.
• Décidez des alertes champ par champ. Chez Apple, seuls les champs dotés d’un message de changement affichent une alerte sur l’écran verrouillé. Chez Google, notifyOnUpdate demande à Google sa propre alerte, qui ne part que pour les cartes de fidélité, les billets d’événement et les cartes d’embarquement, avec 3 alertes maximum par carte sur 24 heures. notifyMessage envoie votre propre texte de notification Android, quel que soit le type de carte.
• Gardez des alertes liées à la carte. Apple et Google autorisent les notifications concernant la carte, pas les promotions.

Exemples de code

Les 2 API utilisent l’URL de base https://apple-passkit.svc-nue.pushwoosh.com et votre jeton d’accès à l’API Pushwoosh dans un en-tête Authorization: Token <api-token>. Les corps de requête ci-dessous sont les exemples de la référence de l’API.

Créer une carte Apple Wallet : POST /api/pass/create. La réponse renvoie le serialNumber de la carte.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Créer une carte Google Wallet : POST /api/google/pass/create. La réponse renvoie le serialNumber et un saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Pour mettre à jour, envoyez le nouveau contenu avec le numéro de série : POST /api/pass/update/{serialNumber} pour Apple, POST /api/google/pass/update/{serialNumber} pour Google.

Éditeur, API ou parcours : la règle simple

Utilisez l’éditeur pour concevoir et tester. Utilisez l’étape de parcours quand le déclencheur est un événement client déjà présent dans Pushwoosh, comme une inscription ou un premier achat. Utilisez l’API quand le déclencheur ou les données vivent dans votre backend, par exemple le système central d’une FinTech qui calcule un statut ou un plafond.

La plupart des équipes finissent par utiliser les 3, et c’est très bien : l’éditeur pour le design, les parcours pour les moments du cycle de vie, l’API pour les soldes et les statuts en temps réel. L’erreur consiste à forcer l’un d’entre eux à faire le travail des autres.

Personnaliser chaque carte à grande échelle avec Pushwoosh

Pushwoosh vous offre un éditeur visuel, une étape de parcours et une API pour des cartes Apple et Google Wallet natives, sans fournisseur de cartes intermédiaire. Chaque carte partage un User ID avec vos push, messages in-app, e-mails et SMS : 1 seul jeu de données pilote tous les canaux.

Personnaliser à grande échelle n’est pas une question de multiplier les modèles. C’est 1 seule source de vérité, reflétée par chaque carte dans chaque wallet.

FAQ