API Google Wallet

L’API Google Wallet vous permet de créer, mettre à jour, lister et gérer les cartes Google Wallet par programmation. Elle prend en charge les mêmes opérations que le générateur de cartes dans le Panneau de Contrôle.

Utilisez-la pour émettre des cartes de fidélité, des offres, des cartes-cadeaux, des billets d’événement, des cartes d’embarquement, des titres de transport et des cartes génériques, et pour envoyer des mises à jour en direct aux cartes déjà enregistrées sur les appareils de vos utilisateurs.

Prérequis : configuration de Google Wallet

Avant de pouvoir créer des cartes pour une application, un ID d’émetteur Google Wallet et une clé de compte de service doivent être configurés pour cette application dans le Panneau de Contrôle de Pushwoosh. Sans eux, les requêtes create et update échouent. Voir la configuration des cartes Google Wallet pour Android.

URL de base

https://apple-passkit.svc-nue.pushwoosh.com

Tous les points de terminaison sont servis via HTTPS. Les requêtes et les réponses utilisent application/json sauf indication contraire.

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’accès à l’API Pushwoosh :

Authorization: Token <api-token>

Le compte propriétaire du jeton doit être propriétaire de l’application référencée par applicationCode. Une requête pour une application appartenant à un autre compte renverra 403 Forbidden.

Conventions

• Nom des champs : Les champs JSON utilisent lowerCamelCase (par exemple, serialNumber, hexBackgroundColor, logoUrl).
• Champs non renseignés : les réponses incluent tous les champs, même lorsqu’ils sont vides ou nuls.
• Identité : le serialNumber est toujours attribué par le serveur lors de la création d’une carte. Toute valeur que vous envoyez lors de la création est ignorée. L’ID complet de l’objet Google Wallet est {issuerId}.{serialNumber}.
• Images : logoUrl et heroImageUrl sont des URL HTTPS publiques vers des images que Google récupère — ce ne sont pas des fichiers téléversés.
• Style de carte : un seul objet de style (generic, offer, loyalty, eventTicket, giftCard, flight ou transit) doit être défini sur une carte. Le style ne peut pas être modifié après la création.

Réponses d’erreur

Statut HTTP	Signification
400 Bad Request	Argument invalide — un champ obligatoire est manquant ou mal formé.
401 Unauthorized	En-tête Authorization manquant ou invalide.
403 Forbidden	L’application n’appartient pas au compte de l’appelant.
404 Not Found	La carte, le modèle ou l’application n’a pas été trouvé(e).
503 Service Unavailable	Le service est à pleine capacité ou temporairement indisponible.

Points de terminaison

Méthode	Chemin	Description
POST	/api/google/pass/validate	Valider une configuration de carte
POST	/api/google/pass/create	Créer un nouvel objet de carte et obtenir un lien de sauvegarde
POST	/api/google/pass/update/{serialNumber}	Mettre à jour une carte existante ; Google livre la modification
GET	/api/google/pass/{applicationCode}/{serialNumber}/save-link	Obtenir un lien de sauvegarde « Ajouter à Google Wallet »
GET	/api/google/pass/{applicationCode}/{serialNumber}	Obtenir une seule carte
GET	/api/google/passes	Lister toutes les cartes pour une application
POST	/api/google/pass/{applicationCode}/{serialNumber}/state	Activer ou invalider une carte
DELETE	/api/google/pass/{applicationCode}/{serialNumber}	Supprimer une carte
GET	/api/google/config	Obtenir la configuration Google Wallet de l’application
GET	/api/google/templates	Lister les modèles de cartes disponibles
GET	/api/google/templates/{filename}	Obtenir un seul modèle

Créer une carte

Crée la classe et l’objet de la carte dans Google Wallet, puis renvoie le numéro de série attribué par le serveur, l’ID complet de l’objet et un lien de sauvegarde « Ajouter à Google Wallet ».

POST /api/google/pass/create

Corps de la requête

Paramètre	Type	Requis	Description
pass	objet	Oui	L’objet de carte décrivant la carte. Un seul style doit être défini.
userId	chaîne	Oui	L’ID utilisateur Pushwoosh auquel la carte est émise.
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.

Exemple de requête

{
  "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"
    }
  }
}

Réponse

Champ	Type	Description
serialNumber	chaîne	Identité unique de la carte créée, attribuée par le serveur.
objectId	chaîne	ID complet de l’objet Google Wallet : {issuerId}.{serialNumber}.
saveLink	chaîne	Lien « Ajouter à Google Wallet » : https://pay.google.com/gp/v/save/{jwt}.
message	chaîne	Message de résultat.

