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 de programmes de facturation et de liens. Ce guide explique comment enregistrer les transactions provenant 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 qui ne sont pas spécifiques aux programmes de facturation et de liens, 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 les achats de contenus numériques ou les téléchargements d'applications en dehors de Google Play. Cela inclut les programmes de facturation alternatifs et de contenus externes.
  • API de transactions externes : API utilisées pour enregistrer les transactions pour les programmes de facturation et de liens éligibles.
  • Transaction externe : transaction éligible qui a lieu en dehors de l' application, comme défini par les programmes de système de facturation alternatif et de contenus externes.
  • Jeton de transaction externe : jeton fourni via la bibliothèque Play Billing que vous pouvez utiliser lorsque l'utilisateur lance une transaction externe. Ce jeton permet d'informer Google Play d'une transaction externe autorisée.
  • ID de transaction externe : identifiant unique généré par vous pour identifier une transaction externe.

Enregistrer les nouvelles transactions externes dans Google Play

Procédez à 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 essais sans frais et les installations d'applications. Vous ne devez lancer et enregistrer des transactions sur des programmes de facturation et de liens que pour les pays d'utilisateurs éligibles, conformément aux systèmes de facturation alternatifs et de contenus externes. Dans le cas contraire, l'appel d'API sera rejeté. Ceci 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 qu'un paiement a été autorisé via un programme de facturation et de liens, 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. Pour connaître les exigences en matière d'enregistrement, consultez les consignes du programme de facturation et de liens concerné.

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

Enregistrer une transaction initiale

Chaque fois qu'un nouvel achat ou téléchargement d'application est autorisé dans des programmes de facturation et de liens, vous devez appeler l'API externaltransactions.

L'externalTransactionToken reçu par l'application via la bibliothèque Google Play Billing 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 que nous appelons 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 en savoir plus, 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 par mois, avec une offre d'essai sans frais d'un mois.
  3. L'application lance le parcours d'achat avec les ProductDetails pour 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 de transaction unique est attribué à cette transaction pour l'enregistrer dans Google Play : 123-456-789. L'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 sans frais.
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 enregistrez 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 uniques 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 de la référence lorsque la précommande est honorée. Pour en savoir plus sur l'enregistrement des transactions ultérieures, consultez la section Enregistrer les transactions ultérieures pour un achat.
  • Vous devez fournir ExternalOfferDetails lorsque vous enregistrez des transactions d'offres externes initiales. Cela n'est pas nécessaire pour les transactions ultérieures.

Si vous effectuez une transaction avec un utilisateur résidant en Inde, où les taxes varient en fonction de leur région administrative (comme l'État ou la province, par exemple), veillez à inclure cette zone 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 enregistrée fait partie du programme d'offres externes, vous devez définir le champ externalOfferDetails si la transaction est unique ou s'il s'agit de la première transaction d'une série récurrente :

  • Lorsque vous enregistrez 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 la section Enregistrer un téléchargement d'application.
  • Lorsque vous enregistrez des transactions d'offres de contenus numériques, définissez linkType sur LINK_TO_DIGITAL_CONTENT_OFFER.
  • Une fois qu'une application externe est installée via le programme d'offres externes, vous devez enregistrer les transactions effectuées dans l'application externe. Lorsque vous enregistrez ces transactions, associez-les à l'événement de téléchargement d'application d'origine :
    • Fournissez l'externalTransactionToken de l'événement de téléchargement d'application.
    • Dans le champ externalOfferDetails, définissez appDownloadEventExternalTransactionId sur l'externalTransactionId de l'événement de téléchargement d'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" : "990000", # 0.99 EUR
   "currency" : "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros" : "90000", # 0.09 EUR
   "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"
 }
}

Pour en savoir plus sur les frais de service Play mis à jour pour différents types de transactions, consultez 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.

Suite de 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", # 12634 KRW
   "currency" : "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros" : "1263000000", # 1263 KRW
   "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.

Enregistrer un téléchargement d'application

Pour enregistrer une installation d'application dans le système de facturation des offres externes, vous devez appeler Externaltransactions.createexternaltransaction, en envoyant le externalTransactionToken fourni à l'application. Enregistrez-le comme une transaction unique sans frais. Ce processus 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"
 }
}

Effectuer une migration 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 vous devez migrer de nombreux abonnements, répartissez-les sur plusieurs jours ou demandez une augmentation de 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 Play Media Experience Program doivent fournir le transaction_program_code lorsqu'ils enregistrent des transactions externes. Si vous êtes un développeur éligible, contactez votre responsable Business Development 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 comporte les transactions suivantes :

  • Une transaction initiale avec l'ID de transaction 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.