Renouveler un certificat Apple Pay avec Stripe (avancé)

Article avancé. Cette page détaille le fonctionnement, les précautions et le dépannage du renouvellement. Pour effectuer l'opération, commencez par la version simplifiée dans le guide Stripe ; revenez ici en cas de doute ou de problème.

Le certificat Apple Pay Payment Processing qui permet à Stripe de traiter les paiements Apple Pay de votre application iOS est valable 25 mois. Il doit être renouvelé avant son expiration, sans quoi les paiements Apple Pay échouent pour le Merchant ID concerné.

Apple envoie des rappels aux rôles Account Holder et Admin du compte Apple Developer 30, 15 et 7 jours avant l'expiration.

Aucune nouvelle version de l'application n'est nécessaire. Tant que le Merchant ID déclaré dans l'application reste le même, seul le certificat change. Stripe l'indique explicitement : « You don't need to update your app after you've replaced the certificate. » (Stripe — Apple Pay Certificate Renewal)

Cette procédure a été appliquée avec succès sur une application Chargekeeper en marque blanche publiée sur l'App Store : aucune nouvelle version publiée, aucune interruption d'Apple Pay. Les libellés ci-dessous sont ceux des interfaces Stripe et Apple Developer en français, avec l'équivalent anglais entre parenthèses.

Principe de la rotation

Deux éléments distincts sont en jeu :

Le certificat est rattaché au Merchant ID, pas à l'application. On peut donc le remplacer sans toucher à l'application.

Dans les applications Chargekeeper, Stripe est la passerelle de paiement d'Apple Pay comme de Google Pay. C'est Stripe qui déchiffre les paiements Apple Pay : il doit donc détenir la clé privée qui correspond au nouveau certificat. C'est pour cela que la demande de signature de certificat (CSR) est générée par Stripe et non sur votre Mac : Stripe garde la clé privée, et Apple ne reçoit que la clé publique.

Google Pay n'utilise pas ce certificat. Il n'est pas concerné par l'opération.

Déroulé de la procédure :

L'ordre des étapes 5 et 6 est déterminant : le certificat doit être importé dans Stripe avant d'être activé chez Apple.

Prérequis

• Un accès au compte Apple Developer de l'application, avec les droits sur Certificats, identifiants et profils (rôle Account Holder ou Admin).
• Un accès au compte Stripe qui traite les paiements de l'application, en mode production.
• Le Merchant ID utilisé par l'application en production.
• Un iPhone avec une carte réelle enregistrée dans Wallet et l'application installée depuis l'App Store, pour le test final.
• Du temps : Apple recommande de renouveler au moins 30 jours avant l'expiration. L'opération elle-même prend moins d'une heure.

1. Vérifier le Merchant ID de production

Avant toute action, confirmez le Merchant ID que l'application publiée utilise réellement.

Dans Xcode : ouvrez le projet, sélectionnez la cible de l'application, puis Signing & Capabilities → Apple Pay. Le Merchant ID coché est celui de l'application.

Dans le fichier d'entitlements (par exemple ios/Runner/Runner.entitlements pour une application Flutter), le Merchant ID figure sous la clé com.apple.developer.in-app-payments :

<key>com.apple.developer.in-app-payments</key>
<array>
    <string>merchant.com.exemple.app</string>
</array>

Une même application a souvent un Merchant ID différent par environnement (développement, recette, production), donc plusieurs fichiers d'entitlements. Prenez celui de la configuration de production.

Un nom historique ne signifie pas un prestataire actif. Un Merchant ID qui contient le nom d'un ancien prestataire de paiement peut tout à fait être utilisé aujourd'hui par Stripe. Le nom d'un Merchant ID n'a aucun effet technique. Ne créez pas de nouveau Merchant ID pour cette seule raison : cela obligerait à publier une nouvelle version de l'application.

2. Identifier le compte Stripe et le certificat actuel

Le nouveau certificat doit être importé dans le compte Stripe dont l'application utilise la clé publique. C'est le seul compte qui détient la clé privée du certificat actuel.

