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 inclut désormais des pour enregistrer les transactions issues d'un système de facturation alternatif ou d'offres externes. Ce guide explique comment signaler d'autres la facturation ou les transactions 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 au système de facturation alternatif ou les API d'offres externes, les instructions du La documentation du système de facturation de Google Play s'applique.

Enregistrer les nouvelles transactions externes dans Google Play

Intégration à Externaltransactions APIs pour enregistrer les transactions qui ont lieu en dehors du système de facturation de Google Play pays où la fonctionnalité est disponible, y compris les transactions à 0 $ issues d'un essai sans frais achats. Transactions sur des systèmes de facturation alternatifs ou d'offres externes ne doivent être lancées et signalées que pour les pays où les utilisateurs sont éligibles, dans la limite autorisée sous le système de facturation alternatif ou programmes d'offres externes. Sinon, l'appel d'API sera refusé. Cela s'applique à toutes les transactions, y compris les nouveaux achats, les renouvellements, les recharges de forfait, les mises à niveau, les rétrogradations, etc.

Enregistrer les transactions externes

Vous devez appeler Externaltransactions API pour signaler une transaction externe une fois que le paiement a été autorisé par le système de facturation alternatif ; ou d'un système d'offres externe. Cela s'applique à toutes les transactions, y compris les transactions initiales débits, renouvellements, remboursements, etc. Toutes les transactions doivent être dans les 24 heures suivant la transaction.

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. Vous ne devez pas inclure d'informations permettant d'identifier des informations propriétaires ou confidentielles. Ces informations externes ID de la transaction.

Enregistrer un nouvel achat

Chaque fois qu'un nouvel achat aboutit avec le système de facturation alternatif ou externe, un appel à l'API Externaltransactions est obligatoire. Pour ces nouveaux achats, vous devez fournir un identifiant unique externalTransactionId associé à l'achat dans votre backend en tant que requête . Cet élément externalTransactionId ne peut pas être réutilisé dans la même application l'ID du package.

Le externalTransactionToken reçu par l'application via la UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener, ou ExternalOfferReportingDetailsListener est également requis dans le cadre le corps de la requête pour les achats uniques et les premières transactions un achat récurrent (un abonnement, par exemple). Dans les deux cas, cela s'appelle une transaction initiale. Après la première transaction, externalTransactionToken n'est plus nécessaire, et vous signalez les cas suivants des transactions (comme les renouvellements d'abonnements) en fournissant externalTransactionId Reportez-vous à la section Enregistrer les transactions ultérieures pour un achat. pour savoir comment enregistrer les transactions ultérieures.

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 des 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é 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 ont besoin répartissez-les sur plusieurs jours ou demandez une augmentation dans le quota pour en savoir plus.

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 les programmes Partenaires Play

Les développeurs qui participent à des programmes partenaires tels que Le Programme Play Media Experience doit fournir les transaction_program_code lorsque vous enregistrez des transactions externes. Si vous utilisez un développeur éligible, contactez votre Business Development Manager pour plus sur la façon de 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 les remboursements totaux. (où le montant est identique à celui que l'utilisateur a payé sur la page de paiement transaction) et les remboursements partiels (où le montant est inférieur à celui payé par l'utilisateur dans la vidéo transactionnel). 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.