Notification types Payloads

Overview

In this page you can better understand the payload that each of the OneTimeProductNotification, SubscriptionNotification and VoidedPurchaseNotification can retrieve and how to deal with them.

OneTimeProductNotification

The OneTimeProductNotification contains the following payload:

{
  "version": String,
  "notificationType": Int,
  "purchaseToken": String,
  "sku": String
}

The parameters in this payload are described as the following:

Name	Type	Description
version	String	Version of the Payload received.
notificationType	Int	Type of notification received for the Non-Consumable Product Purchase. Possible values can be seen here.
purchaseToken	String	Purchase Token of the Non-Consumable Purchase. This is a unique value and should be used to obtain more information about the Purchase.
sku	String	The SKU of the Product in the Purchase.

NotificationType

Possible values of the notificationType are the following:

Value	Title	Description
1	COMPLETED	Inapp Purchase has been completed successfully.
2	CANCELED	Inapp Purchase has been canceled.

Processing the OneTimeProductNotification payload

When you receive a notification of the OneTimeProductNotification type, use the orderId parameter to obtain more information about the Purchase to which the Notification is related and then update your backend data with the information you have.

To obtain the Purchase data with orderId of a InApp type Product, use the following endpoint:

https://api.catappult.io/productv2/8.20241201/google/inapp/v3/applications/{packageName}/purchases/products/{sku}/tokens/{purchaseToken}

Which will retrieve the following data:

{
  "kind": String,
  "purchaseTimeMillis": String,
  "purchaseState": Int,
  "consumptionState": Int,
  "developerPayload": String,
  "orderId": String,
  "acknowledgementState": Int,
  "purchaseToken": String,
  "productId": String,
  "regionCode": String,
  "currency": String
}

The parameters in this payload are described as the following:

Name	Type	Description
kind	String	Type of purchase made.
purchaseTimeMillis	String	Purchase time in millies.
purchaseState	Int	State of the Purchase.
consumptionState	Int	State of the consumption.
developerPayload	String	String based payload specified by the Developer when initiating this Purchase.
orderId	String	The order UID (Unique Identifier) used internally in Aptoide.
acknowledgementState	Int	State of the acknowledgment.
purchaseToken	String	Purchase Token of the Inapp Purchase.
productId	String	The SKU of the Product in the Purchase.
regionCode	String	String value following the ISO-3166-1-A2 guidelines. Example: `US`
currency	String	The price currency, as an ISO 4217 alphabetic code. Example: `USD`

consumptionState

Value	Title	Description
0	Pending	Purchase is still not consumed.
1	Consumed	Purchase has been consumed.

acknowledgementState

Value	Title	Description
0	Pending	Purchase is still not acknowledged.
1	Acknowledged	Purchase has been acknowledged.

SubscriptionNotification

The SubscriptionNotification contains the following payload:

{
  "version": String,
  "notificationType": Int,
  "purchaseToken": String,
  "subscriptionId": String
}

The parameters in this payload are described as the following:

Name	Type	Description
version	String	Version of the Payload received.
notificationType	Int	Type of notification received for a Subscription Purchase. Possible values can be seen here.
purchaseToken	String	Purchase Token of the Subscription Purchase. This is a unique value and should be used to obtain more information about the Purchase.
subscriptionId	String	The SKU of the Product in the Purchase.

NotificationType

Possible values of the notificationType are the following:

Value	Title	Description
1	SUBSCRIPTION_RECOVERED	A subscription was successfully recovered from account hold.
2	SUBSCRIPTION_RENEWED	An active subscription was renewed successfully.
3	SUBSCRIPTION_CANCELED	A subscription was canceled, either voluntarily by the user or involuntarily. For voluntary cancellations, this notification is sent when the user initiates the cancellation.
4	SUBSCRIPTION_PURCHASED	A new subscription was purchased.
5	SUBSCRIPTION_ON_HOLD	A subscription has been placed on account hold (if this feature is enabled).
6	SUBSCRIPTION_IN_GRACE_PERIOD	A subscription has entered the grace period due to issues such as payment failure (if this feature is enabled).
7	SUBSCRIPTION_RESTARTED	A user has restored their subscription through AppCoins Wallet > Settings > Manage Subscriptions. The subscription had been canceled but was still within its validity period when restored.
12	SUBSCRIPTION_REVOKED	The subscription was revoked by the system before its expiration date.
13	SUBSCRIPTION_EXPIRED	The subscription has reached its expiration date and was not renewed.

