net.rimlib.blackberry.api.paymentsdk
Class PaymentEngine

java.lang.Object
  net.rimlib.blackberry.api.paymentsdk.PaymentEngine

public final class PaymentEngine
extends java.lang.Object

API that permits BlackBerry device users to initiate the purchase of digital goods from within your application. For example, this API can be used to allow users to purchase additional levels in a gaming application, music from a radio application, or any other digital good that your application offers. The digital good being purchased must be registered in the Vendor Portal for BlackBerry App World and must be associated with the application from where the purchase option is offered. In order to purchase digital goods, users must have BlackBerry App World 3.0 or higher installed on their devices.

Some of the methods in this class (notably purchase(PurchaseArguments) and getExistingPurchases(boolean)) require user input and interaction with the Payment Service server, and can take a long time to complete. For this reason, if these methods are invoked from the application's event thread, a modal progress dialog is displayed and a separate thread is automatically initiated to handle the network connections and user interaction. If you want to retain control of the UI as your application awaits a response from the Payment Service server, you can invoke these methods on a separate thread.

Before you can invoke any of the methods in PaymentEngine, you must retrieve an instance of the class by invoking getInstance(). If the value of the object is null, in-app purchases are not currently available (occurs if BlackBerry App World 3.0 or higher is not installed). You might want to check to see if in-app purchases are available before you offer purchase options to your users.

Purchases are initiated via the purchase() method. The amount of time that elapses before a response is returned from the Payment Service server depends on how quickly the user completes the purchase process (which may include steps such as signing in with a BlackBerry ID account or setting up a preferred billing method). The purchase() method returns a Purchase object if the purchase attempt succeeds, or throws a PaymentException if the purchase attempt fails.

The purchase() method accepts a PurchaseArguments object as an argument, which contains the information required to send a purchase request to the Payment Service server. Only the ID or SKU of the digital good to be purchased is required in a PurchaseArguments object for a purchase to succeed. You do not have to provide both arguments, and all other arguments are optional. If both the ID and SKU are provided, the ID takes precedence, and the SKU is used only if the digital good could not be located on the Payment Service server based on the ID. See the PurchaseArgumentsBuilder class for definitions of the available purchase arguments and how they affect the purchase process.

If an application requires a list of its digital goods that have already been purchased by the user (for example, to avoid offering users purchase options for digital goods they previously purchased), such a list can be retrieved by invoking the getExistingPurchases() method. This method can require some of the the same user interactions as purchase(), so it can also be a long-running method.

Testing

Testing against the live Payment Server server is unavailable until after you submit descriptions of your application and the digital goods within your application in the Vendor portal for BlackBerry App World. Until that point, the Payment Service server is unable to recognize the ID or SKU for a digital good when it receives a purchase request from an application.

To test the end-to-end purchase flow without being charged money, you can set up a BlackBerry ID as a test account. The test account allows you to download any applications or digital goods that are associated with your BlackBerry App World vendor account without incurring any costs. Local testing must be turned off for this type of testing, otherwise no network connections will be attempted.

For more information about developing or testing an in-app purchase solution, see the Payment Service SDK Development Guide.

See Also:

Purchase, PurchaseArguments, PurchaseArgumentsBuilder

Field Summary

static int	VERSION_CODE A variable to track releases of the SDK
static java.lang.String	VERSION_NAME A variable to track the version of this SDK

Method Summary

Result	cancel(java.lang.String transactionID) Initiates a request to cancel the virtual good given it's TransactionID.
boolean	checkExisting(java.lang.String sku) Returns true if the logged in BBID user has rights for this SKU at the time of calling this method.
Purchase	get(java.lang.String sku) Returns a Purchase object if the logged in BBID user has rights for this SKU at the time of calling this method.
ExistingPurchasesResult	getExistingPurchases(boolean allowRefresh) Retrieves a record of the previous successful purchases made by the user from within the calling application.
static PaymentEngine	getInstance() Retrieves an instance of the PaymentEngine class, or null if the BlackBerry device does not have BlackBerry App World 3.0 or higher installed.
PriceSet	getPrice(java.lang.String sku) Initiates a request for the price of a digital good.
static void	isAppWorldInstalledAndAtCorrectVersion() Provides a method to check if a version of AppWorld that supports this version of the PS SDK is installed.
PurchaseResult	purchase(PurchaseArguments arguments) Initiates the purchase of a digital good.
static void	upDateAppWorld() Starts the process of upgrading App World to the current version by opening the browser on the device to the AppWorld upgrade page.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION_NAME

public static final java.lang.String VERSION_NAME

A variable to track the version of this SDK

See Also:

Constant Field Values

VERSION_CODE

public static final int VERSION_CODE

A variable to track releases of the SDK

See Also:

Constant Field Values

Method Detail

getInstance

public static PaymentEngine getInstance()

Retrieves an instance of the PaymentEngine class, or null if the BlackBerry device does not have BlackBerry App World 3.0 or higher installed.

Returns:

An instance of PaymentEngine or null.

upDateAppWorld

public static void upDateAppWorld()

Starts the process of upgrading App World to the current version by opening the browser on the device to the AppWorld upgrade page. PS SDK 1.5 requires AppWorld 3.0 or greater.

Since:

version 1.5

isAppWorldInstalledAndAtCorrectVersion

public static void isAppWorldInstalledAndAtCorrectVersion()
                                                   throws AppWorldUpdateRequired

