API Voided Purchases

L'API Voided Purchases de Google Play fournit la liste des commandes associées aux achats qu'un utilisateur a annulés. Vous pouvez utiliser les informations de cette liste pour implémenter un système de révocation qui empêche l'utilisateur d'accéder aux produits de ces commandes.

Cette API s'applique aux commandes et abonnements ponctuels effectués via une application.

Un achat peut être annulé pour les raisons suivantes :

• L'utilisateur demande le remboursement de sa commande.
• L'utilisateur annule sa commande.
• Une commande est rejetée.

• Le développeur annule ou rembourse la commande.

  Remarque :Seules les commandes annulées seront affichées dans l'API Voided Purchases. Si un développeur rembourse un achat sans définir l'option de révocation, la commande ne sera pas renvoyée par l'API.

• Google annule ou rembourse la commande.

En utilisant cette API, vous contribuez à créer une expérience plus équilibrée et équitable pour tous les utilisateurs de votre application, en particulier s'il s'agit d'un jeu.

Remarque :Contrairement à d'autres sources de données liées aux commandes, l'API Voided Purchases inclut les achats qui sont rejetés par les sociétés de traitement des paiements. Il est donc possible que vous constatiez des incohérences entre les informations de cette API et celles d'autres sources de données liées aux commandes.

Remarque :L'API Voided Purchases ne renvoie des achats annulés que lorsqu'ils doivent être annulés. Les développeurs peuvent se servir de cette API pour savoir quand prendre des mesures supplémentaires de leur part.

Accès

Pour utiliser l'API Voided Purchases, vous devez être autorisé à afficher les informations financières. Pour accorder une autorisation, vous devez utiliser un client OAuth ou un compte de service. Si vous utilisez un compte de service, activez l'autorisation "Afficher les rapports financiers" dans ce compte.

Pour en savoir plus sur l'obtention d'un accès autorisé aux API Google Play Developer, consultez les guides suivants:

• Configurer les clients d'accès à l'API
• Ajouter des utilisateurs à un compte développeur et gérer les autorisations

Afficher les achats annulés

Utilisez la méthode GET pour demander la liste des achats annulés. Dans votre requête, incluez le nom de package complet de votre application (par exemple, com.google.android.apps.maps) et le jeton d'autorisation que vous avez reçu lors de l'accès à l'API.

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

Vous pouvez également inclure les paramètres suivants dans votre requête, chacun étant facultatif:

startTime

Durée, en millisecondes depuis l'epoch Unix, du plus ancien achat annulé que vous voulez voir dans la réponse. Par défaut, startTime est défini sur il y a 30 jours.

L'API ne peut afficher que les achats annulés qui ont eu lieu au cours des 30 derniers jours. Les achats annulés plus anciens ne sont pas inclus dans la réponse, quelle que soit la valeur que vous avez fournie pour startTime.

Remarque:Les achats annulés dans la réponse sont filtrés en fonction de l'heure à laquelle un enregistrement donné est considéré comme annulé par l'API, et non en fonction de la valeur de voidedTimeMillis renvoyée dans la réponse.

endTime

Durée, en millisecondes depuis l'epoch Unix, du dernier achat annulé que vous souhaitez voir dans la réponse. Par défaut, endTime est défini sur l'heure actuelle.

Remarque:Les achats annulés dans la réponse sont filtrés en fonction de l'heure à laquelle un enregistrement donné est considéré comme annulé par l'API, et non par la valeur de voidedTimeMillis renvoyée dans la réponse.

maxResults

Nombre maximal d'achats annulés qui apparaissent dans chaque réponse. Par défaut, cette valeur est de 1 000. Notez que la valeur maximale de ce paramètre est également de 1 000.

jeton

Jeton de continuité d'une réponse précédente, vous permettant d'afficher plus de résultats.

Type

Type d'achats annulés qui apparaissent dans chaque réponse. Si la valeur est 0, seuls les achats via une application annulés sont renvoyés. Si la valeur est 1, les achats via une application annulés et les achats d'abonnements annulés sont renvoyés. La valeur par défaut est 0.

Remarque:Avant de demander à recevoir les achats d'abonnements annulés, vous devez utiliser "orderId" dans la réponse, qui identifie de manière unique les achats et abonnements ponctuels. Sinon, vous recevrez plusieurs commandes d'abonnement avec le même purchaseToken.

includeQuantityBasedPartialRefund

