Conseils sur l'intégration du backend pour la monétisation en dehors de Google Play Billing

L'API Google Play Developer comprend des fonctionnalités supplémentaires pour enregistrer les transactions provenant des programmes de facturation et d'association. Ce guide explique comment déclarer les transactions de ces programmes de facturation.

Certains composants peuvent être nécessaires pour gérer les transactions externes depuis votre backend. Pour les créer, vous devez configurer l'intégration du backend, comme indiqué dans la section Configurer l'API Google Play Developer. Pour créer des fonctionnalités de backend de développeur qui ne sont pas spécifiques aux programmes de facturation et d'association, consultez Système de facturation de Google Play.

Glossaire des termes

Termes utilisés dans ce guide :

  • Programmes de facturation et de liens : programmes qui facilitent l'achat de contenus numériques ou le téléchargement d'applications en dehors de Google Play. Cela inclut les programmes de système de facturation alternatif et d'offres externes.
  • API de transaction externes : API utilisées pour signaler les transactions pour les programmes de facturation et d'association éligibles.
  • Transaction externe : transaction éligible effectuée en dehors de l'application, telle que définie dans les exigences du programme. Cela inclut les achats de contenu numérique et les téléchargements d'applications.
  • Jeton de transaction externe : jeton fourni par la bibliothèque Play Billing que vous pouvez utiliser lorsque l'utilisateur effectue une transaction externe. Ce jeton permet d'informer Google Play qu'une transaction externe a réussi.
  • ID de transaction externe : identifiant unique généré par vous pour identifier une transaction externe.

Enregistrer les nouvelles transactions externes dans Google Play

Effectuez l'intégration avec l'API externaltransactions pour enregistrer les transactions qui ont lieu en dehors du système de facturation de Google Play dans les pays où cette fonctionnalité est disponible, y compris les transactions de 0 $ liées aux achats d'essais sans frais et aux installations d'applications. Vous ne devez lancer et enregistrer des transactions sur les programmes de facturation et d'association que pour les pays éligibles, conformément aux consignes relatives aux systèmes de facturation alternatifs ou aux offres externes. Dans le cas contraire, l'appel d'API sera rejeté. Cela s'applique à toutes les transactions, y compris les nouveaux achats, les renouvellements, les recharges de forfaits prépayés, les mises à niveau, les rétrogradations et les téléchargements d'applications.

Enregistrer les transactions externes

Une fois que le paiement a été autorisé via un programme de facturation et d'association, vous devez appeler l'API externaltransactions pour enregistrer une transaction externe. Cela s'applique à toutes les transactions, y compris les frais initiaux, les renouvellements, les remboursements, etc. Consultez les consignes du programme de facturation et d'association concerné pour connaître les exigences en matière de signalement.

Chaque transaction externe est enregistrée avec un ID de transaction externe. Pour les achats récurrents (abonnements renouvelables automatiquement, par exemple), vous devez envoyer l'ID de transaction externe associé à la première transaction de l'achat récurrent comme paramètre pour toutes les transactions ultérieures, y compris pour les remboursements. La série de transactions est ainsi enregistrée pour cet achat. Vous devez envoyer un nouvel ID de transaction externe pour les achats lorsque le produit change (par exemple, en cas de mise à niveau ou de rétrogradation), ou encore si la transaction récurrente est annulée ou si elle est arrivée à expiration et que le même produit est racheté ultérieurement. N'ajoutez pas d'informations permettant d'identifier personnellement l'utilisateur ni d'informations propriétaires ou confidentielles dans cet ID de transaction externe.

Signaler une transaction initiale

Chaque fois qu'un nouvel achat ou un nouveau téléchargement d'application est effectué avec succès dans les programmes de facturation et d'association, vous devez appeler l'API externaltransactions.

