Skip to content
Retour au blog

Guide d'intégration REST API pour pass Apple & Google Wallet

Créez des modèles de pass, émettez des cartes dynamiques et synchronisez les données via webhooks.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-162 min de lecture
Image de couverture pour Guide d'intégration REST API pour pass Apple & Google Wallet

L'intégration de cartes Wallet dans votre architecture logicielle permet d'automatiser l'émission, d'envoyer des notifications de mise à jour prises en charge par les plateformes et de piloter le cycle de vie des cartes depuis votre backend, CRM ou logiciel de caisse (POS).

Ce guide présente une vue technique complète de l'intégration des API REST Passinstance, des SDK officiels, de l'authentification, de l'idempotence et de la vérification des webhooks.


1. Architecture système et flux de données

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX ARCHITECTURE SYSTÈME
ÉTAPE 01 Votre application / Backend
ÉTAPE 02 Moteur API Passinstance
Compile le fichier .pkpass signé PKCS#7 pour Apple Wallet
Génère le lien de sauvegarde JWT signé pour Google Wallet
ÉTAPE 03 Appareil du client (iOS / Android)
ÉTAPE 04 Passerelle Webhooks Passinstance
4. POST/webhooks/pass-installedVotre Backend

2. Authentification et clés d'environnement

Passinstance prend en charge l'authentification par clé API (X-API-Key) pour les appels serveur à serveur (ainsi que les jetons de session Bearer JWT) via HTTPS/TLS. Les clés API sont générées dans le tableau de bord selon deux environnements :

  • pi_test_... — Environnement sandbox pour tester vos modèles, générer des cartes de test et déclencher vos webhooks.
  • pi_live_... — Environnement de production pour émettre des cartes signées sur Apple Wallet et Google Wallet.
BASH
curl -X GET https://api.passinstance.com/api/v1/templates \
  -H "X-API-Key: pi_live_99481203948123"

3. Créer et émettre des cartes par programmation

Utilisez le SDK officiel @passinstance/sdk (Node.js / TypeScript) ou des requêtes HTTP REST directes depuis votre backend :

TS
import { Passinstance } from "@passinstance/sdk";

const client = new Passinstance({
  apiKey: process.env.PASSINSTANCE_API_KEY!,
});

export async function handleCustomerSignup(user: { id: string; email: string; name: string }) {
  const pass = await client.passes.create({
    templateId: "tpl_membership_gold",
    externalId: user.id, // Idempotence et référence croisée en base
    data: {
      memberName: user.name,
      memberId: `MEM-${user.id.slice(0, 8)}`,
      joinDate: new Date().toISOString().split("T")[0],
      status: "Active",
    },
  });

  return {
    appleUrl: pass.appleWalletUrl,
    googleUrl: pass.googleWalletUrl,
    qrCodeImageUrl: pass.qrCodeUrl,
  };
}

4. Pousser des mises à jour sur l'écran verrouillé

Pour actualiser les données d'une carte (ajout de points, changement de palier ou modification de porte d'accès), envoyez une requête de mise à jour :

TS
await client.passes.update("pass_9842011", {
  data: {
    pointsBalance: 2500,
    tier: "Platinum",
  },
  pushNotification: {
    message: "Félicitations ! Vous passez au statut Platinum.",
  },
});

Cet appel unique déclenche simultanément une mise à jour APNs sur Apple Wallet et une actualisation REST sur Google Wallet.


5. Écouter les événements Webhook

Passinstance envoie des webhooks signés pour les principaux événements du cycle de vie afin de maintenir votre base de données synchronisée sans polling.

Types d'événements pris en charge :

  • pass.created — La charge utile de la carte a été générée.
  • pass.installed — L'utilisateur a ajouté la carte dans Apple Wallet ou Google Wallet.
  • pass.updated — Des champs de la carte ont été mis à jour.
  • pass.scanned — L'application scanner a validé le code-barres en caisse ou à l'entrée.
  • pass.removed — L'utilisateur a supprimé la carte de son portefeuille mobile.

Vérification de la signature Webhook :

TS
import { verifyWebhookSignature } from "@passinstance/sdk/crypto";

export async function handleWebhookRequest(req: Request) {
  const signature = req.headers.get("x-passinstance-signature")!;
  const payload = await req.text();

  const isValid = verifyWebhookSignature({
    payload,
    signature,
    secret: process.env.PASSINSTANCE_WEBHOOK_SECRET!,
  });

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(payload);
  if (event.type === "pass.installed") {
    console.log(`Carte ${event.data.passId} installée sur ${event.data.platform}`);
  }

  return new Response("OK", { status: 200 });
}

6. Architecture multi-tenant et domaines personnalisés

Pour les plateformes SaaS et agences intégrant l'émission de cartes dans leur produit :

  • Provisionnez des espaces clients isolés par tenant via l'API.
  • Configurez un domaine personnalisé CNAME (ex. wallet.votre-saas.com, option à 20 €/mois) pour vos liens de téléchargement.
  • Isolez les webhooks, certificats Apple et clés API pour chaque espace client.
Démo interactive en direct
Apple Wallet & Google Wallet

Testez une vraie carte Wallet sur votre téléphone

Découvrez le fonctionnement des cartes digitales en direct. Scannez avec votre téléphone ou appuyez ci-dessous pour ajouter ce pass dans Apple Wallet ou Google Wallet.

Artisan RoastersCafé & F&B
Test QR code for Artisan Roasters

Scannez avec l'appareil photo

Lié à ce sujet

API pour développeurs et intégrations

Centre de sujets ouvert

Prêt à lancer votre programme de carte de portefeuille ?

Créez votre compte, concevez votre modèle de carte et testez de vrais carte directement dans Apple Wallet et Google Wallet.