net.rimlib.blackberry.api.paymentsdk
Class PaymentEngine

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

public final class PaymentEngine
extends java.lang.Object

This API lets BlackBerry device users purchase digital goods from within your application. For example, you can use this API 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.1 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 (this happens if BlackBerry App World 3.1 or higher is not installed). You might want to check whether in-app purchases are available before you offer purchase options to your users.

Purchases are initiated using 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 same user interactions as purchase(), so it can also be a long-running method.

Testing

Testing against the live Payment Service 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 then, 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 java.lang.String	APP_WORLD_VERSION_FOUND
static boolean	DEBUGFLAG_SKIP_APPWORLD_CHECK For development only, when set to true no check is done for App World.
static java.lang.String	MINIMUM_REQUIRED_APP_WORLD_VERSION Minimum required App World version.
static int	VERSION_CODE A variable to track releases of the Payment Service SDK.
static java.lang.String	VERSION_NAME A variable to track the version of the Payment Service SDK

Method Summary

Result	cancel(java.lang.String transactionID) Initiates a request to cancel the purchase of the digital good using its TransactionID.
boolean	checkExisting(java.lang.String sku) Returns true if the logged in BlackBerry ID user has rights for this SKU at the time this method is called.
Purchase	get(java.lang.String sku) Returns a Purchase object if the current BlackBerry ID user has rights for this SKU at the time this method is called.
ExistingPurchasesResult	getExistingPurchases(boolean allowRefresh) Deprecated. Use PurchaseHistory#get(PurchaseHistoryListingListener) instead.
static PaymentEngine	getInstance() Retrieves an instance of the PaymentEngine class
PriceSet	getPrice(java.lang.String sku) Initiates a request for the price of a digital good.
static void	isAppWorldInstalledAndAtCorrectVersion() Provides a method to check whether a version of AppWorld that supports this version of the Payment Service SDK is installed.
static void	isPaymentServicesAvailable(PaymentEngineListener listener) Checks whether the Payment daemon 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 the Payment Service SDK

See Also:

Constant Field Values

VERSION_CODE

public static final int VERSION_CODE

A variable to track releases of the Payment Service SDK. For example "3" means that this is the 3rd public release.

See Also:

Constant Field Values

DEBUGFLAG_SKIP_APPWORLD_CHECK

public static boolean DEBUGFLAG_SKIP_APPWORLD_CHECK

For development only, when set to true no check is done for App World.

MINIMUM_REQUIRED_APP_WORLD_VERSION

public static final java.lang.String MINIMUM_REQUIRED_APP_WORLD_VERSION

Minimum required App World version.

See Also:

Constant Field Values

APP_WORLD_VERSION_FOUND

public static java.lang.String APP_WORLD_VERSION_FOUND

Method Detail

getInstance

public static PaymentEngine getInstance()

Retrieves an instance of the PaymentEngine class

Returns:

An instance of PaymentEngine

isPaymentServicesAvailable

public static void isPaymentServicesAvailable(PaymentEngineListener listener)

Checks whether the Payment daemon is installed. This is an asynchronous call that returns results to the provided PaymentEngineListener. The reference to the PaymentEngineListener must be maintained by the calling application, as the daemon only holds a weak reference.

Parameters:

listener - the PaymentEngineListener for handling the asynchronous call back

Since:

Version 1.8.0

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. Payment Service SDK 1.8 requires AppWorld 3.1 or greater.

Since:

Version 1.5

isAppWorldInstalledAndAtCorrectVersion

public static void isAppWorldInstalledAndAtCorrectVersion()
                                                   throws AppWorldUpdateRequired

Provides a method to check whether a version of AppWorld that supports this version of the Payment Service SDK is installed. This may be useful to you to make sure users have the correct version of App World before they try and initiate an in-application purchase. Note: Payment Service SDK 1.8 requires AppWorld 3.1 or greater.

Throws:

AppWorldUpdateRequired - if the a version of App World that supports Payment Service SDK 1.8 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 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. Requires BlackBerry ID authentication.

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 using 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 a version of App World that supports the Payment Service SDK 1.8 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 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 formatted price of the digital 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 using 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 a version of App World that supports the Payment Service SDK 1.8 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 purchase of the digital good using its TransactionID. The vendor should guarantee it is a subscription good that can be canceled. Requires BlackBerry ID authentication.

Parameters:

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

Returns:

Result containing information on the status of the call.

Throws:

java.lang.Exception

AppWorldUpdateRequired - if a version of App World that supports the Payment Service SDK 1.8 is not installed on the device

Since:

Version 1.5

getExistingPurchases

public ExistingPurchasesResult getExistingPurchases(boolean allowRefresh)
                                             throws AppWorldUpdateRequired,
                                                    PaymentException

Deprecated. Use PurchaseHistory#get(PurchaseHistoryListingListener) instead.

Retrieves a record of the previous successful purchases made by the user from within the calling application. If the calling application is itself a subscription, this call can be used to retrieve the status of the user's subscription for 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. Requires BlackBerry ID authentication.

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 using 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 a version of App World that supports the Payment Service SDK 1.8 is not installed on the device

checkExisting

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

Returns true if the logged in BlackBerry ID user has rights for this SKU at the time this method is called. The result will be based on the default business rules defined by the Payment Server or App World. Will return true if the user has the right to the sku, false otherwise. For example, in the case of a subscription, a "Canceled" subscription will return true until the next renewal date. If subscription date has expired, the method returns false. All "Refunded" SKUs will return false. Requires BlackBerry ID authentication.

Returns:

true if the user has the right to the sku, false otherwise.

Throws:

IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed using 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 a version of App World that supports Payment Service SDK 1.8 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 current BlackBerry ID user has rights for this SKU at the time this method is called. The result will be based on the default business rules defined by the Payment Server or App World. For any cases where the user does not have the right to the SKU, it will return null. Requires BlackBerry ID authentication.

Returns:

Purchase for any SKU's that satisfy checkExisting(), null otherwise.

Throws:

IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed using 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 a version of App World that supports the Payment Service SDK 1.8 is not installed on the device

Since:

Version 1.5