Skip to content
Retour au blog

Créer un pass Apple Wallet : Guide technique complet 2026

Certificats, payload PassKit, signatures de bundles .pkpass et web services de mise à jour.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-163 min de lecture
Image de couverture pour Créer un pass Apple Wallet : Guide technique complet 2026

La création de cartes natives Apple Wallet (fichiers .pkpass) permet aux entreprises de diffuser des cartes de fidélité, billets d'événement, cartes d'embarquement, coupons et cartes de membre directement sur l'iPhone et l'Apple Watch, sans obliger les utilisateurs à télécharger une application mobile dédiée.

Ce guide technique complet couvre l'architecture Apple PassKit, la signature cryptographique, la diffusion et les mises à jour push en temps réel.


1. Anatomie d'une carte Apple Wallet (.pkpass)

Une carte Apple Wallet est une archive ZIP compressée portant l'extension .pkpass, contenant un fichier JSON structuré, des images adaptées et des manifestes signés cryptographiquement reconnus par Apple.

Structure requise du bundle

BUNDLE TREE
my-pass.pkpass
├── pass.json           # Mise en page principale, définition des champs et métadonnées
├── logo.png            # Emblème de marque en haut à gauche (160x160 @2x)
├── logo@2x.png
├── icon.png            # Icône de notification écran verrouillé (58x58 @2x)
├── icon@2x.png
├── strip.png           # Image bannière pour billets et coupons (375x144 @2x)
├── strip@2x.png
├── manifest.json       # Empreintes SHA-1 de tous les fichiers de l'archive
└── signature           # Signature cryptographique PKCS#7 créée avec votre certificat Pass Type ID

2. Configuration Apple Developer et signature par certificat

Pour signer nativement des cartes Apple Wallet, Apple exige des identifiants de signature PKCS#12 issus d'un compte Apple Developer actif.

Étapes du pipeline de signature :

  1. 1
    Pass Type ID : Enregistrez un identifiant unique (ex. pass.com.votreentreprise.fidelite) dans l'Apple Developer Portal.
  2. 2
    Demande de signature de certificat (CSR) : Générez une clé privée RSA 2048 bits et un fichier CSR via OpenSSL ou Trousseau d'accès.
  3. 3
    Certificat Pass Type : Téléchargez votre certificat .cer émis et exportez-le au format .p12 avec sa clé privée.
  4. 4
    Certificat intermédiaire WWDR : Incluez le certificat intermédiaire Apple Worldwide Developer Relations G6 dans la chaîne de confiance.

[!NOTE]

Signature gérée en production : Pour signer des cartes Apple Wallet en production sous l'identité de votre marque, téléversez votre certificat Apple Developer Pass Type ID dans votre espace Passinstance. Passinstance automatise ensuite l'empaquetage .pkpass, la signature PKCS#7 et la chaîne intermédiaire WWDR.


3. Configurer les champs de pass.json

Le fichier pass.json définit le style de mise en page (storeCard, coupon, eventTicket, boardingPass, generic) et les champs dynamiques :

JSON
{
  "formatVersion": 1,
  "passTypeIdentifier": "pass.com.passinstance.loyalty",
  "serialNumber": "PASS-8842-2026",
  "teamIdentifier": "ABC123XYZ",
  "organizationName": "Artisan Coffee",
  "description": "Carte de fidélité Artisan Coffee",
  "logoText": "Artisan Coffee",
  "foregroundColor": "rgb(255, 255, 255)",
  "backgroundColor": "rgb(10, 90, 84)",
  "labelColor": "rgb(164, 243, 222)",
  "storeCard": {
    "primaryFields": [
      {
        "key": "stamps",
        "label": "PROGRESSION",
        "value": "8 sur 10 tampons"
      }
    ],
    "secondaryFields": [
      {
        "key": "holder",
        "label": "MEMBRE",
        "value": "Jane Doe"
      }
    ]
  },
  "barcodes": [
    {
      "format": "PKBarcodeFormatQR",
      "message": "PASS-LOYALTY-8842",
      "messageEncoding": "iso-8859-1"
    }
  ],
  "webServiceURL": "https://api.passinstance.com/v1/apple",
  "authenticationToken": "tok_exemple_99182348"
}

Éditeur Visuel Passinstance — Zones de mise en page et variables pass.json
Éditeur Visuel Passinstance — Zones de mise en page et variables pass.json

4. Coordonnées de localisation et déclencheurs natifs

Les cartes Apple Wallet prennent en charge jusqu'à 10 coordonnées géographiques (locations) permettant à iOS d'afficher passivement un rappel sur l'écran verrouillé lorsque le client s'approche de votre boutique ou lieu d'événement.

JSON
"locations": [
  {
    "latitude": 48.856614,
    "longitude": 2.3522219,
    "relevantText": "Bienvenue ! Présentez votre carte en caisse pour profiter de votre avantage."
  }
]

5. Pousser des mises à jour en temps réel (APNs)

Lorsque le solde, le palier ou la date d'expiration d'une carte évolue, Apple Wallet actualise la carte à distance via l'Apple Push Notification service (APNs) :

  1. 1
    À l'installation, iOS envoie une requête POST vers votre webServiceURL avec le jeton push de l'appareil (pushToken).
  2. 2
    Pour mettre à jour la carte, un signal push APNs vide est transmis vers les serveurs Apple pour cibler ce pushToken.
  3. 3
    iOS se réveille en arrière-plan, récupère le dernier pass.json auprès du serveur, met à jour la carte et affiche une bannière si un champ configuré avec changeMessage a changé.

6. Générer des cartes Apple Wallet facilement avec Passinstance

Plutôt que de maintenir vos propres pipelines de signature OpenSSL, vos serveurs APNs et vos endpoints d'enregistrement d'appareils, Passinstance automatise l'ensemble du flux :

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

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

// Émettre une carte Apple Wallet signée
const pass = await client.passes.create({
  templateId: "tpl_coffee_loyalty",
  data: {
    holderName: "Jane Doe",
    stamps: "8 of 10 Stamps",
  },
});

console.log("Lien Ajouter à Apple Wallet :", pass.appleWalletUrl);
Checklist de publication — Certificat de signature .pkpass, règles de validation et page de téléchargement
Checklist de publication — Certificat de signature .pkpass, règles de validation et page de téléchargement

Points clés à retenir

  • Aucune application requise : Les clients ajoutent leur carte en un geste depuis Safari, un QR code, un e-mail ou un lien hébergé.
  • Toujours à jour : Les modifications de solde se synchronisent sur iPhone et Apple Watch via APNs.
  • Pertinence géographique : Les coordonnées GPS affichent la carte sur l'écran verrouillé à l'approche de vos points de vente.
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.