1. Dans Stripe, en mode production, ouvrez Paramètres → Moyens de paiement → Apple Pay (accès direct).
2. Dans la section Certificats iOS, repérez la ligne du Merchant ID et notez sa date d'expiration.

3. Dans Apple Developer, ouvrez Certificats, identifiants et profils → Identifiants, filtrez sur les Merchant IDs et ouvrez le vôtre. Le certificat actif doit avoir la même date d'expiration.

Si les dates concordent, vous êtes sur le bon compte Stripe. Si la ligne est absente ou si les dates diffèrent, arrêtez-vous : l'application utilise probablement un autre compte Stripe.

Dans le portail Apple en français, le nom du certificat peut s'afficher avec le préfixe marchand. au lieu de merchant. : il s'agit bien du même Merchant ID.

Un Merchant ID, un seul compte Stripe. Un Merchant ID n'a qu'un seul certificat de traitement actif, et chaque CSR appartient à un seul compte Stripe. Si plusieurs comptes Stripe reçoivent des paiements Apple Pay avec le même Merchant ID, un seul pourra les déchiffrer après la rotation.

Ne révoquez rien. Révoquer le certificat actif (Révoquer / Revoke) fait échouer immédiatement les paiements Apple Pay.

3. Télécharger un nouveau CSR depuis Stripe

1. Dans Paramètres → Moyens de paiement → Apple Pay, section Certificats iOS, cliquez sur + Ajouter une nouvelle application (Add new application).
2. Dans la fenêtre Ajouter un nouveau certificat, cliquez sur Télécharger la demande de signature de certificat : vous obtenez le fichier stripe.certSigningRequest.

3. Cliquez sur Continuer : Stripe résume les manipulations à faire chez Apple. Laissez cette fenêtre ouverte et ouvrez le lien vers le Centre Développeur d'Apple dans un nouvel onglet.

Attention : utilisez uniquement le CSR que Stripe vient de vous fournir.

• Ne générez pas de CSR vous-même avec le Trousseau d'accès, OpenSSL ou un autre outil. Stripe ne détiendrait pas la clé privée correspondante et ne pourrait pas déchiffrer les paiements.
• Ne réutilisez pas un ancien CSR téléchargé depuis Stripe. Stripe exige un nouveau CSR à chaque renouvellement, et un CSR ne sert qu'à émettre un seul certificat.

4. Créer le nouveau certificat chez Apple, sans l'activer

Dans Certificats, identifiants et profils :

1. Vérifiez en haut à droite que l'équipe sélectionnée est bien celle de l'application.
2. Cliquez sur Identifiants, filtrez sur les Merchant IDs, puis ouvrez le même Merchant ID qu'à l'étape 2.
   Si un bandeau vous demande d'accepter un accord, suivez les instructions avant de continuer.
3. Dans la section Certificat de traitement des paiements Apple Pay (Apple Pay Payment Processing Certificate), cliquez sur Créer un certificat (Create Certificate).
4. Sélectionnez le fichier stripe.certSigningRequest, puis cliquez sur Continuer.
5. Cliquez sur Télécharger (Download) : vous obtenez le fichier apple_pay.cer.

La page du nouveau certificat propose alors trois boutons : Activer, Révoquer et Télécharger. Sa date d'expiration est déjà affichée : elle est calculée dès la création et ne change pas à l'activation.

Ne cliquez pas encore sur Activer. Tant qu'il n'est pas activé, le nouveau certificat n'est pas utilisé et l'ancien reste en service.

N'installez pas le certificat dans le Trousseau d'accès. Le portail Apple suggère de double-cliquer sur le fichier .cer pour l'installer sur votre Mac. Cette consigne ne s'applique pas ici : la clé privée est chez Stripe, et le fichier .cer doit seulement être importé dans Stripe.

Au cours de cette étape :

• ne créez pas de nouveau Merchant ID ;
• ne modifiez pas les capabilities de l'App ID ;
• ne modifiez pas les entitlements de l'application.