L'externalTransactionToken reçu par l'application via les rappels UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener ou BillingProgramReportingDetailsListener est requis dans le corps de la requête pour les téléchargements d'applications, les achats uniques et les premières transactions réalisées à l'occasion d'un achat récurrent, telles qu'un abonnement. C'est ce qu'on appelle une transaction initiale. Après la première transaction, enregistrez les transactions ultérieures (par exemple, les renouvellements d'abonnements) en fournissant un nouvel externalTransactionId unique. Pour découvrir comment enregistrer les transactions ultérieures, consultez la section Enregistrer les transactions ultérieures pour un achat.

Exemple :

  1. Un développeur configure et active un système de facturation alternatif dans son application.
  2. L'utilisateur 1 se trouve en Corée du Sud, un pays où cette fonctionnalité est disponible, et tente d'acheter product1 pour 12 634, 10 KRW/mois, avec une offre d'essai sans frais d'un mois.
  3. L'application lance le parcours d'achat avec les ProductDetails pour le product1 et l'offre sélectionnée par l'utilisateur.
  4. L'utilisateur 1 sélectionne le système de facturation alternatif du développeur.
  5. Le UserChoiceBillingListener reçoit la valeur my_token comme externalTransactionToken.
  6. Le développeur envoie ensuite les informations adaptées à son backend (valeur externalTransactionToken et produits achetés). Il lance ensuite le parcours d'achat du product1 dans le système de facturation alternatif. Du côté du développeur, un ID unique est attribué à la transaction pour l'enregistrer dans Google Play : 123-456-789. Cet ID de transaction est obligatoire, même si l'utilisateur bénéficie d'un essai sans frais.
  7. Une fois la transaction d'achat effectuée dans le système de facturation alternatif, le développeur enregistre la transaction dans Google Play avec la requête suivante. Dans un premier temps, elle est enregistrée comme une transaction de 0 $, car l'utilisateur bénéficie d'un mois gratuit.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Lorsque vous signalez une transaction initiale, tenez compte des points suivants :

  • subscriptionType peut indiquer RECURRING (pour les abonnements à renouvellement automatique) ou PREPAID (pour les abonnements prépayés).
  • OtherRecurringProduct doit être utilisé pour représenter les achats ponctuels qui nécessitent plusieurs paiements ou un paiement différé. Par exemple, une précommande peut comporter une transaction initiale de 0 $, suivie d'une deuxième transaction à une date ultérieure pour le prix du SKU lorsque la précommande est traitée. Pour découvrir comment enregistrer les transactions ultérieures, consultez Enregistrer les transactions ultérieures pour un achat.
  • Vous devez fournir ExternalOfferDetails lorsque vous signalez les transactions initiales d'offres externes. Cela n'est pas nécessaire pour les transactions ultérieures.

Si vous effectuez une transaction avec un utilisateur en Inde, où les taxes dépendent de sa région administrative (comme un État ou une province, par exemple), incluez cette région sous userTaxAddress. Pour en savoir plus sur les régions administratives, reportez-vous à la liste de chaînes prédéfinie dans le guide de référence de l'API.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

Offres externes

Si la transaction signalée relève du programme d'offres externes, vous devez définir le champ externalOfferDetails si la transaction est ponctuelle ou s'il s'agit de la première transaction d'une série récurrente :

  • Lorsque vous signalez des transactions de téléchargement d'applications, définissez linkType sur LINK_TO_APP_DOWNLOAD et fournissez les valeurs appropriées pour installedAppPackage et installedAppCategory. Pour en savoir plus, consultez Signaler le téléchargement d'une application.
  • Lorsque vous signalez des transactions d'offres de contenu numérique, définissez linkType sur LINK_TO_DIGITAL_CONTENT.
  • Une fois qu'une application externe est installée via le programme d'offres externes, vous devez signaler les transactions effectuées dans l'application externe. Lorsque vous signalez ces transactions, associez-les à l'événement de téléchargement de l'application d'origine :
    • Fournissez le externalTransactionToken de l'événement de téléchargement de l'application.
    • Dans le champ externalOfferDetails, définissez appDownloadEventExternalTransactionId sur externalTransactionId de l'événement de téléchargement de l'application. Les autres champs de externalOfferDetails ne sont pas obligatoires.

Exemple de requête pour une transaction dans une application externe téléchargée via des offres externes :

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "currency": "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode": "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
 }
}

Vous trouverez les détails mis à jour des frais de service Play pour les différents types de transactions dans Modifications apportées au programme d'offres externes pour les utilisateurs de l'Espace économique européen (EEE).

Enregistrer les transactions ultérieures pour un achat

Dans certains cas, plusieurs paiements utilisateur sont associés au même achat externe (par exemple, pour les renouvellements d'abonnements ou les recharges de forfaits prépayés). Vous pouvez enregistrer ces transactions ultérieures avec la même API dans Externaltransactions. Comme indiqué dans la section Enregistrer un nouvel achat, l'externalTransactionToken n'est pas nécessaire pour les transactions ultérieures. À la place, un nouvel externalTransactionId unique est envoyé en tant que paramètre de requête pour chaque transaction de renouvellement ou de recharge d'un forfait prépayé. L'ID de la transaction initiale est inclus dans le champ initialExternalTransactionId.

Pour reprendre l'exemple précédent :

  1. Le premier renouvellement de l'utilisateur 1 a lieu sur le système de facturation alternatif. L'ID de transaction d'origine était 123-456-789.
  2. Le développeur enregistre la récurrence de la transaction dans le paramètre de requête d'URL comme ID de transaction externe pour cette nouvelle transaction, tout en référençant l'ID de transaction externe de la transaction initiale dans le champ initialExternalTransactionId.

Exemple de requête :

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Enregistrer une mise à niveau ou une rétrogradation

Pour enregistrer une mise à niveau ou une rétrogradation lorsque l'utilisateur possède un abonnement dans le système de facturation alternatif, utilisez le même point de terminaison et la même fonction dans l'API Externaltransactions, en envoyant l'externalTransactionToken fourni à l'application pour la transaction de mise à niveau ou de rétrogradation. Cette opération s'apparente à l'enregistrement d'un nouvel achat.

Signaler le téléchargement d'une application

Pour enregistrer une installation d'application dans le système de facturation des offres externes, vous devez appeler Externaltransactions.createexternaltransaction en envoyant l'externalTransactionToken fourni à l'application. Enregistrez-la comme une transaction unique sans frais. Cette procédure est semblable à l'enregistrement d'une transaction initiale. Veillez à inclure ExternalOfferDetails dans le corps de la requête.

Exemple de requête :

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": "my_token",
 },
 "userTaxAddress" : {
   "regionCode": "US"
 }
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

