public abstract class Purchase

  1. Object
  2. Purchase

Represents the status of in-app-purchase goods, this class provides information about products purchased by a user as well as the ability to purchase additional products. There are generally two types of payment systems: Manual and managed. In manual payments we pay a specific amount in a specific currency while with managed payment systems we work against a product catalog defined in the server.

In-app-purchase API’s rely on managed server based products, other payment systems use the manual approach. An application dealing with virtual goods must support both since not all devices feature in-app-purchase API’s. An application dealing with physical goods & services must use the latter according to the TOS of current in-app-purchase solutions.

Constructors

public Purchase()

Methods

public static void postReceipt(String storeCode, String sku, String transactionId, long datePurchased, String orderData)Deprecated Posts a receipt to be added to the receipt store.
public static Purchase getInAppPurchase()Returns the native OS purchase implementation if applicable, if unavailable this method will try to fallback to a custom purchase implementation and failing that will return null
public static Purchase getInAppPurchase(boolean d)Deprecated
protected final ReceiptStore getReceiptStore()
public final void setReceiptStore(ReceiptStore store)Installs a given receipt store to handle receipt management
public final List<Receipt> getReceipts()Gets all of the receipts for this app.
public final Receipt[] getReceipts(String... skus)Gets all of the receipts for the specified skus.
public boolean isManualPaymentSupported()Indicates whether the purchasing platform supports manual payments which are just payments of a specific amount of money.
public boolean isManagedPaymentSupported()Indicates whether the purchasing platform supports managed payments which work by picking products that are handled by the servers/OS of the platform vendor.
public String pay(double amount, String currency)Performs payment of a specific amount based on the manual payment API, notice that this doesn’t use the in-app-purchase functionality of the device!
public String pay(double amount, String currency, String invoiceNumber)Performs payment of a specific amount based on the manual payment API, notice that this doesn’t use the in-app-purchase functionality of the device!
public boolean isItemListingSupported()Indicates whether the payment platform supports things such as “item listing” or requires that items be coded into the system.
public Product[] getProducts(String[] skus)Returns the product list for the given SKU array
public boolean wasPurchased(String sku)Returns true if the given SKU was purchased in the past, notice this method might not work as expected for Unmanaged/consumable products which can be purchased multiple times.
public void purchase(String sku)Begins the purchase process for the given SKU
protected void purchaseImpl(String sku)Platform hook for purchase(String).
public void purchase(String sku, PromotionalOffer promotionalOffer)Begins the purchase process for the given SKU using a provided promotional offer.
protected void purchaseImpl(String sku, PromotionalOffer promotionalOffer)Platform hook for purchase(String, PromotionalOffer).
public void subscribe(String sku)Begins subscribe process for the given subscription SKU
public void subscribe(String sku, PromotionalOffer promotionalOffer)Begins subscribe process for the given subscription SKU using a provided promotional offer.
public void unsubscribe(String sku)Cancels the subscription to a given SKU
public List<Receipt> getPendingPurchases()Gets a list of purchases that haven’t yet been sent to the server.
public final void synchronizeReceipts()
public final void synchronizeReceipts(long ifOlderThanMs, SuccessCallback<Boolean> callback)Synchronize with receipt store.
public final boolean synchronizeReceiptsSync(long ifOlderThanMs)Synchronize receipts and wait for the sync to complete before proceeding.
public final Date getExpiryDate(String... skus)Gets the expiry date for a set of skus.
public final boolean isSubscribed(String... skus)Checks to see if the user is currently subscribed to any of the given skus.
public Receipt getFirstReceiptExpiringAfter(Date dt, String... skus)Gets the first receipt that expires after the specified date for the provided skus.
public boolean isRefundable(String sku)Indicates whether refunding is possible when the SKU is purchased
public void refund(String sku)Tries to refund the given SKU if applicable in the current market/product
public boolean isSubscriptionSupported()Returns true if the subscription API is supported in this platform
public boolean isUnsubscribeSupported()Deprecated Some platforms support subscribing but don’t support unsubscribe
public boolean isRestoreSupported()Indicates whether a purchase restore button is supported by the OS
public void restore()Restores purchases if applicable, this will only work if isRestoreSupported() returns true
public boolean isManageSubscriptionsSupported()Checks to see if this platform supports the #manageSubscriptions(java.lang.String) method.
public void manageSubscriptions(String sku)Open the platform’s UI for managing subscriptions.
public String getStoreCode()Returns the store code associated with this in-app purchase object.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Constructor details

Purchase

public Purchase()

Method details

postReceipt

public static void postReceipt(String storeCode, String sku, String transactionId, long datePurchased, String orderData)
Deprecated. For internal implementation use only.
Posts a receipt to be added to the receipt store.

Parameters

storeCode String
Not documented.
sku String
The sku of the product
transactionId String
The transaction ID
datePurchased long
The date of the purchase.
orderData String
Not documented.

