# 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
  Description
  `Purchase()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final 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

  `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
  `final List<Receipt>`
  `getReceipts()`
  Gets all of the receipts for this app.
  `final Receipt[]`
  `getReceipts(String... skus)`
  Gets all of the receipts for the specified skus.
  `protected final 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
  `final 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()`
  Some platforms support subscribing but don't support unsubscribe
  `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)`
  Posts a receipt to be added to the receipt store.
  `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.
  `protected void`
  `purchaseImpl(String sku)`
  Platform hook for `purchase(String)`.
  `protected void`
  `purchaseImpl(String sku, PromotionalOffer promotionalOffer)`
  Platform hook for `purchase(String, PromotionalOffer)`.
  `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
  `final 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.
  `final void`
  `synchronizeReceipts()`
  `final void`
  `synchronizeReceipts(long ifOlderThanMs, SuccessCallback<Boolean> callback)`
  Synchronize with receipt store.
  `final 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 Object

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

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

  - ### 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`: 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`: 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

  - ### purchaseImpl

    protected void purchaseImpl(String sku, PromotionalOffer promotionalOffer)

    Platform hook for `purchase(String, PromotionalOffer)`. See `purchaseImpl(String)`.

    ###### Parameters

    - `sku`: the SKU with which to perform the purchase process

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

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

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