In-App Voided Purchases Verification

Our service provides access to Voided Purchases, which include transactions that were canceled by the user or due to unexpected issues during payment processing. Correct integration of voided purchases helps provide users with up-to-date and accurate information about their purchases, ensuring a seamless experience.

This guide walks through the necessary steps for integrating voided purchases into your app and offers tips on handling them efficiently and securely.

Why Voided Purchases Matter

Handling voided purchases effectively improves the user experience by:

Preventing access to premium content after a purchase is voided (e.g., refunded, canceled).
Keeping the purchase records in sync between your app, backend, and the user's account.
Complying with store policies to avoid potential issues.

What are Voided Purchases?

Voided purchases refer to transactions that have been either refunded or charged back by Aptoide Connect or the user. These could include:

Refunds issued by Aptoide Connect.
Canceled subscriptions or in-app purchases.
Transactions affected by payment errors.

Voided Purchases Integration Guidelines

To correctly integrate voided purchases functionality, follow these best practices:

1. Backend API to Manage Voided Purchases

Implement a Backend API to manage the processed Voided Purchases for each User. This is critical to ensure that the Users do not get duplicate notifications or warnings about their Voided Purchases.

2. Notify Users of Voided Purchases

Display clear and friendly messages informing the user when a purchase has been voided. Avoid using technical terms and provide helpful context for the user.
Example message: "Your recent purchase was canceled, and access to premium features has been revoked."

3. Update Local and Backend Purchase Records

Mark any voided purchases as voided in the local database and your backend to avoid discrepancies in the purchase history.
Revoke access to any premium content, subscriptions, or features linked to voided purchases.
Make sure to update the purchase state both locally and on the server to avoid giving users access to premium content unintentionally.

4. Subscription-Specific Handling

For subscriptions, revoke access only after the subscription expiration date, not immediately upon void. This ensures users with legitimate, partially-used subscriptions are not penalized prematurely.

Implementation

In order to obtain the Voided Purchases of your application, follow these steps:

Request our service for the Voided Purchases.
1. Use correctly the query parameters provided to avoid receiving already processed data.
Link the Voided Purchase to the User using the orderId parameter from the VoidedPurchase model.
Notify the User about the status of the Voided Purchases received.

Moving on to the integration of the Voided Purchases service with your API.

1. Request Voided Purchases

This endpoint allows you to retrieve voided in-app purchases https://api.catappult.io/productv2/8.20241107/google/inapp/v3/applications/{packageName}/purchases/voidedpurchases

Path Parameters

Name	Type	Description	Mandatory	Example
packageName	String	The package name of your application.	Y	com.appcoins.diceroll.sdk

It has a few parameters that you can fill to improve the results.

Query Parameters

Name	Type	Description	Mandatory	Example
pageSelection.maxResults	Integer	The maximum number of voided purchases that appear in each response.	N	100
pageSelection.token	Integer	A continuation token from a previous response, allowing you to view more results.	N
type	Int	Type of the Voided Purchases you want to receive.	N	0
startTime	String	Time in milliseconds of the oldest Voided Purchase you want to receive.	N	1729247468
endTime	String	Time in milliseconds of the newest Voided Purchase you want to receive.	N	1729247468

type

Type of the Voided Purchases. Possible values are:

Value	Description
0	INAPP only (default) - By requesting this type, you will only receive the INAPP Voided Purchases.
1	INAPP & SUBS - By requesting this type, you will both INAPP and SUBS type of Voided Purchases.

Implementing the Voided Purchases request

import requests

package_name = "com.example.app"
void_purchases_url = f"https://api.catappult.io/productv2/8.20240101/google/inapp/v3/applications/{package_name}/purchases/voidedpurchases"
response = requests.get(void_purchases_url)
response = response.json()
for voided_purchase in response["voidedPurchases"]:
    order_id = voided_purchase["orderId"]
    print(f"Handling voided purchase with order id {order_id}")
    # Handle your voided purchase here

The format will look something like this :

{
  "pageInfo": {
    "resultPerPage": 15
  },
  "tokenPagination": {
    "nextPageToken": null,
    "previousPageToken": null
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "catappult.inapp.purchase.QQATJ76ESKXMTLKY",
      "purchaseTimeMillis": 1721167420119,
      "voidedTimeMillis": 1721340431555,
      "orderId": "WJTG2ID4TQJSYOQK",
      "voidedReason": 0
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "catappult.inapp.purchase.HS5FW5NZ5JBMV7E6",
      "purchaseTimeMillis": 1721190786352,
      "voidedTimeMillis": 1721363831842,
      "orderId": "F7KCIB3ZBYSFQIFY",
      "voidedReason": 0
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "catappult.inapp.purchase.DYMXIMA5OKRLUXBB",
      "purchaseTimeMillis": 1721229249199,
      "voidedTimeMillis": 1721402186518,
      "orderId": "AJLWNMYF7MKLDAMX",
      "voidedReason": 0
    },
  ]
}

For more information on the meaning and type of each field reference our VoidedPurchase documentation .

2. Handle the Voided Purchases received

Once received the result from the service, you can apply your custom business logic.