getInAppPurchase

public static Purchase getInAppPurchase()
Returns the native OS purchase implementation if applicable, if unavailable this method will try to fallback to a custom purchase implementation and failing that will return null

Returns

instance of the purchase class or null

getInAppPurchase

public static Purchase getInAppPurchase(boolean d)
Deprecated. use the version that takes no arguments

getReceiptStore

protected final ReceiptStore getReceiptStore()

setReceiptStore

public final void setReceiptStore(ReceiptStore store)
Installs a given receipt store to handle receipt management

getReceipts

public final List<Receipt> getReceipts()
Gets all of the receipts for this app. Note: You should periodically reload the receipts from the server to make sure that the user hasn’t canceled a receipt or renewed one.

Returns

List of receipts for purchases this app.

getReceipts

public final Receipt[] getReceipts(String... skus)
Gets all of the receipts for the specified skus.

Parameters

skus String...
The skus for which to get receipts.

Returns

All receipts for the given skus.

isManualPaymentSupported

public boolean isManualPaymentSupported()
Indicates whether the purchasing platform supports manual payments which are just payments of a specific amount of money.

Returns

true if manual payments are supported

isManagedPaymentSupported

public boolean isManagedPaymentSupported()
Indicates whether the purchasing platform supports managed payments which work by picking products that are handled by the servers/OS of the platform vendor.

Returns

true if managed payments are supported

pay

public String pay(double amount, String currency)
Performs payment of a specific amount based on the manual payment API, notice that this doesn’t use the in-app-purchase functionality of the device!

Parameters

amount double
the amount to pay
currency String
the three letter currency type

Returns

a token representing the pending transaction which will be matched when receiving a callback from the platform or a null if the payment has failed or was canceled

Throws

RuntimeException
This method is a part of the manual payments API and will fail if isManualPaymentSupported() returns false

pay

public String pay(double amount, String currency, String invoiceNumber)
Performs payment of a specific amount based on the manual payment API, notice that this doesn’t use the in-app-purchase functionality of the device!

Parameters

amount double
the amount to pay
currency String
the three letter currency type
invoiceNumber String
application specific invoice number

Returns

a token representing the pending transaction which will be matched when receiving a callback from the platform or a null if the payment has failed or was canceled

Throws

RuntimeException
This method is a part of the manual payments API and will fail if isManualPaymentSupported() returns false

isItemListingSupported

public boolean isItemListingSupported()
Indicates whether the payment platform supports things such as “item listing” or requires that items be coded into the system. iOS provides listing and pricing where Android expects developers to redirect into the Play application for application details.

Returns

true if the OS supports this behavior

getProducts

public Product[] getProducts(String[] skus)
Returns the product list for the given SKU array

Parameters

skus String[]
the ids for the specific products

Returns

the product instances

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false
RuntimeException
This method works only if isItemListingSupported() returns true

wasPurchased

public boolean wasPurchased(String sku)
Returns true if the given SKU was purchased in the past, notice this method might not work as expected for Unmanaged/consumable products which can be purchased multiple times. In addition, this will only return true if the product was purchased (or has been restored) on the current device.

Parameters

sku String
the id of the product

Returns

true if the product was purchased

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

purchase

public void purchase(String sku)

Begins the purchase process for the given SKU

On Android you must use #subscribe(java.lang.String) for play store subscription products instead of this method. You cannot use #purchase(java.lang.String). On iOS there is no difference between #subscribe(java.lang.String) and #purchase(java.lang.String), so if you are simulating subscriptions on iOS using auto-renewables, you are better to use #subscribe(java.lang.String) as this will work correctly on both Android and iOS.

Parameters

sku String
the SKU with which to perform the purchase process

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

purchaseImpl

protected void purchaseImpl(String sku)
Platform hook for purchase(String). Native implementations override this to begin the store transaction; the public purchase method wraps it so the purchase_initiated analytics event fires uniformly across platforms.

Parameters

sku String
the SKU with which to perform the purchase process

purchase

public void purchase(String sku, PromotionalOffer promotionalOffer)

Begins the purchase process for the given SKU using a provided promotional offer.

Promotional offers are currently only supported on iOS. See Apple’s documentation

Parameters

sku String
the SKU with which to perform the purchase process
promotionalOffer PromotionalOffer
The promotional offer.

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

See also

purchaseImpl

protected void purchaseImpl(String sku, PromotionalOffer promotionalOffer)
Platform hook for purchase(String, PromotionalOffer). See purchaseImpl(String).

Parameters

sku String
the SKU with which to perform the purchase process
promotionalOffer PromotionalOffer
the promotional offer

subscribe

public void subscribe(String sku)

Begins subscribe process for the given subscription SKU