Permet d'inclure ou non les achats annulés pour les remboursements partiels basés sur une quantité, qui ne s'appliquent qu'aux achats de quantités multiples. Si la valeur est true, les achats annulés supplémentaires peuvent être renvoyés avec voidedQuantity qui indique le nombre d'un remboursement partiel basé sur la quantité. La valeur par défaut est false.

Remarque:Lorsque la quantité totale restante d'un achat est remboursée, l'achat annulé correspondant n'est pas associé à voidedQuantity, ce qui indique que l'achat a été entièrement remboursé. Par exemple, si un achat de quantité 10 est remboursé trois fois avec les quantités 2, 3 et 5, trois achats seront annulés. Les deux premiers achats annulés auront un voidedQuantity de 2 et 3, tandis que le troisième achat annulé n'aura pas de voidedQuantity.

La réponse est une chaîne JSON qui contient une liste des achats annulés. Si le nombre de résultats est supérieur au nombre spécifié dans le paramètre de requête maxResults, la réponse inclut une valeur nextPageToken, que vous pouvez transmettre dans une requête ultérieure pour afficher plus de résultats. Le premier résultat de la liste indique le plus ancien achat annulé.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

Quotas

L'API Voided Purchases définit les quotas suivants par package:

• 6 000 requêtes par jour. (Une journée commence et se termine à minuit, heure du Pacifique.)
• 30 requêtes en 30 secondes

Consignes pour les demandes initiales

Lors de votre requête API initiale, vous pouvez récupérer toutes les données disponibles pour votre application. Bien que peu probable, ce processus peut épuiser votre quota quotidien. Pour obtenir les données sur les achats annulés de manière plus sûre et plus cohérente, suivez ces bonnes pratiques:

• Utilisez la valeur par défaut pour le paramètre maxResults. Ainsi, si vous utilisez l'intégralité de votre quota de requêtes pendant une journée, vous pouvez récupérer les détails de 6 000 000 achats annulés.
• Si une réponse inclut une valeur pour nextPageToken, attribuez cette valeur au paramètre token lors de votre prochaine requête.

Bonnes pratiques

Remarque :En plus d'utiliser cette API, les développeurs doivent intégrer les notifications en temps réel pour les développeurs (RTDN). Avec les notifications RTDN, vous recevez des notifications de Google en cas de modification des droits d'accès d'un utilisateur dans votre application, y compris lorsqu'un utilisateur annule un achat.

Lorsque vous utilisez cette API dans votre application, n'oubliez pas qu'il existe de nombreuses raisons d'annuler un achat et qu'il n'existe pas de solution unique qui fonctionne dans tous les cas. Gardez vos utilisateurs à l'esprit lorsque vous concevez vos stratégies et stratégies de révocation. Pour ce faire, appliquez les pratiques recommandées suivantes:

• Utilisez cette API comme l'un des nombreux éléments d'une stratégie complète visant à remédier aux comportements indésirables. Révoquer l'accès aux produits intégrés est généralement plus efficace lorsqu'elle est associée à une application proposant des prix raisonnables pour les achats via l'application, une conception d'application qui décourage les comportements indésirables, une forte base d'utilisateurs dont la culture rejette un tel comportement, et des canaux d'assistance réactifs et efficaces.
• Administrez votre règle de révocation de manière uniforme pour assurer l'impartialité de tous les utilisateurs.
• Envisagez de créer une règle par étapes pour gérer les comportements indésirables. Par exemple, commencez par des avertissements dans l'application pour les infractions précoces, puis faites remonter vos réponses au fur et à mesure que le comportement indésirable d'un utilisateur continue. En dernier recours, vous pouvez empêcher un utilisateur d'interagir avec votre application.
• Lorsque vous introduisez une règle de révocation et que vous la mettez à jour, utilisez les canaux de communication de votre application pour informer les utilisateurs des modifications. Donnez à vos utilisateurs le temps de bien comprendre ces modifications avant qu'elles ne soient appliquées dans votre application.
• Soyez transparent vis-à-vis de vos utilisateurs et informez-les chaque fois que vous prenez des mesures (par exemple, révoquer leur accès à un produit intégré). Idéalement, les utilisateurs doivent pouvoir contester vos décisions, et ces contestations doivent être traitées de manière équitable.
• Surveillez les formulaires de commentaires et les forums de la communauté pour comprendre ce qui pousse les utilisateurs à se comporter de manière indésirable et la façon dont ils exercent un tel comportement. Agissez sur ces informations comme première ligne de défense.