Payment
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 purchase 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 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 OS 5.0+
- BlackBerry PlayBook
API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
getExistingPurchases | Y | Y | Y | Y | |
purchase | Y | Y | Y | Y | |
developmentMode | Y | Y | Y | 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:
You must declare the feature element(s) below in your configuration document:
Feature ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
<feature id="blackberry.payment" /> | Y | Y | Y | 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. |
getExistingPurchases
static void getExistingPurchases([refresh: Boolean], callbackOnSuccess : function, [callbackOnFailure: function]) |
Supported Platform(s)
- BlackBerry OS 5.0+- 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 : String) |
Function to be invoked on successful call.
data: A string representing a literal array of Purchase items is passed as a parameter in the form below: [{ "transactionID": "00000001", "digitalGoodID": "123", "date": "1234567891011", "digitalGoodSKU": "SKU_1", "licenseKey": null, "metaData": "My Metadata" }, { "transactionID": "00000002", "digitalGoodID": "456", "date": "1234567891011", "digitalGoodSKU": "SKU_2", "licenseKey": null, "metaData": "My 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.
|
purchase
static void purchase(args : Object, callbackOnSuccess : function, [callbackOnFailure: function]) |
Supported Platform(s)
- BlackBerry OS 5.0+- 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 : String) |
Function to be called when the payment is successful.
data: A string representing a Purchase object literal. |
callbackOnFailure |
function(errorText : String, errorID : Number)
Optional |
Function to be called 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.
|
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) { var purchasedItem = JSON.parse(purchase); var transId = purchasedItem.transactionID; var sku = purchasedItem.digitalGoodSKU; var dgId = purchasedItem.digitalGoodID; alert("Purchased Item: " + transId + "," + sku + "," + dgId); } function failure(errorText, errorId) { alert("Error occured: " + errorText + ", " + errorId); } </script>
Properties:
Property | Type | Description | Supported Platform(s) |
---|---|---|---|
developmentMode default: false |
Static Boolean |
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 OS 5.0+
- BlackBerry PlayBook |