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 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 OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.payment.cancelSubscription           Y 
blackberry.payment.checkAppSubscription           Y 
blackberry.payment.checkExisting           Y 
blackberry.payment.getExistingPurchases           Y 
blackberry.payment.getExistingPurchases Y Y Y Y Y   
blackberry.payment.getPrice           Y 
blackberry.payment.purchase           Y 
blackberry.payment.purchase Y Y Y Y Y   
developmentMode Y Y 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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.payment" /> Y Y Y Y Y Y 

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


Properties

Boolean developmentMode

Functions

static void blackberry.payment.cancelSubscription (purchaseID : String, onSuccess: function(), onFailure: function(error : PaymentError))


Initiates a request to cancel a subscription for a digital good. If successful the subscription becomes canceled and will not be renewed at the end of the current subscription period. The subscription will remain valid until the end of the current subscription period. The subscription to cancel is identified by a purchase ID that is returned at the time of purchase or queried by calling getExistingPurchases. The cancelation of a non-subscription digital good is not permitted.


Supported Platforms
 - BlackBerry 10


Parameters
purchaseID The purchase ID when the subscription was purchased.
onSuccess Function to be called on success.

data.subscriptionCancelled: True if the cancellation was successful.
onFailure Function to be called when an error occurs.

error: A PaymentError object containing details about the error.