Migrer depuis la création manuelle de rapports sur les transactions de systèmes de facturation alternatifs

Pour migrer des abonnements actifs qui ont commencé alors que vous proposiez un système de facturation alternatif sans création de rapports automatisés, créez une transaction sans frais à l'aide du champ migratedTransactionProgram au lieu de spécifier une initialExternalTransactionId ou une externalTransactionToken. Définissez transactionTime sur l'heure à laquelle l'utilisateur a souscrit chaque abonnement actif pour la première fois. Ensuite, enregistrez chaque transaction ultérieure pour ces abonnements comme d'habitude via les API, en fournissant l'initialExternalTransactionId utilisé précédemment pour créer les transactions de renouvellement. Une fois l'abonnement migré, vous n'aurez plus besoin de déclarer manuellement les transactions ultérieures pour l'abonnement, à condition qu'elles soient signalées via les méthodes automatisées décrites sur cette page.

Lors de la migration des abonnements, tenez compte des limites de quota en place pour vous assurer que la migration n'entraîne pas d'interruption de quota. Si de nombreux abonnements doivent être migrés, répartissez-les sur plusieurs jours ou demandez à augmenter le quota.

Le champ migratedTransactionProgram ne peut être utilisé que lors de la migration à partir de la création manuelle de rapports. Il deviendra obsolète lorsque la création manuelle de rapports ne sera plus disponible.

Exemple de requête :

# Note that the externalTransactionId specified here will used to report
# subsequent transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Conditions requises pour les programmes partenaires Play

Les développeurs participant à des programmes partenaires tels que le Programme Play Media Experience doivent fournir le transaction_program_code lorsqu'ils signalent des transactions externes. Si vous êtes un développeur éligible, contactez votre responsable du développement commercial pour savoir comment définir ce champ.

Enregistrer des remboursements d'achats dans Google Play

Effectuez l'intégration avec l'API externaltransactions pour enregistrer les transactions remboursées aux utilisateurs en dehors du système de facturation de Google Play. Pour que Play identifie correctement la transaction remboursée, vous devez inclure l'externalTransactionId correspondant à la transaction enregistrée précédemment dans les paramètres d'URL.

Lorsque vous enregistrez le remboursement d'un achat d'abonnement, faites référence à l'externalTransactionId associé à la récurrence spécifique de l'abonnement qui fait l'objet du remboursement.

Exemple : Supposons qu'un abonnement présente les transactions ci-dessous.

  • Une transaction initiale avec l'ID de externe ABC.1234-5678-9012-34567

  • La première transaction récurrente avec l'ID externe ABC.1234-5678-9012-34567..0

  • La deuxième transaction récurrente avec l'ID externe ABC.1234-5678-9012-34567..1

Pour enregistrer un remboursement de toutes les transactions de l'abonnement, vous devez effectuer trois demandes de remboursement distinctes : une pour la transaction initiale et deux pour les transactions suivantes.

Cette méthode accepte à la fois les remboursements complets (où le montant est identique à celui que l'utilisateur a payé lors de la transaction externe d'origine) et les remboursements partiels (où le montant est inférieur à celui payé par l'utilisateur lors de la transaction externe d'origine). Pour les remboursements partiels, vous devez spécifier le montant hors taxes qui a été remboursé.

Quotas d'API

L'API Externaltransactions est soumise à des quotas d'API pour tous les appels, comme n'importe quel autre point de terminaison de l'API Google Play Developer.

En outre, l'API Externaltransactions impose une limite de 1 200 requêtes par minute (RPM) pour les appels à Externaltransactions.createexternaltransaction ou Externaltransactions.refundexternaltransaction. Les appels à Externaltransactions.getexternaltransaction ne sont pas comptabilisés dans cette limite de 1 200 RPM.