Exemple de réponse

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

Valider une carte

Vérifie une configuration de carte par rapport aux exigences de Google sans la créer. Utile avant d’appeler la création.

POST /api/google/pass/validate

Corps de la requête

Paramètre	Type	Requis	Description
pass	objet	Oui	L’objet de carte à valider.

Réponse

Champ	Type	Description
valid	booléen	Indique si la carte passe la validation.
errors	tableau de chaînes	Problèmes bloquants qui doivent être corrigés.
warnings	tableau de chaînes	Avertissements non bloquants.

Mettre à jour une carte

Met à jour l’objet de la carte avec un nouveau contenu. Google livre ensuite la version mise à jour à chaque appareil qui a enregistré la carte. Envoie éventuellement une notification Android avec la mise à jour.

POST /api/google/pass/update/{serialNumber}

Paramètres de chemin

Paramètre	Type	Description
serialNumber	chaîne	Le numéro de série renvoyé lors de la création de la carte.

Corps de la requête

Paramètre	Type	Requis	Description
updates	objet	Oui	L’objet de carte avec le nouveau contenu. Le style ne peut pas être modifié.
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.
notifyMessage	chaîne	Non	Si non vide, envoie une notification push Android avec ce texte à tous ceux qui ont enregistré la carte. Vide signifie une mise à jour silencieuse.
notifyOnUpdate	booléen	Non	Demande une notification de mise à jour de champ. Seules les cartes loyalty, eventTicket et flight notifient réellement ; les autres styles acceptent l’indicateur mais n’en envoient jamais. Les notifications ne se déclenchent que dans les 3 heures précédant une heure de début pertinente, et Google les limite à 3 notifications par carte par 24 heures.

Deux façons de notifier lors d'une mise à jour

notifyMessage envoie une notification Android personnalisée à tous ceux qui ont enregistré la carte et fonctionne pour n’importe quel style de carte. notifyOnUpdate demande à Google d’envoyer sa propre notification de mise à jour de champ, qui ne se déclenche que pour les cartes loyalty, eventTicket et flight.

Réponse

Champ	Type	Description
success	booléen	Indique si la mise à jour a réussi.
message	chaîne	Message de résultat.

Obtenir un lien de sauvegarde

Renvoie un lien de sauvegarde « Ajouter à Google Wallet » pour une carte déjà créée. L’objet de la carte doit déjà exister (créé via Créer une carte).

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

Réponse

Champ	Type	Description
saveLink	chaîne	https://pay.google.com/gp/v/save/{jwt}.

Partagez le lien ou affichez-le sous forme de code QR

Placez le saveLink derrière un bouton « Ajouter à Google Wallet », ou affichez-le sous forme de code QR avec n’importe quelle bibliothèque QR. Lorsqu’un utilisateur l’ouvre, Google l’invite à enregistrer la carte et enregistre son appareil pour les mises à jour.

Obtenir une carte

Renvoie une seule carte stockée, y compris son objet de carte complet.

GET /api/google/pass/{applicationCode}/{serialNumber}

Réponse

Renvoie { "pass": { ... } }, un seul enregistrement de carte.

Lister les cartes

Renvoie une liste paginée et triée des cartes stockées pour une application.

GET /api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

Paramètres de requête

Paramètre	Type	Requis	Description
applicationCode	chaîne	Oui	Le code d’application Pushwoosh.
orderBy	chaîne	Non	Champ de tri : UPDATED (par défaut) ou CREATED.
orderDirection	chaîne	Non	Direction du tri : DESC (par défaut, les plus récents en premier) ou ASC.
page	entier	Non	Index de page basé sur zéro. Par défaut à 0.
perPage	entier	Non	Taille de la page. 0 ou omis utilise la valeur par défaut du serveur.

Réponse

Champ	Type	Description
passes	tableau d’objets	La page actuelle des enregistrements de carte.
page	entier	L’index de la page renvoyée.
perPage	entier	La taille de page utilisée pour cette réponse.
total	entier	Nombre total de cartes pour l’application sur toutes les pages.

Définir l’état de la carte

Active ou invalide une carte. Une carte invalidée (inactive) est déplacée vers la section Cartes expirées de l’utilisateur dans Google Wallet ; l’enregistrement est conservé pour pouvoir être réactivé.

POST /api/google/pass/{applicationCode}/{serialNumber}/state

Corps de la requête

Paramètre	Type	Requis	Description
active	booléen	Oui	true définit la carte à ACTIVE ; false l’invalide (INACTIVE).