5. Importer le certificat dans Stripe

1. Revenez à la fenêtre Ajouter un nouveau certificat restée ouverte dans Stripe et cliquez sur Continuer.
2. Cliquez sur Charger un certificat, sélectionnez le fichier apple_pay.cer, puis cliquez sur Soumettre.

3. Rechargez la page Apple Pay.

Dans Certificats iOS, le Merchant ID apparaît désormais sur deux lignes :

Ne supprimez pas l'ancienne ligne. Stripe demande que l'ancien et le nouveau certificat soient tous deux présents avant l'activation, pour que l'un ou l'autre puisse servir pendant la transition. L'ancien certificat expirera de lui-même : aucune suppression n'est nécessaire.

Si l'import échoue, rien n'est encore activé : vous pouvez tout recommencer à l'étape 3 sans impact sur la production.

6. Activer le nouveau certificat chez Apple

Ne passez à cette étape que lorsque les deux lignes sont visibles dans Stripe.

1. Dans Apple Developer, ouvrez la page du nouveau certificat. Vérifiez la date d'expiration pour ne pas vous tromper de certificat.
2. Cliquez sur Activer (Activate) et notez l'heure.

Une fois l'activation faite, le bouton Activer disparaît ; seuls Révoquer et Télécharger restent affichés.

Ce qui se passe ensuite, d'après la documentation d'Apple et de Stripe :

• Un Merchant ID n'a qu'un seul certificat de traitement actif à la fois. L'activation du nouveau certificat invalide immédiatement l'ancien. Vous n'avez donc pas à révoquer l'ancien certificat vous-même.
• L'activation est irréversible. L'ancien certificat ne peut être ni réactivé ni restauré.
• La bascule prend un peu de temps. Pendant que le nouveau certificat se propage sur les serveurs Apple Pay, certaines transactions peuvent encore être chiffrées avec l'ancienne clé. Stripe indique qu'Apple utilise la nouvelle clé environ 5 minutes après l'activation. Comme les deux certificats sont présents dans Stripe, les paiements continuent d'être déchiffrés pendant cette période.

7. Tester Apple Pay

Le fait que le certificat soit actif chez Apple ne prouve pas que Stripe arrive à déchiffrer les paiements : seul un paiement Apple Pay réel le confirme. Attendez une dizaine de minutes après l'activation, puis faites le test.

Dans une application Chargekeeper, le test le plus simple ne débite rien :

1. Sur un iPhone avec une carte réelle dans Wallet, installez l'application depuis l'App Store. Une version de développement ou de recette utilise généralement un autre Merchant ID et ne teste pas le bon certificat.
2. Connectez-vous avec un compte interne, ou créez-en un.
3. Dans les moyens de paiement du compte, ajoutez Apple Pay : la fenêtre Apple Pay affiche un montant de 0,00 €. Validez avec Face ID, Touch ID ou le code.
4. Vérifiez que le moyen de paiement est bien enregistré dans l'application.

L'ajout doit être nouveau : si Apple Pay est déjà enregistré sur le compte, retirez-le d'abord ou utilisez un autre compte. C'est au moment de l'ajout que Stripe déchiffre les données d'Apple Pay.

Pour une vérification côté serveur, ouvrez dans Stripe Développeurs → Journaux : après l'heure d'activation, la requête POST /v1/tokens et la confirmation du SetupIntent qui la suit doivent être en 200.

Pensez ensuite à supprimer le compte de test, ou au moins à retirer le moyen de paiement.

Pour une autre intégration, Stripe recommande de faire un paiement Apple Pay avec les clés API de test et une vraie carte : Stripe détecte le mode test et ne la débite pas. Les cartes de test Stripe et les cartes sandbox d'Apple ne peuvent pas être ajoutées à Wallet.

Faut-il republier l'application sur l'App Store ?

Non, pas dans le scénario décrit ici.

L'application iOS ne contient ni le certificat ni sa clé. Elle déclare seulement un Merchant ID dans ses entitlements et le transmet à Apple Pay au moment du paiement. Apple chiffre alors les données de paiement avec le certificat actif de ce Merchant ID, et Stripe les déchiffre avec la clé privée correspondante.

