L'API Google Play Developer inclut désormais des fonctionnalités supplémentaires pour enregistrer les transactions provenant d'un système de facturation alternatif ou d'offres externes. Ce guide explique comment enregistrer les transactions avec système de facturation alternatif ou avec 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 facturation alternative ou d'offres externes, suivez les instructions de la documentation du système de facturation Google Play.
Enregistrer les nouvelles transactions externes dans Google Play
Procédez à l'intégration avec Externaltransactions APIs pour enregistrer les transactions qui ont lieu en dehors du système de facturation de Google Play dans les pays où le service est disponible, y compris les transactions à 0 $ résultant d'achats en essai sans frais. Les transactions sur des systèmes de facturation alternatifs ou d'offres externes ne doivent être lancées et enregistrées que pour les pays d'utilisateurs éligibles, conformément aux programmes de système de facturation alternatif ou 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 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 d'offres externes, vous devez appeler 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 déclarées dans les 24 heures qui suivent.
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 personnellement l'utilisateur, propriétaires ou confidentielles dans cet ID de transaction externe.
Enregistrer un nouvel achat
Chaque fois qu'un nouvel achat aboutit dans le système de facturation alternatif ou 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. Ce externalTransactionId ne peut pas être réutilisé dans l'ID de package de la même application.
Le 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 lors d'un achat récurrent (comme un abonnement). Dans les deux cas, on parle alors de transaction initiale. Après la transaction initiale, le externalTransactionToken n'est plus nécessaire et vous enregistrez les transactions ultérieures (par exemple, les renouvellements d'abonnement) en fournissant un nouvel externalTransactionId unique. Pour savoir 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
product1pour 12 634,10 KRW/mois, avec une offre d'essai sans frais d'un mois. - L'application lance le parcours d'achat avec les
ProductDetailspour leproduct1et l'offre sélectionnée par l'utilisateur. - L'utilisateur 1 sélectionne le système de facturation alternatif du développeur.
- Le
UserChoiceBillingListenerreçoit la valeurmy_tokencommeexternalTransactionToken. - Le développeur envoie ensuite les informations adaptées à son backend (valeur
externalTransactionTokenet produits achetés). Il lance ensuite le parcours d'achat duproduct1dans 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 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"
}
}
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.
Abandonner 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 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"
}
}
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 payé par l'utilisateur 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.