Processing the SubscriptionNotification payload

When you receive a notification of the SubscriptionNotification type, use the orderId parameter to obtain more information about the Purchase to which the Notification is related and then update your backend data with the information you have.

To obtain the Purchase data with orderId of a Subscription type Product, use the following endpoint:

https://api.catappult.io/productv2/8.20241201/google/inapp/v3/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{purchaseToken}

Which will retrieve the following data:

{
  "kind": String,
  "startTimeMillis": String,
  "expiryTimeMillis": String,
  "autoRenewing": Boolean,
  "priceCurrencyCode": String,
  "priceAmountMicros": Long,
  "countryCode": String,
  "developerPayload": String,
  "paymentState": Int,
  "orderId": String,
  "acknowledgementState": Int
}

The parameters in this payload are described as the following:

Name	Type	Description
kind	String	Type of purchase made.
startTimeMillis	String	Start time of the Subscription in millies.
expiryTimeMillis	String	Expiry time of the Subscription in millies.
autoRenewing	Boolean	Specifies if the subscription will renew automatically. If set to true, the subscription remains active and is scheduled to renew on the upcoming billing date. If set to false, the subscription has been canceled, and access to content will end on the next billing date unless the user opts to restore automatic renewal or completes a manual renewal.
priceCurrencyCode	String	The price currency, as an ISO 4217 alphabetic code. Example: `USD`
priceAmountMicros	Long	The price in micro-units (millionths of the price currency). Example: `4990000` (for 4.99)
countryCode	String	String value following the ISO-3166-1-A2 guidelines. Example: `US`
developerPayload	String	String based payload specified by the Developer when initiating this Purchase.
paymentState	Int	State of the Payment.
orderId	String	The order UID (Unique Identifier) used internally in Aptoide.
acknowledgementState	Int	State of the acknowledgment.

paymentState

Value	Title	Description
0	Pending	Payment is still pending.
1	Received	Payment has been received.

acknowledgementState

Value	Title	Description
0	Pending	Purchase is still not acknowledged.
1	Acknowledged	Purchase is not acknowledged.

VoidedPurchaseNotification

The VoidedPurchaseNotification contains the following payload:

{
  "purchaseToken": String,
  "orderId": String,
  "productType": Int,
  "refundType": Int
}

The parameters in this payload are described as the following:

Name	Type	Description
purchaseToken	String	Purchase Token of the Voided Purchase. This is a unique value and should be used to obtain more information about the Purchase.
orderId	String	The order UID (Unique Identifier) used internally in Aptoide.
productType	Int	Type of the SKU in the Purchase that has been Voided.
refundType	Int	Type of notification received for the Voided Purchase. Possible values can be seen here .

productType

Possible values of the productType are the following:

Value	Title	Description
1	SUBS	A type of SKU for subscriptions.
2	INAPP	A type of SKU for in-app products.

refundType

Possible values for the refundType are the following:

Value	Title	Description
1	REFUND_TYPE_FULL_REFUND	Purchase has been totally refunded.
2	REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND	Purchase has been partially refunded.

Processing the VoidedPurchaseNotification payload

When you receive a notification of the VoidedPurchaseNotification type, use the orderId parameter to obtain more information about the Purchase that got Voided to which the Notification is related and then update your backend data with the information you have.

To obtain more information regarding the Voided Purchase itself, follow our guide about In-App Voided Purchases Integration.

FAQ

How to obtain more information about the Purchase?

To obtain more information about the Purchase you can use the In-App Purchase Details documentation page which includes our endpoints from which you can request additional data.