Cette page a été traduite par l'API Cloud Translation.

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

L'API Google Play Developer comprend désormais des fonctionnalités supplémentaires pour enregistrer les transactions provenant d'un système de facturation alternatif ou de offres externes. Ce guide explique comment enregistrer les transactions de facturation alternative ou d'offres externes.

Certains composants peuvent être nécessaires pour gérer les achats via une application 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 toutes les fonctionnalités de backend qui ne sont pas spécifiques aux API de système de facturation alternatif ou d'offres externes, suivez les instructions fournies dans la documentation du système de facturation de Google Play.

Enregistrer les nouvelles transactions externes dans Google Play

Procédez à l'intégration avec les Externaltransactions APIs 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. Les transactions effectuées sur des systèmes de facturation alternatifs ou d'offres externes ne doivent être lancées et enregistrées que si l'utilisateur se trouve dans un pays éligible, conformément aux programmes de systèmes de facturation alternatifs ou d'offres externes, sinon 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, etc.

Enregistrer les transactions externes

Une fois que le paiement a été autorisé via le système de facturation alternatif ou le système d'offres externes, vous devez appeler l'Externaltransactions API pour enregistrer une transaction externe. Cela s'applique à toutes les transactions, y compris les frais initiaux, les renouvellements, les remboursements, etc. Toutes les transactions doivent être enregistrées dans les 24 heures à compter du moment où elles sont effectuées.

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 un nouvel achat

Chaque fois qu'un nouvel achat a lieu dans le système de facturation alternatif ou dans le système d'offres externes, un appel à l'API Externaltransactions est nécessaire. Pour ces nouveaux achats, vous devez fournir un externalTransactionId unique associé à l'achat dans votre backend en tant que paramètre de requête. Cet externalTransactionId ne peut pas être réutilisé dans l'ID de package de la même application.

L'externalTransactionToken reçu par l'application via les rappels UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener ou ExternalOfferReportingDetailsListener est également requis dans le corps de la requête pour les achats uniques et les premières transactions réalisées à l'occasion d'un achat récurrent, telles qu'un abonnement. Dans les deux cas, il s'agit d'une transaction initiale. Après la première transaction, l'externalTransactionToken n'est plus nécessaire. Vous enregistrerez 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 :

Un développeur configure et active un système de facturation alternatif dans son application.
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.
L'application lance le parcours d'achat avec les ProductDetails pour le product1 et l'offre sélectionnée par l'utilisateur.
L'utilisateur 1 sélectionne le système de facturation alternatif du développeur.
Le UserChoiceBillingListener reçoit la valeur my_token comme externalTransactionToken.
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.
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"
 }
}

Si vous effectuez une transaction avec un utilisateur résidant en Inde, où les taxes varient en fonction de la 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"
 }
}

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 :

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

Migrer depuis la création manuelle de rapports sur les transactions via un système de facturation alternatif

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é ci-dessus 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"
 }
}

Signaler des 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 Business Development pour en savoir plus sur la configuration de 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 quotidiens 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.