Code Example:
<script type="text/javascript">
  function cancelSubscription() {
      try {
          blackberry.payment.cancelSubscription("12345", onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

 function onSuccess(data) {
     alert("Cancellation " + (data.subscriptionCancelled ? "" : "NOT ") + "successful");
 }

 function onFailure(error) {
     alert("Error occurred: " + error.errorText + ", " + error.errorID);
 }
</script>

static void blackberry.payment.checkAppSubscription (onSuccess: function(), onFailure: function(error : PaymentError))


Initiates a call to check whether the currently logged in BBID user has rights to the current app-level subscription. If the calling application is not a subscription app, this will return false.

A user can cancel a subscription, and it will remain active until the subscription period has passed.


Supported Platforms
 - BlackBerry 10


Parameters
onSuccess Function to be called on success.

data.subscriptionExists: Whether the subscription to the application is currently active.
onFailure Function to be called when an error occurs.

error: A PaymentError object containing details about the error.

Code Example:
<script type="text/javascript">
 function checkAppSubscription() {
     try {
         blackberry.payment.checkAppSubscription(onSuccess, onFailure);
     } catch (e){
         alert("Error" + e);
     }
 }

 function onSuccess(data) {
     alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the app.");
 }

 function onFailure(error) {
     alert("Error occurred: " + error.errorText + ", " + error.errorID);
 }
</script>

static void blackberry.payment.checkExisting (args : Object, onSuccess: function(), onFailure: function(error : PaymentError))


Initiates a call to check whether the currently logged in BBID user has rights to the provided digital good subscription at this time.

A user can cancel a subscription, and it will remain active until the subscription period has passed.


Supported Platforms
 - BlackBerry 10


Parameters
args Contains information that describes the digital good. One of ID or SKU needs to be specified, and if both are specified, the ID takes precedence and SKU will be ignored.

id: ID of the digital good.
sku: SKU of the digital good.
onSuccess Function to be called on success.

data.subscriptionExists: Whether the subscription digital good is currently active.
onFailure Function to be called when an error occurs.

error: A PaymentError object containing details about the error.

Code Example:
<script type="text/javascript">
  function checkSubscription() {
      try {
          blackberry.payment.checkExisting({
              "id": 12345"
          }, onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

 function onSuccess(data) {
     alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the item.");
 }

 function onFailure(error) {
     alert("Error occurred: " + error.errorText + ", " + error.errorID);
 }
</script>

static void blackberry.payment.getExistingPurchases (refresh : Boolean, onSuccess: function(data : Purchase[]), [onFailure: function(error : PaymentError)])


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


Supported Platforms
 - BlackBerry 10


Parameters
refresh True if the BlackBerry should retrieve the list of purchases from the Payment Service server. False if the BlackBerry should attempt to use the local purchase history, and only go to the Payment Service server if necessary.
onSuccess Function to be invoked on successful call.

data: An array of Purchase items
onFailure Function to be invoked when an error occurs.

error: A PaymentError object containing details about the error.

Code Example:
<script type="text/javascript">
  function getExistingPurchases() {
      try {
          blackberry.payment.getExistingPurchases(true, onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

 function onSuccess(purchases) {
     for (var i = 0; i < purchases.length; i++) {
         var transId = purchases[i].transactionID;
         var sku = purchases[i].digitalGoodSKU;
         var dgId = purchases[i].digitalGoodID;
         alert("Purchased Item " + i + ": " + transId + "," + sku + "," + dgId);
     }
 }

 function onFailure(err) {
     alert("Error occurred: " + err.errorText + ", " + err.errorID);
 }
</script>

static void blackberry.payment.getExistingPurchases ([refresh : Boolean], callbackOnSuccess: function(data : String), [callbackOnFailure: function(errorText : String, errorID : Number)])


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


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+


Parameters
refresh 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 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 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
  • Illegal Application Error = 5 [BlackBerry OS 5.0+ only]
Note: The actual values may be different when developmentMode equals true.

static void blackberry.payment.getPrice (args : Object, onSuccess: function(), onFailure: function(error : PaymentError))


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.


Supported Platforms
 - BlackBerry 10


Parameters
args Contains information that describes the digital good. One of ID or SKU needs to be specified, and if both are specified, the ID takes precedence and SKU will be ignored.

id: ID of the digital good.
sku: SKU of the digital good.
onSuccess Function to be called on success.

data.price: The cost of the digital good.
data.initialPeriod: The number of days in the subscriptions initial period. This will only be present if the digital good represents a subscription item.
data.renewalPrice: The subscription renewal price. This will only be present if the digital good represents a subscription item.
data.renewalPeriod: The number of days in the subscription renewal period. This will only be present if the digital good represents a subscription item.
onFailure Function to be called when an error occurs.

error: A PaymentError object containing details about the error.

Code Example:
<script type="text/javascript">
  function getPrice() {
      try {
          blackberry.payment.getPrice({
             "id:" "123"
          }, onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

  function onSuccess(data) {
      var price = data.price;

      alert("Digital good price: " + price);

      if (data.initialPeriod) {
          var initialPeriod = data.initialPeriod;
          var renewalPrice = data.renewalPrice;
          var renewalPeriod = data.renewalPeriod;
          alert("Subscription Info: " + initialPeriod + "," + renewalPrice + "," + renewalPeriod);
      }
  }

  function onFailure(err) {
      alert("Error occurred: " + err.errorText + ", " + err.errorID);
  }
</script>

static void blackberry.payment.purchase (args : Object, onSuccess: function(data : Purchase), onFailure: function(error : PaymentError))


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. To customize the name and icon that are displayed on the purchase dialog banners, provide the purchaseAppName and/or purchaseAppIcon arguments. If not provided, the name and icon that were registered with App World will be used.


Supported Platforms
 - BlackBerry 10


Parameters
args 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.
extraParameters: Set of extra parameters, in the form of key/value pairs, to associate with the purchase.
onSuccess Function to be called when the payment is successful.

data: A Purchase object containing the details of the successful purchase.
onFailure Function to be called when an error occurs.

error: A PaymentError object containing details about the error.
Note: The actual values may be different when developmentMode equals true.

Code Example:
<script type="text/javascript">
  function purchase() {
      try {
          blackberry.payment.purchase({
              "digitalGoodID":"123",
              "digitalGoodSKU":"someSKU",
              "digitalGoodName":"SomeName",
              "metaData":"metadata",
              "purchaseAppName":"WebWorks APP",
              "purchaseAppIcon":null,
              "extraParameters": {
                  "key1": "value1",
                  "key2": "value2"
              }
          },
          onSuccess, onFailure);
      } catch (e) {
          alert ("Error" + e);
      }
  }

  function onSuccess(purchasedItem) {
      var transId = purchasedItem.transactionID;
      var sku = purchasedItem.digitalGoodSKU;
      var dgId = purchasedItem.digitalGoodID;
      alert("Purchased Item: " + transId + "," + sku +  "," + dgId);
  }

  function onFailure(error) {
      alert("Error occurred: " + error.errorText + ", " + error.errorID);
  }
</script>

static void blackberry.payment.purchase (args : Object, callbackOnSuccess: function(data : String), [callbackOnFailure: function(errorText : String, errorID : Number)])


Initiates the purchase of a digital good.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+


Parameters
args 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 to be called when the payment is successful.

data: A string representing a Purchase object literal.
callbackOnFailure 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.
  • User Cancelled = 1
  • Payment System Busy = 2
  • General Payment System Error = 3
  • Digital Good not Found = 4
  • Illegal Application Error = 5 [BlackBerry OS 5.0+ only]

Code Example:
<script type="text/javascript">
  function purchase() {
      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

static Boolean developmentMode


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10


Default Value:

false


Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:08 GMT-0500 (EST)