Skip to content
Guide du centre d'aide · Intégrations Wallet
3 min de lectureVérifié 2026-11-16

Google Wallet

Provisionnement des classes et objets Generic, Loyalty, Offer, Gift Card et Event via liens JWT signés.

Dans ce guide

Aperçu : architecture en deux niveaux Classes & Objets

Contrairement à l'archive binaire .pkpass téléchargée localement par Apple Wallet, Google Wallet repose sur un modèle de données cloud en deux niveaux géré via l'API REST Google Wallet (walletobjects/v1) :

  1. 1
    Wallet Class (couche Modèle) : Définit l'identité visuelle partagée, les métadonnées de l'émetteur, le logo du programme, la mise en page et les URLs de rappel pour tous les titulaires d'un même modèle (LoyaltyClass, EventTicketClass, OfferClass, GiftCardClass, GenericClass).
  2. 2
    Wallet Object (couche Instance de passe) : Représente la carte individuelle d'un client rattachée à sa classe parente classId (LoyaltyObject, EventTicketObject, OfferObject, GiftCardObject, GenericObject), contenant le code-barres unique, le solde de points, le palier et la charge utile Smart Tap.
FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
CLASSES/OBJETS GOOGLE WALLET & PIPELINE JWT SAVE
ÉTAPE 01 PHASE 1 : PUBLICATION DU MODÈLEPROVISIONNEMENT DE CLASSE
Publication du modèle Passinstance (POST/api/v1/templates/:id/publish)
Google Wallet Sync crée/actualise <issuerId>.<templateClassId> via REST (LoyaltyClass | EventTicketClass | OfferClass | GiftCardClass)
ÉTAPE 02 PHASE 2 : ÉMISSION DU PASSE & SIGNATURE DU JWT SAVE RS256
1
Provisionner ou embarquer <issuerId>.<passObjectId> (LoyaltyObject, etc.)
2
Signer les claims JWT (iss, aud: "google", typ: "savetowallet", payload) avec la clé privée RSA du compte de service Google Cloud (RS256)
3
Retourner le lien d'ajout : https://pay.google.com/gp/v/save/<signed_jwt>
Ajout / Suppression client
ÉTAPE 03A Google Cloud appelle le webhook
Passinstance :POST/api/v1/wallet/callback
Événement : eventType: "save" | "del"
Mutation côté serveur
ÉTAPE 03B Passinstance exécute REST PATCH
sur walletobjects/v1/...Object
Google Play Services synchronise instantanément la carte Android

Correspondance des programmes Passinstance avec les Classes & Objets Google Wallet

Les adaptateurs factory de Passinstance associent automatiquement la configuration de votre modèle à la paire de ressources Google Wallet adaptée :

Programme PassinstanceRessource Google ClassRessource Google ObjectPrincipaux champs spécialisés
Cartes de fidélité & tamponsLoyaltyClassLoyaltyObjectloyaltyPoints, secondaryLoyaltyPoints, accountId, accountName, rewardsTier
Coupons & bons de réductionOfferClassOfferObjectredemptionChannel, provider, validTimeInterval, barcode
Cartes cadeaux & prépayéesGiftCardClassGiftCardObjectcardNumber, pin, balance (micros + currencyCode), balanceUpdateTime
Billets d'événementsEventTicketClassEventTicketObjectseatInfo (seat, row, section, gate), ticketHolderName, eventName, doorsOpen
Cartes de membre & badgesGenericClassGenericObjectcardTitle, subheader, header, textModulesData, imageModulesData

Important : Même si un client se connecte à son compte Google sur plusieurs smartphones ou tablettes Android, Google Wallet associe la carte à un identifiant canonique unique <issuerId>.<objectId>. Passinstance déduplique au niveau de l'Objet et ne comptabilise cela que comme 1 passe actif Google Wallet.

Liens JWT signés d'ajout & webhooks de rappel

1. Jeton JWT Save to Google Wallet signé en RS256

Lorsqu'un client ouvre un lien intelligent depuis Android, Passinstance construit et signe un JSON Web Token avec la clé privée du compte de service Google Cloud et le redirige vers https://pay.google.com/gp/v/save/<jwt> :

JSON
{
  "iss": "wallet-signer@passinstance-prod.iam.gserviceaccount.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1763218800,
  "origins": ["https://app.passinstance.com"],
  "payload": {
    "loyaltyObjects": [
      {
        "id": "3388000000022194812.pass_c41a8d20",
        "classId": "3388000000022194812.cls_7b9e4c12",
        "state": "ACTIVE",
        "accountId": "CUST-88412",
        "accountName": "Alex Rivera",
        "loyaltyPoints": {
          "label": "Points",
          "balance": { "int": 1450 }
        },
        "barcode": {
          "type": "QR_CODE",
          "value": "PI-8849-2026-X9",
          "alternateText": "PI-8849-2026-X9"
        }
      }
    ]
  }
}

2. Webhook d'installation & de suppression Google Wallet (POST /api/v1/wallet/callback)

Chaque Google Wallet Class provisionnée par Passinstance définit callbackOptions.url sur POST /api/v1/wallet/callback. Dès qu'un utilisateur Android enregistre ou retire la carte de Google Wallet, Google transmet un événement signé :

JSON
POST /api/v1/wallet/callback
{
  "classId": "3388000000022194812.cls_7b9e4c12",
  "objectId": "3388000000022194812.pass_c41a8d20",
  "eventType": "save",
  "expTimeMillis": 1763219100000,
  "nonce": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
}
  • eventType: "save" : Enregistre l'installation active Google Wallet, incrémente installedDevices et déclenche le webhook ou automatisme PASS_INSTALLED.
  • eventType: "del" : Marque l'objet Google Wallet comme désinstallé et décrémente les compteurs de passes actifs.

Surcharges spécifiques à Android en direct

Comme Google Wallet affiche les cartes dans une vue verticale déroulante (header, cardTitle et lignes à deux colonnes textModulesData) plutôt que sur une carte recto-verso fixe comme Apple Wallet, vous pouvez définir des Android Overrides dans l'inspecteur de l'éditeur visuel pour chaque champ ou image (googlePayLogo, androidBackground, androidLogo).

Approfondissez ces réglages sur Plateforme Google Wallet, Configuration Google Wallet et Google Smart Tap.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.