Pendant le renouvellement, rien ne change dans l'application :

• ni le Merchant ID ;
• ni le Bundle ID ;
• ni les entitlements ;
• ni la capability Apple Pay ;
• ni le code.

Seul le certificat associé au Merchant ID est remplacé, côté Apple et côté Stripe. Aucune nouvelle build n'est donc nécessaire. Stripe le confirme : « You don't need to update your app after you've replaced the certificate. »

Une nouvelle publication ne devient nécessaire que si le Merchant ID déclaré par l'application change.

À ne pas faire

Ne créez pas de nouveau Merchant ID. Le renouvellement concerne le certificat, pas le Merchant ID. Un nouveau Merchant ID imposerait de modifier l'application et de la republier.

Ne modifiez pas le Merchant ID dans Xcode. Cela changerait la configuration de l'application et nécessiterait une nouvelle version.

N'utilisez pas un CSR généré localement ni un ancien CSR Stripe. Utilisez uniquement le CSR que Stripe fournit pour ce renouvellement.

N'activez pas le certificat chez Apple avant de l'avoir importé dans Stripe. L'activation est immédiate et irréversible. Si Stripe ne dispose pas du nouveau certificat, les paiements Apple Pay échouent.

Ne supprimez pas l'ancien certificat dans Stripe avant la bascule. Les deux doivent coexister pendant la transition.

Ne révoquez pas le certificat actif chez Apple. La révocation fait échouer immédiatement les paiements. L'activation du nouveau certificat suffit à remplacer l'ancien.

N'attendez pas l'expiration. Renouvelez au moins 30 jours à l'avance pour pouvoir tester sereinement.

Dépannage : Apple Pay ne fonctionne plus après le renouvellement

Vérifiez dans l'ordre :

1. Le Merchant ID : celui du certificat, dans Stripe comme chez Apple, est-il exactement celui déclaré dans les entitlements de production de l'application ?
2. Le compte Stripe : le certificat a-t-il été importé dans le compte Stripe dont l'application utilise la clé publique, et en mode production ?
3. Le type de certificat : le nouveau certificat a-t-il été créé dans la section Certificat de traitement des paiements Apple Pay du Merchant ID ?
4. Le CSR : le certificat a-t-il été créé à partir d'un CSR téléchargé depuis Stripe pour ce renouvellement ? Si ce n'est pas le cas, Stripe ne peut pas déchiffrer les paiements. Il faut recommencer à l'étape 3 avec un nouveau CSR Stripe.
5. L'import : les deux lignes du Merchant ID apparaissent-elles dans Stripe (Certificats iOS) ?
6. L'activation : chez Apple, le bouton Activer a-t-il bien disparu de la page du nouveau certificat ?
7. Le délai : l'activation date-t-elle de plus de quelques minutes ? Juste après, la bascule peut être encore en cours.
8. Le test : a-t-il été fait avec l'application de l'App Store (Merchant ID de production) et avec un nouvel ajout d'Apple Pay ?
9. Les journaux Stripe : dans Développeurs → Journaux, repérez l'erreur renvoyée. Le message « You haven't added your Apple merchant account to Stripe » signifie que les données ont été chiffrées avec un certificat que Stripe ne connaît pas.

Ne republiez pas l'application pour tenter de résoudre le problème : dans ce scénario, la cause se trouve côté certificat (Apple ou Stripe), pas dans l'application.

Si le problème persiste, contactez support@charge-keeper.com en indiquant le Merchant ID, l'heure d'activation du nouveau certificat et l'identifiant de la requête Stripe en échec.

Références

• Stripe — Apple Pay Best Practices : Apple Pay Certificate Renewal
• Stripe — Apple Pay (iOS) : Create a new Apple Pay certificate, Troubleshooting, Test Apple Pay
• Apple — TN3206 : Updating Apple Pay certificates
• Apple — Configure Apple Pay