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
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.
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 :
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 :
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 :
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.





