App Store Server Notifications V2 en 2026
Apple a fermé la voie de la version 1 : les notifications version 1 et le point de terminaison App Store Receipts sont dépréciés, et la consigne indique désormais « implémentez le point de terminaison version 2 sur votre serveur ». Pour une application avec des abonnements actifs, il ne s’agit pas d’une migration cosmétique — le flux de notifications est le moyen par lequel votre serveur apprend qu’un renouvellement a réussi, qu’un remboursement a été émis, qu’une facturation est retentée ou que Apple vous demande de justifier une demande de remboursement. Ce tutoriel couvre l’installation complète 2026 : activer la version 2 dans App Store Connect, vérifier le JWS, mapper chaque type et sous-type de notification, et utiliser le App Store Server API pour l’état qu’une notification ne décrit qu’à un instant donné.
La version en une ligne : App Store Connect envoie un objet JSON signé JWS à votre URL HTTPS ; vérifiez la chaîne de signature, décodez signedPayload, agissez sur notificationType et subtype, répondez 200-206 rapidement, et appelez l’API App Store Server dès que vous avez besoin de l’état actuel plutôt que de l’état de l’événement.
Étape 1 — Corrigez les deux points de terminaison avant de toucher à App Store Connect
You need one HTTPS URL for production and, optionally, a second one for sandbox; Apple explicitly allows you to use the same URL for both environments. Your server must support TLS 1.2 or later. If the URL contains a port, it must be either 443 or 1024 and above — https://example.com:1234/notifications is a valid shape, a low privileged port is not. And if your edge terminates behind an IP allow list, add Apple's 17.0.0.0/8 subnet, which applies to sandbox and production alike. All of this is documented in Enabling App Store Server Notifications.
Étape 2 — activer la version 2 par environnement
Dans App Store Connect, ouvrez votre application, puis Informations sur l’app > App StoreNotifications serveur. La production et le sandbox se configurent séparément, et chaque environnement choisit indépendamment la version 2 ou la version 1 dépréciée — c’est ce qui vous permet d’exploiter le nouveau format en production tandis que l’ancien doit encore fonctionner ailleurs, ou l’inverse. Le parcours de migration indiqué par Apple consiste à tester d’abord la version 2 dans l’environnement sandbox, puis seulement à basculer la production. Un comportement à connaître avant de commencer le débogage : la notification TEST est toujours envoyée au format version 2, quelle que soit la version attendue par l’URL configurée.
Étape 3 — Répondez avec le bon code de statut, puis travaillez en asynchrone
Répondez avec un code de statut HTTP 200-206 si le POST a été traité avec succès. S’il ne l’a pas été, envoyez un 50x ou 40x pour que App Store réessaie la notification. Le schéma pratique est le suivant : lire le corps, le vérifier, le mettre en file d’attente, répondre 200, puis effectuer le vrai travail dans un worker. Ne gardez pas la connexion ouverte pendant que vous appelez votre propre base de données, votre fournisseur d’e-mail ou l’API App Store Server. Les nouvelles tentatives servent à vous protéger contre une défaillance d’infrastructure, pas contre un gestionnaire lent — et chaque nouvelle tentative déclenchée est un événement en double qu’il vous faut ensuite supprimer.
Étape 4 — Décoder la charge utile
Le corps est un objet responseBodyV2 dont le seul champ significatif est signedPayload, un JWS. Analysez-le en ses représentations d’en-tête, de charge utile et de signature, puis décodez la charge utile en Base64URL pour obtenir le responseBodyV2DecodedPayload. À ce niveau, vous obtenez notificationType, subtype, version, signedDate et notificationUUID. Un seul des quatre objets de données est présent : data pour les événements d’achat intégré, portant un signedTransactionInfo et — pour les abonnements à renouvellement automatique — un signedRenewalInfo ; summary, qui n’apparaît que pour un RENEWAL_EXTENSION avec le sous-type SUMMARY ; appData ; ou externalPurchaseToken, qui n’apparaît que sur une notification EXTERNAL_PURCHASE_TOKEN.
Étape 5 — vérifier chaque signature, pas seulement la signature externe
Les trois représentations signées — signedPayload, signedTransactionInfo et signedRenewalInfo — portent chacune leur propre signature JWS, et chacune doit être validée ; utilisez l’algorithme indiqué dans le paramètre alg de l’en-tête. Concrètement, cela signifie vérifier la chaîne de certificats x5c jusqu’à la racine publiée par Apple, que vous téléchargez depuis la page de l’autorité de certificationApple (la racine actuelle pour ce service est AppleRootCA-G3.cer). Ne faites pas cela vous-même : Apple publie la App Store Server Library pour Python, Java, Node.js et Swift, qui effectue la vérification et le décodage à votre place. Un gestionnaire qui décode la charge utile en Base64 et saute la vérification est trivialement falsifiable — quiconque découvre votre URL de notification peut s’accorder un abonnement.
Étape 6 — Associer notificationType et subtype à vos droits
L’énumération de la version 2 définit 23 types de notification, et 19 sous-types qui en qualifient certains ; les deux listes sont publiées sur notificationType et subtype. Ceux qui déterminent si un client payant conserve l’accès :
SUBSCRIBED— avec les sous-typesINITIAL_BUY,RESUBSCRIBE,UPGRADEetDOWNGRADE. Accordez l’accès et enregistrez l’identifiant du produit, pas seulement « subscribed ».DID_RENEW— avec les sous-typesBILLING_RECOVERYetBILLING_RETRY. Un renouvellement survenu après un problème de paiement arrive aussi ici : traitez-le comme une prolongation normale de l’accès.DID_FAIL_TO_RENEW— avec le sous-typeGRACE_PERIODlorsque le client se trouve dans un délai de grâce. L’accès continue généralement ici, ce qui est tout l’intérêt des délais de grâce.GRACE_PERIOD_EXPIRED— le délai de grâce est écoulé. C’est le moment de rétrograder, pas au moment du prélèvement refusé.EXPIRED— avec les sous-typesVOLUNTARY,BILLING_RETRYetPRODUCT_NOT_FOR_SALE. Ce dernier compte si vous retirez un produit de la vente alors que des utilisateurs le détiennent encore.DID_CHANGE_RENEWAL_STATUS(AUTO_RENEW_ENABLED/AUTO_RENEW_DISABLED) etDID_CHANGE_RENEWAL_PREF(UPGRADE/DOWNGRADE) — un client qui a désactivé le renouvellement automatique conserve ses droits jusqu’à la fin de la période, donc ne révoquez jamais surAUTO_RENEW_DISABLED.REFUND,REFUND_DECLINED,REFUND_REVERSED,REVOKEetRESCIND_CONSENT— le volet révocation. Un remboursement annulé signifie que l’argent vous est revenu, donc le droit d’accès doit aussi revenir au client.CONSUMPTION_REQUEST— Apple demande des preuves sur l’utilisation de l’achat ; voir l’étape 7.OFFER_REDEEMED,PRICE_CHANGE,PRICE_INCREASE(ACCEPTED/PENDING),RENEWAL_EXTENDEDetRENEWAL_EXTENSION(SUMMARY/FAILURE) — des changements commerciaux et de dates qui nécessitent généralement une notification au client plutôt qu’une modification de l’accès.METADATA_UPDATE,MIGRATION,ONE_TIME_CHARGE,TESTetEXTERNAL_PURCHASE_TOKEN(avec le sous-typeUNREPORTEDlorsque Apple a généré un token pour lequel il n’a aucun rapport).
Le catalogue complet, avec les ajouts récents, se trouve dans le journal des modifications des notifications — Apple ajoute des champs et des valeurs au fil du temps, alors relisez-le avant de considérer que votre gestionnaire est complet.
Étape 7 — Répondre à une CONSUMPTION_REQUEST sous 12 heures
Lorsqu’un client demande un remboursement pour tout type de produit — consommable, non consommable, non renouvelable ou à renouvellement automatique —, Apple envoie un CONSUMPTION_REQUEST. Si le client a consenti, vous pouvez répondre en appelant Send Consumption Information avec les données d’usage demandées par Apple, et Apple documente une fenêtre de réponse de 12 heures à compter de la réception de la notification. Si le client n’a pas consenti, vous ne répondez pas du tout. Deux règles sont faciles à rater : le consentement requis pour cette API est distinct de celui collecté pour le suivi ou la publicité, et c’est à vous qu’il incombe d’obtenir un consentement valide avant de partager des données d’usage avec Apple.
Étape 8 — Utilisez l’App StoreAPI Server pour l’état, pas pour l’événement
Une notification décrit un instant. Avant de rédiger les droits, clarifiez le présent :
- Obtenir les informations de transaction pour une transaction unique, y compris son motif et sa date de révocation.
- Get All Subscription Statuses pour obtenir la vue de référence des abonnements d’un client.
- Get Refund History lorsque vous avez besoin des remboursements liés à un identifiant de transaction d’origine.
- Prolonger une date de renouvellement d’abonnement pour compenser une interruption de service. Deux caractéristiques font de cette opération une décision irréversible : une fois la prolongation appliquée il n’existe aucun moyen de l’annuler, et les abonnements des membres de la famille sont prolongés automatiquement, tandis que les demandes directes portant sur l’abonnement d’un membre de la famille ne sont pas prises en charge. La période de prolongation ne compte pas non plus dans l’année de service payant Apple utilisée pour calculer le taux de commission.
Étape 9 — Prouvez que le circuit fonctionne avant de vous y fier
Appelez Request a Test Notification et App Store envoie une notification TEST à votre endpoint. Cet appel renvoie un jeton que vous transmettez à Get Test Notification Status sous six mois pour voir comment votre serveur a réellement répondu. Par ailleurs, si votre endpoint était indisponible à 3 h du matin, Get Notification History renvoie les notifications de version 2 que App Store a tenté d'envoyer : 180 jours en production, 30 jours dans le sandbox, 20 enregistrements par page avec un jeton de continuation, et le contenu complet des notifications. Gardez en tête ce qu'est cet historique : chaque enregistrement reflète l'état au moment où la notification a été envoyée à l'origine, et non l'état actuel.
Étape 10 — Les règles opérationnelles qui maintiennent le pipeline correct
- Lisez
l’environnementavant d’écrire quoi que ce soit. Le trafic sandbox atteint les URL sandbox ; si un gestionnaire partagé écrit des droits de production à partir d’un événement sandbox, les tests deviennent un incident de données. - Dédupliquez sur
notificationUUID. Les nouvelles tentatives et votre propre retraitement produisent le même événement plusieurs fois ; stockez l’identifiant et écartez les doublons. - Ne traitez jamais une notification comme un reçu. Une version qui n’écoute que
SUBSCRIBEDetDID_RENEW, et ignoreREFUND,REVOKEetREFUND_REVERSED, laisse fuiter l’accès payant de façon permanente. Gérez tout le cycle de vie ou confiez la vérification à la bibliothèque de Apple et interrogez l’API serveur. - Tenez votre propre journal d'événements. En cas de contestation d'accès par un client, l'historique des notifications et votre journal vous permettent de reconstituer la décision.
- Prévoyez que le point de terminaison fasse partie de la production. Il nécessite une supervision, un délai d’expiration des requêtes bien inférieur au budget de connexion et une file d’attente — pas une chaîne d’appels synchrones vers votre système de facturation.
Sources
- Notifications serveur Apple Developer — App Store : developer.apple.com/documentation/appstoreservernotifications
- Apple Developer — App Store Server Notifications V2 : app-store-server-notifications-v2
- Apple Développeur — Activer les App Store notifications serveur : enabling-app-store-server-notifications
- Apple Developer — énumérations notificationType et subtype : notificationtype / subtype
- Apple Développeur — responseBodyV2DecodedPayload : responsebodyv2decodedpayload
- Apple Developer — API serveur App Store : developer.apple.com/documentation/appstoreserverapi
- Apple — bibliothèque serveur App Store (Python) : github.com/apple/app-store-server-library-python
- Apple — autorité de certification : www.apple.com/certificateauthority
Vous gérez des comptes développeur à grande échelle ? Nous prenons en charge le volet opérationnel.
Nous avons bien reçu votre message et vous répondrons sous 24 heures.
← Retour à la modification