Entry point for purchasing digital goods.

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 registered on the Vendor Portal for BlackBerry App World. The digital good being purchased must be associated with the calling application in the Vendor Portal for BlackBerry App World.

Purchases are initiated via the purchase method. The amount of time that elapses before a response is returned depends on how quickly the user completes the purchase process (which may include steps such as signing in to their BlackBerry ID account and setting up their preferred billing method). The purchase method dispatches a callbackOnSuccess on success, or dispatches a callbackOnFailure on failure.

When calling the puchase method only the ID or SKU of the digital good to be purchased is required; it is not necessary to provide both, and all other arguments are optional. If both the ID and SKU are provided, then the ID takes precedence; the SKU is only used if the digital good could not be located on the Payment Service server based on the ID.

If an application requires a list of its digital goods that have already been purchased by the user (for example, to avoid offering for sale a digital good the user already owns), such a list can be obtained with the blackberry.payment.getExistingPurchases method. This method requires the same user interaction as the purchase method, so it can also be a long-running method.

Supported Platform(s)
- BlackBerry PlayBook
- Supported Platform Table: Expand
API OS 5.0 OS 6.0 OS 7.0 PlayBook
blackberry.payment.getExistingPurchases       Y
blackberry.payment.purchase       Y
blackberry.payment.developmentMode       Y

Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
Feature Elements
You must declare the feature element(s) below in your configuration document:
Feature ID OS 5.0 OS 6.0 OS 7.0 PlayBook
<feature id="blackberry.payment" />       Y

Permission Elements (PlayBook Only)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions


Properties

blackberry.payment.getExistingPurchases


static void getExistingPurchases([refresh: Boolean], callbackOnSuccess : function, [callbackOnFailure: function])

Supported Platform(s)
 - BlackBerry PlayBook

Description
 Retrieves the previous successful purchases made by the user from within the calling application.

Parameter Type Description
refresh Boolean
Optional
True if the BlackBerry should be allowed to refresh the list of purchases from the Payment Service server. False if the current list of cached purchases should be returned immediately.
callbackOnSuccess function(data : Purchase[]) Function to be invoked on successful call.

data: An array of purchases is passed as a parameter in the form below.
[{
"transactionID": "00000001",
"digitalGoodID": "123",
"date": "1234567891011",
"digitalGoodSKU": "SKU 1",
"licenseKey": null,
"metaData": ""
},
{
"transactionID": "00000002",
"digitalGoodID": "456",
"date": "1234567891011",
"digitalGoodSKU": "SKU 2",
"licenseKey": null,
"metaData": ""
}]
callbackOnFailure function(errorText : String, errorID : Number)
Optional
Function to be invoked when an error occurs.

errorText: Retrieves the message set for an error. In addition to descriptive text, error code may appear at the end of the message.
errorID: Contains the reference number associated with the specific error in corresponding to the following values.
  • User Cancelled = 1
  • Payment System Busy = 2
  • General Payment System Error = 3
  • Digital Good not Found = 4
Note: The actual values may be different when blackberry.payment.developmentMode equals true.

blackberry.payment.purchase


static void purchase(args : Object, callbackOnSuccess : function, [callbackOnFailure: function])

Supported Platform(s)
 - BlackBerry PlayBook

Description
 Initiates the purchase of a digital good.

Parameter Type Description
args Object Contains information that describes the purchase.

digitalGoodID: ID of the digital good being purchased.
digitalGoodSKU: SKU of the digital good being purchased.
digitalGoodName: Name of the digital good being purchased.
metaData: Metadata associated with the digital good. Metadata offers the application developer a way to store information about each purchase on the Payment Service server.
purchaseAppName: Name of the application requesting the purchase.
purchaseAppIcon: Icon of the application requesting the purchase.
callbackOnSuccess function(data : Purchase) Function to be called when the payment is successful.

data: An object representing a purchase is passed as a parameter in the form below.
callbackOnFailure function(error : Number)
Optional
Function to be called when an error occurs.

error: An error code will be passed in corresponding to the following codes
  • User Cancelled = 1
  • Payment System Busy = 2
  • General Payment System Error = 3
  • Digital Good not Found = 4

Code Example(s)
<script type="text/javascript">
  function pay() {
    try{
      blackberry.payment.purchase({
      "digitalGoodID":"123",
      "digitalGoodSKU":"someSKU",
      "digitalGoodName":"SomeName",
      "metaData":"metadata",
      "purchaseAppName":"WebWorks APP",
      "purchaseAppIcon":null},
      success,failure);
   }catch (e){
     alert ("Error" + e);
   }
 }

 function success(purchase) {
   alert ("success called:"+ JSON.stringify(purchase));
  }

 function failure(error) {
   alert ("failure called with error code:"+ error);
 }
</script>

Properties:


Property Type Description Supported Platform(s)
blackberry.payment.developmentMode Static
Boolean = false
Defines the development mode used in the application. If development mode is set to true, the application does not contact the Payment Service server for any transactions. For purchases, a simulated purchase screen is displayed, allowing the user to choose the result of the purchase. For retrieving existing purchases, only simulated successful purchases are returned. This mode is useful for testing how your application handles the possible results without requiring network connections or currency. THIS MODE SHOULD NOT BE USED IN PRODUCTION CODE. If development mode is set to false, purchases and retrievals of existing purchases proceed normally, contacting the Payment Service server as necessary. This is the default development mode, and applications in production should not modify it.
 - BlackBerry PlayBook

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Sep 14 2011 09:55:32 GMT-0000 (UTC)