Réponse

Renvoie un objet vide {} en cas de succès.

Supprimer une carte

Invalide la carte dans Google et supprime son enregistrement stocké dans Pushwoosh.

DELETE /api/google/pass/{applicationCode}/{serialNumber}

Une carte enregistrée ne peut pas être supprimée de force

Google ne permet pas de supprimer une carte déjà enregistrée sur l’appareil d’un utilisateur. La suppression invalide la carte (elle est déplacée vers les Cartes expirées) et supprime l’enregistrement Pushwoosh.

Réponse

Renvoie un objet vide {} en cas de succès.

Obtenir la configuration

Renvoie l’état de la configuration Google Wallet pour une application.

GET /api/google/config?applicationCode=XXXXX-XXXXX

Réponse

Champ	Type	Description
hasServiceAccount	booléen	Indique si une clé de compte de service est configurée.
issuerId	chaîne	L’ID d’émetteur de la Google Pay & Wallet Console configuré.
serviceAccountEmail	chaîne	Le client_email du compte de service configuré.

Modèles

Listez les modèles de cartes d’exemple disponibles, ou récupérez-en un en tant qu’objet de carte que vous pouvez utiliser comme point de départ.

GET /api/google/templates — renvoie { "templates": [ { "filename", "name", "description", "style" } ] }.

GET /api/google/templates/{filename} — renvoie { "template": { ...objet de carte... } }.

Référence d’objet

Objet de carte (Pass object)

Champ	Type	Description
serialNumber	chaîne	Attribué par le serveur lors de la création ; identifie la carte.
generic / offer / loyalty / eventTicket / giftCard / flight / transit	objet	Le style de la carte. Un seul doit être défini. Voir les objets de style ci-dessous.
hexBackgroundColor	chaîne	Couleur de fond de la carte, #rrggbb.
logoUrl	chaîne	URL HTTPS publique de l’image du logo. Requis pour les cartes de fidélité et de transport.
heroImageUrl	chaîne	URL HTTPS publique d’une image de bannière large.
barcode	objet	Code-barres affiché sur la carte.
textModules	tableau	Modules de texte affichés dans la vue détaillée.
links	tableau	Modules de lien affichés dans la vue détaillée.
expirationTime	chaîne	Heure ISO 8601 à laquelle Google fait expirer automatiquement la carte. Vide signifie pas d’expiration.
appLink	objet	Lien d’application : un bouton CTA sur le recto de la carte.
locations	tableau	Emplacements qui déclenchent une notification géolocalisée (max 10).
holdersPolicy	chaîne	Qui peut enregistrer la carte : ONE_USER_ALL_DEVICES (par défaut), ONE_USER_ONE_DEVICE, ou MULTIPLE_HOLDERS.

Objet générique (Generic object)

Champ	Type	Description
cardTitle	chaîne	Requis. Le nom de l’émetteur/programme en haut de la carte.
header	chaîne	Requis. Le titre principal de la carte.
subheader	chaîne	Titre secondaire.
cardFields	tableau	Jusqu’à 6 modules de texte épinglés au recto (jusqu’à 3 rangées de 2).

Objet d’offre (Offer object)

Champ	Type	Description
title	chaîne	Requis. Par exemple, 20% de réduction sur tout.
provider	chaîne	Requis. Le nom du marchand.
details	chaîne	Détails de l’offre.
finePrint	chaîne	Termes et conditions.
redemptionChannel	chaîne	ONLINE, INSTORE, BOTH (par défaut), ou TEMPORARY_PRICE_REDUCTION.
issuerName	chaîne	Affiché sur les surfaces « émis par » de Google ; par défaut à provider.

Objet de fidélité (Loyalty object)

Champ	Type	Description
programName	chaîne	Requis. Nécessite logoUrl sur la carte.
accountName	chaîne	Nom du membre affiché sur la carte.
accountId	chaîne	ID du membre affiché sur la carte.
pointsLabel	chaîne	Par exemple, Points. Affiché uniquement avec un solde.
pointsBalance	chaîne	Le solde de points.
rewardsTier	chaîne	Par exemple, Or.
rewardsTierLabel	chaîne	Étiquette à côté du niveau ; par défaut à Niveau.
issuerName	chaîne	Par défaut à programName.

Objet de billet d’événement (Event ticket object)