Provides a method to check if a version of AppWorld that supports this version of the PS SDK is installed. This may be useful to a developer that wants to make sure their users will have the correct version of AW before they try and initiate an in app purchase. Note: PS SDK 1.5 requires AppWorld 3.0 or greater.

Throws:

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

Since:

version 1.5

purchase

public PurchaseResult purchase(PurchaseArguments arguments)
                        throws AppWorldUpdateRequired,
                               java.lang.IllegalArgumentException,
                               PaymentException

Initiates the purchase of a digital good. Purchases can be initiated by using either the ID or the SKU of the digital good to be purchased, but it is not necessary to provide both. If customization of the name or icon for the digital good is desired, they can be provided with the PurchaseArguments.

Parameters:

arguments - Contains information about the digital good to be purchased.

Returns:

A Purchase object containing information about the successful purchase.

Throws:

java.lang.IllegalArgumentException - if both the ID and SKU are null or zero-length.

IllegalApplicationException - if the purchase failed because it was initiated by an application that was not installed via BlackBerry App World.

DigitalGoodNotFoundException - if the purchase failed because a record of the digital good was not found on the Payment Service server.

UserCancelException - if the purchase failed because it was canceled by the user.

PaymentServerException - if the purchase failed because of a problem with the Payment Service server.

PaymentException - if the purchase failed because of an unknown reason.

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

getPrice

public PriceSet getPrice(java.lang.String sku)
                  throws AppWorldUpdateRequired,
                         java.lang.IllegalArgumentException,
                         PaymentException

Initiates a request for the price of a digital good. The request can be initiated by using either the ID or the SKU of the digital good to be purchased, but it is not necessary to provide both.

Parameters:

arguments - Contains information about the digital good to be purchased.

Returns:

PriceSet containing the localized formated price of the good or a set of items for a subscription. See the item for more information.

Throws:

java.lang.IllegalArgumentException - if both the ID and SKU are null or zero-length.

IllegalApplicationException - if the purchase failed because it was initiated by an application that was not installed via BlackBerry App World.

DigitalGoodNotFoundException - if the purchase failed because a record of the digital good was not found on the Payment Service server.

UserCancelException - if the purchase failed because it was canceled by the user.

PaymentServerException - if the purchase failed because of a problem with the Payment Service server.

PaymentException - if the purchase failed because of an unknown reason.

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

Since:

version 1.5

cancel

public Result cancel(java.lang.String transactionID)
              throws java.lang.Exception,
                     AppWorldUpdateRequired

Initiates a request to cancel the virtual good given it's TransactionID. The vendor should guarantee it is a subscription good that can be canceled.

Parameters:

arguments - Contains a string identifying the digital good by transactionID.

SKU - of PurchaseToBeCanceled

Returns:

Result containing information on the status of the call.

Throws:

java.lang.Exception

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

Since:

version 1.5

getExistingPurchases

public ExistingPurchasesResult getExistingPurchases(boolean allowRefresh)
                                             throws AppWorldUpdateRequired,
                                                    PaymentException

Retrieves a record of the previous successful purchases made by the user from within the calling application. If allowRefresh is true, the list of existing purchases is retrieved from the Payment Service server, which has the potential to be a long running operation. If speed is of a higher importance than accuracy and/or user interaction is not desired (for example, in cases where this method is being executed by a background thread), you can set allowRefresh to false to have this method immediately return the purchase results cached on the BlackBerry device (possibly an empty list) without querying the Payment Service server.

Parameters:

allowRefresh - True if the application should refresh the list of purchases from the Payment Service server. False if the application should only retrieve the purchases cached on the device.

Returns:

The existing purchases.

Throws:

IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed via BlackBerry App World.

UserCancelException - if the purchase retrieval failed because it was canceled by the user.

PaymentServerException - if the purchase retrieval failed because of a problem with the Payment Service server.

PaymentException - if the purchase retrieval failed because of an unknown reason.

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

checkExisting

public boolean checkExisting(java.lang.String sku)
                      throws AppWorldUpdateRequired,
                             PaymentException

Returns true if the logged in BBID user has rights for this SKU at the time of calling this method. The result will be based on the default business rules defined by the PS Server / AppWorld. For example: In the case of a subscription a "Canceled" subscription will return true till the next renewal date. All "Refunded" SKUs will return false immediately.

Returns:

true or false.

Throws:

IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed via BlackBerry App World and not otherwise permitted to run without being downloaded from AppWold

UserCancelException - if the purchase retrieval failed because it was canceled by the user.

PaymentServerException - if the purchase retrieval failed because of a problem with the Payment Service server.

PaymentException - if the purchase retrieval failed because of an unknown reason.

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

Since:

version 1.5

get

public Purchase get(java.lang.String sku)
             throws AppWorldUpdateRequired,
                    PaymentException

Returns a Purchase object if the logged in BBID user has rights for this SKU at the time of calling this method. The result will be based on the default business rules defined by the PS Server / AppWorld. For example: In the case of a subscription a "Canceled" subscription will return true till the next renewal date. All "Refunded" SKUs will return false immediately.

Returns:

Purchase.

Throws:

IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed via BlackBerry App World and not otherwise permitted to run without being downloaded from AppWold

UserCancelException - if the purchase retrieval failed because it was canceled by the user.

PaymentServerException - if the purchase retrieval failed because of a problem with the Payment Service server.

PaymentException - if the purchase retrieval failed because of an unknown reason.

AppWorldUpdateRequired - if the a version of App World that supports PS SDK 1.5 is not installed on the device

Since:

version 1.5