com.codename1.payment

Class Purchase

java.lang.Object

com.codename1.payment.Purchase

public abstract class Purchase
extends Object

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.

Constructor Summary

Constructors

Constructor and Description
Purchase()

Method Summary

Modifier and Type	Method and Description
Date	getExpiryDate(String... skus) Gets the expiry date for a set of skus.
Receipt	getFirstReceiptExpiringAfter(Date dt, String... skus) Gets the first receipt that expires after the specified date for the provided skus.
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
static Purchase	getInAppPurchase(boolean d) Deprecated. use the version that takes no arguments
List<Receipt>	getPendingPurchases() Gets a list of purchases that haven't yet been sent to the server.
Product[]	getProducts(String[] skus) Returns the product list for the given SKU array
List<Receipt>	getReceipts() Gets all of the receipts for this app.
Receipt[]	getReceipts(String... skus) Gets all of the receipts for the specified skus.
protected ReceiptStore	getReceiptStore()
String	getStoreCode() Returns the store code associated with this in-app purchase object.
boolean	isItemListingSupported() Indicates whether the payment platform supports things such as "item listing" or requires that items be coded into the system.
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.
boolean	isManageSubscriptionsSupported() Checks to see if this platform supports the manageSubscriptions(java.lang.String) method.
boolean	isManualPaymentSupported() Indicates whether the purchasing platform supports manual payments which are just payments of a specific amount of money.
boolean	isRefundable(String sku) Indicates whether refunding is possible when the SKU is purchased
boolean	isRestoreSupported() Indicates whether a purchase restore button is supported by the OS
boolean	isSubscribed(String... skus) Checks to see if the user is currently subscribed to any of the given skus.
boolean	isSubscriptionSupported() Returns true if the subscription API is supported in this platform
boolean	isUnsubscribeSupported() Deprecated. use isManageSubscriptionsSupported() instead
void	manageSubscriptions(String sku) Open the platform's UI for managing subscriptions.
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!
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!
static void	postReceipt(String storeCode, String sku, String transactionId, long datePurchased, String orderData) Deprecated. For internal implementation use only.
void	purchase(String sku) Begins the purchase process for the given SKU
void	purchase(String sku, PromotionalOffer promotionalOffer) Begins the purchase process for the given SKU using a provided promotional offer.
void	refund(String sku) Tries to refund the given SKU if applicable in the current market/product
void	restore() Restores purchases if applicable, this will only work if isRestoreSupported() returns true
void	setReceiptStore(ReceiptStore store) Installs a given receipt store to handle receipt management
void	subscribe(String sku) Begins subscribe process for the given subscription SKU
void	subscribe(String sku, PromotionalOffer promotionalOffer) Begins subscribe process for the given subscription SKU using a provided promotional offer.
void	synchronizeReceipts()
void	synchronizeReceipts(long ifOlderThanMs, SuccessCallback<Boolean> callback) Synchronize with receipt store.
boolean	synchronizeReceiptsSync(long ifOlderThanMs) Synchronize receipts and wait for the sync to complete before proceeding.
void	unsubscribe(String sku) Cancels the subscription to a given SKU
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

Purchase

public Purchase()

Method Detail

setReceiptStore

public final void setReceiptStore(ReceiptStore store)

Installs a given receipt store to handle receipt management

Parameters:

store -

getReceiptStore

protected final ReceiptStore getReceiptStore()

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 - 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 - the amount to pay

currency - 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 - the amount to pay

currency - the three letter currency type

invoiceNumber - 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:

sku - 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 - 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 - 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

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 - the SKU with which to perform the purchase process

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:

ApplePromotionalOffer

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 - 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 - the SKU with which to perform the purchase process

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:

ApplePromotionalOffer

unsubscribe

public void unsubscribe(String sku)

Cancels the subscription to a given SKU

Parameters:

sku - 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 - Only fetch receipts if they haven't been fetched in ifOlderThanMs milliseconds.

callback - 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.

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:

sku - The sku of the product

transactionId - The transaction ID

datePurchased - The date of the purchase.

synchronizeReceiptsSync

public final boolean synchronizeReceiptsSync(long ifOlderThanMs)

Synchronize receipts and wait for the sync to complete before proceeding.

Parameters:

ifOlderThanMs - 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 - 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 - Set of skus to check.

Returns:

getFirstReceiptExpiringAfter

public Receipt getFirstReceiptExpiringAfter(Date dt,
                                            String... skus)

Gets the first receipt that expires after the specified date for the provided skus.

Parameters:

dt -

skus -

Returns:

isRefundable

public boolean isRefundable(String sku)

Indicates whether refunding is possible when the SKU is purchased

Parameters:

sku - 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 - the id for the product

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

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.

Since:

6.0

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 - 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.

Since:

6.0

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.

Since:

8.0