Champ	Type	Description
eventName	chaîne	Requis.
venueName / venueAddress	chaîne	Détails du lieu.
startDateTime / endDateTime	chaîne	ISO 8601 avec décalage (par exemple, 2026-07-01T19:30:00+02:00).
ticketHolderName / ticketNumber / ticketType	chaîne	Détails du détenteur et du billet.
section / row / seat / gate	chaîne	Détails des places.
issuerName	chaîne	Par défaut à eventName.

Objet de carte-cadeau (Gift card object)

Champ	Type	Description
merchantName	chaîne	Requis.
cardNumber	chaîne	Requis.
pin	chaîne	PIN de la carte.
balance	chaîne	Montant décimal, par exemple 25.00. Nécessite balanceCurrency.
balanceCurrency	chaîne	Code de devise ISO 4217, par exemple USD.
issuerName	chaîne	Par défaut à merchantName.

Objet de vol (Flight object)

Champ	Type	Description
carrierIataCode	chaîne	Requis. Code IATA à 2 lettres, par exemple LX.
airlineName	chaîne	Nom d’affichage de la compagnie aérienne.
flightNumber	chaîne	Requis. Chiffres uniquement, par exemple 113.
originAirportCode / destinationAirportCode	chaîne	Requis. Codes IATA à 3 lettres.
originTerminal / originGate / destinationTerminal	chaîne	Détails du terminal et de la porte d’embarquement.
departureDateTime	chaîne	Requis. Heure locale de l’aéroport d’origine, ISO 8601 sans décalage (par exemple, 2026-09-01T06:30:00).
boardingTime / arrivalDateTime	chaîne	Même format local. arrivalDateTime est l’heure locale de destination.
passengerName	chaîne	Requis.
confirmationCode / seatNumber / seatClass / boardingGroup	chaîne	Détails du passager.
issuerName	chaîne	Par défaut à airlineName, puis au code du transporteur.

Objet de transport (Transit object)

Champ	Type	Description
transitType	chaîne	Requis. BUS, RAIL, TRAM, FERRY, ou OTHER.
transitOperatorName	chaîne	Requis. Nécessite logoUrl sur la carte.
passengerName	chaîne	Requis.
ticketNumber	chaîne	Numéro de billet.
tripType	chaîne	ONE_WAY (par défaut) ou ROUND_TRIP.
legs	tableau	Un ou plusieurs tronçons de transport dans l’ordre du voyage.
issuerName	chaîne	Par défaut à transitOperatorName.

Objet de tronçon de transport (Transit leg object)

Champ	Type	Description
originName / destinationName	chaîne	Requis.
departureDateTime / arrivalDateTime	chaîne	ISO 8601 ; décalage optionnel (heure locale si omis).
platform / coach / seat	chaîne	Détails de l’embarquement.
fareName	chaîne	Par exemple, Aller simple Anytime.

Objet de code-barres (Barcode object)

Champ	Type	Description
format	chaîne	QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, et autres types de codes-barres de Google Wallet.
value	chaîne	Données encodées dans le code-barres.
altText	chaîne	Texte affiché sous le code-barres.

Objet de module de texte (Text module object)

Champ	Type	Description
id	chaîne	Identifiant du module.
header	chaîne	Titre du module.
body	chaîne	Texte du module.

Objet de module de lien (Link module object)

Champ	Type	Description
uri	chaîne	URL du lien externe.
description	chaîne	Étiquette du lien affichée dans la vue détaillée.

Objet de lien d’application (App link object)

Champ	Type	Description
uri	chaîne	URL web ou URI cible de lien profond.
androidPackageName	chaîne	Optionnel. Si défini, ouvre l’application Android.
description	chaîne	Description interne de l’URI cible (pas une étiquette de bouton visible) ; par défaut à l’URI.

Objet d’emplacement (Location object)

Champ	Type	Description
latitude	nombre	-90.0 à +90.0.
longitude	nombre	-180.0 à +180.0.

Objet d’enregistrement de carte (Pass record object)

Renvoyé par les points de terminaison de liste/obtention.

Champ	Type	Description
serialNumber	chaîne	Numéro de série de la carte.
objectId	chaîne	ID complet de l’objet Google Wallet {issuerId}.{serialNumber}.
cardTitle	chaîne	Titre/en-tête d’affichage de la carte.
header	chaîne	Titre d’affichage secondaire.
userId	chaîne	ID utilisateur Pushwoosh auquel la carte a été émise.
createdAt / updatedAt	chaîne	Horodatages de création et de dernière mise à jour.
state	chaîne	ACTIVE ou INACTIVE.
style	chaîne	generic, offer, loyalty, eventTicket, giftCard, flight, ou transit.
pass	objet	L’objet de carte complet, pour l’édition.