On Android you must use this method for play store subscription products. You cannot use #purchase(java.lang.String). On iOS there is no difference between #subscribe(java.lang.String) and #purchase(java.lang.String), so if you are simulating subscriptions on iOS using auto-renewables, you are better to use #subscribe(java.lang.String) as this will work correctly on both Android and iOS.

Parameters

sku String
the SKU with which to perform the purchase process

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

subscribe

public void subscribe(String sku, PromotionalOffer promotionalOffer)

Begins subscribe process for the given subscription SKU using a provided promotional offer.

Promotional offers are currently only supported on iOS. See Apple’s documentation

Parameters

sku String
the SKU with which to perform the purchase process
promotionalOffer PromotionalOffer
The promotional offer.

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

See also

unsubscribe

public void unsubscribe(String sku)
Cancels the subscription to a given SKU

Parameters

sku String
the SKU with which to perform the purchase process

Throws

RuntimeException
This method is a part of the managed payments API and will fail if isManagedPaymentSupported() returns false

getPendingPurchases

public List<Receipt> getPendingPurchases()
Gets a list of purchases that haven’t yet been sent to the server. You can use this for diagnostic and debugging purposes periodically in the app to make sure there aren’t a queue of purchases that aren’t getting submitted to the server.

Returns

List of receipts that haven’t been sent to the server.

synchronizeReceipts

public final void synchronizeReceipts()

synchronizeReceipts

public final void synchronizeReceipts(long ifOlderThanMs, SuccessCallback<Boolean> callback)
Synchronize with receipt store. This will try to submit any pending purchases to the receipt store, and then reload receipts from the receipt store

Parameters

ifOlderThanMs long
Only fetch receipts if they haven’t been fetched in ifOlderThanMs milliseconds.
callback SuccessCallback<Boolean>
Callback called when sync is done. Will be passed true if all pending purchases were successfully submitted to the receipt store AND receipts were successfully loaded.

synchronizeReceiptsSync

public final boolean synchronizeReceiptsSync(long ifOlderThanMs)
Synchronize receipts and wait for the sync to complete before proceeding.

Parameters

ifOlderThanMs long
Only re-fetch if it hasn’t been reloaded in this number of milliseconds.

Returns

True if the synchronization succeeds. False otherwise.

getExpiryDate

public final Date getExpiryDate(String... skus)
Gets the expiry date for a set of skus.

Parameters

skus String...
The skus to check. The latest expiry date of the set will be used.

Returns

The expiry date for a set of skus.

isSubscribed

public final boolean isSubscribed(String... skus)
Checks to see if the user is currently subscribed to any of the given skus. A user is deemed to be subscribed if #getExpiryDate(java.lang.String...) returns a date later than now.

Parameters

skus String...
Set of skus to check.

getFirstReceiptExpiringAfter

public Receipt getFirstReceiptExpiringAfter(Date dt, String... skus)
Gets the first receipt that expires after the specified date for the provided skus.

isRefundable

public boolean isRefundable(String sku)
Indicates whether refunding is possible when the SKU is purchased

Parameters

sku String
the sku

Returns

true if the SKU can be refunded

refund

public void refund(String sku)
Tries to refund the given SKU if applicable in the current market/product

Parameters

sku String
the id for the product

isSubscriptionSupported

public boolean isSubscriptionSupported()
Returns true if the subscription API is supported in this platform

Returns

true if the subscription API is supported in this platform

isUnsubscribeSupported

public boolean isUnsubscribeSupported()
Deprecated. use #isManageSubscriptionsSupported() instead
Some platforms support subscribing but don’t support unsubscribe

Returns

true if the subscription API allows for unsubscribe

isRestoreSupported

public boolean isRestoreSupported()
Indicates whether a purchase restore button is supported by the OS

Returns

true if you can invoke the restore method

restore

public void restore()
Restores purchases if applicable, this will only work if isRestoreSupported() returns true

isManageSubscriptionsSupported

public boolean isManageSubscriptionsSupported()
Checks to see if this platform supports the #manageSubscriptions(java.lang.String) method.

Returns

True if the platform supports the #manageSubscriptions(java.lang.String) method.

manageSubscriptions

public void manageSubscriptions(String sku)
Open the platform’s UI for managing subscriptions. Currently iOS and Android are the only platforms that support this. Other platforms will simply display a dialog stating that it doesn’t support this feature. Use the #isManageSubscriptionsSupported() method to check if the platform supports this feature.

Parameters

sku String
Optional sku of product whose subscription you wish to manage. If left null, then the general subscription management UI will be opened. iOS doesn’t support “deep-linking” directly to the management for a particular sku, so this parameter is ignored there. If included on Android, howerver, it will open the UI for managing the specified sku.

getStoreCode

public String getStoreCode()
Returns the store code associated with this in-app purchase object.

Returns

The store code. One of Receipt#STORE_CODE_ITUNES, Receipt#STORE_CODE_PLAY, Receipt#STORE_CODE_SIMULATOR, or Receipt#STORE_CODE_WINDOWS.