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 Details

    • Purchase

      public Purchase()

  • Method Details

    • postReceipt

      public static void postReceipt(String storeCode, String sku, String transactionId, long datePurchased, String orderData)

      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.

      Deprecated

      For internal implementation use only.

    • 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

      Parameters
      • store

    • 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
      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: @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
      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: @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: the ids for the specific products
      Returns

      the product instances

      Throws

      • RuntimeException: @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: @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: @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: @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: @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: @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: @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: @param 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.

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

    • 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

    • 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

    • 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()

      Some platforms support subscribing but don't support unsubscribe

      Returns

      true if the subscription API allows for unsubscribe

      Deprecated

      use #isManageSubscriptionsSupported() instead

    • 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: @param 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
      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