Sample App - BlackBerry WebWorks Payment Service

by Retired ‎07-25-2011 03:38 PM - edited ‎08-16-2011 09:23 AM (6,666 Views)

What is it?


This sample demonstrates how to leverage the BlackBerry Payment Service in an application created using the BlackBerry WebWorks SDK.  The Payment Service API provides an end-to-end payment solution for monetizing application content. 


Applies to:


  • BlackBerry® Tablet OS
  • BlackBerry® WebWorks™ SDK for Tablet OS







Getting Started: sample application


Download the sample code from Github, build it using the BlackBerry WebWorks SDK for Tablet OS and install the sample app on a BlackBerry Tablet OS simulator, or a live BlackBerry PlayBook Tablet.


The following steps demonste how to use the BlackBerry Payment Service to include features such as a "Buy" button in your application, as well as displaying and evaluating a history of purchases.


  1. Enable or disable payment service development mode.
  2. Click on a "Buy" button to purchase one of the available digital goods.
  3. Observe any success or error messages as well as the purchase history listing.




Use Cases


Using the Payment Service API, you can provide an end-to-end payment solution to allow users to purchase in-application digital goods.

As explained in the Developer's Blog posting, Introducing the BlackBerry Payment Service and BlackBerry Payment Service SDK, there are certain types of digital goods that can be distributed through BlackBerry App World™ storefront, and others that cannot.

Allowed digital goods:


  • Digital Content – eBooks, magazines, photos, artwork, or digital property (e.g. audio, video content) that you can use on a BlackBerry® device.
  • Additional Functionality – new features, levels, characters, or games (e.g. "epic sword", "levels 50-59".  Must be distributed with the application and unlocked for a BlackBerry device user after a purchase.
  • Services – any kind of digital service that a BlackBerry device user must pay to use (e.g. subscriptions, video streaming).



Prohibited digital goods:


  • Virtual currencies or in-app credits – digital currencies or in-app credits that can be used to purchase digital goods are prohibited.
  • Physical goods or services – In-app purchases must be digital content that is usable on the BlackBerry device, not physical goods or services.
  • Digital goods used across multiple applications – You can’t sell digital goods to a user in one application that can be used with other applications.


How it works?


Using the blackberry.payment WebWorks JavaScript® API, developers can add functionality to applications that allow users to submit requests to purchase a digital good, as well as retrieve a history of payments.



Example: Display a "Subscriptions" menu item if the user has purchased an given digital good "123":


   <li id="sub" style="display:none;">Subscriptions</li>

function checkForSubscription(data)
   for (i = 0; i < data.length; i++)
      if (data[i].digitalGoodID = "123") {
         document.getElementById("sub").style.display = "";

blackberry.payment.getExistingPurchases(true, checkForSubscription, onFailure);


Buying Digital Goods


A purchase request is completed by creating a JSON object containing the details of a digital good, and calling the blackberry.payment.purchase() method.  The payment service (live server, or local cache depending on whether development mode is On) will return another JSON object containing the successful details of the transaction.


Creating Digital Goods


As a developer, you create the digital goods for your application through the App World vendor portal.  For detailed information on how to create digital goods for your application, see the "Submitting digital goods" chapter of the Payment Service SDK Development Guide.



Development Mode


Development mode is a true/false value that defines how an application behaves when a purchase request is submitted using the BlackBerry payment API.  Development mode is Off by default.


On - If development mode is On, the application does not contact the (live) Payment Service server for any transactions. This mode is useful for testing how your application handles the possible results without requiring network connections or currency. 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.




Off - If development mode is Off, purchases and retrievals of existing purchases proceed normally, contacting the (live) Payment Service server for any transactions. Users are prompted to select one of their preferred payment methods. Off is the default development mode, and applications in production should not modify it.




More Info