Sample application notes

You can use the Purchase and Payment APIs to create purchase opportunities in your application. To see an implementation of the APIs that you can use in your application, open the Payment Service Sample Application. The sample application illustrates how to implement the following methods, which are necessary to receive payments in your application.

Using development mode

When you develop your application, you need to use the developmentMode property from the Payment API. This property is useful for testing your application without requiring network connections or currency. You can turn on the developmentMode property when you design and test your application so that it does not contact BlackBerry World's Payment Service server for any transactions. Instead, the API displays a simulated purchase screen, from which you can choose the result of the purchase. When you use the developmentMode property, to retrieve existing purchases, only simulated and successful purchases are returned.

Remember to turn off the developmentMode property in production code (or you will not get paid).

appendContent(id, msg)

Adds to the description of your digital goods.

debug(source, msg)

Routes a message (msg) to the console.log().

displayAbout()

Defines the information that your application displays on its About page.

displayDevelopmentMode()

Indicates the state of developmentMode for your application.

displayDigitalGoods()

Retrieves a list of digital goods that are available for purchase within your application.

displayPurchasedInventory()

Displays the purchased state of each of the digital goods in your application's inventory.

incrementPurchaseCount(goodId)

Increments the total number of purchases for a given goodId in your inventory. Note that this method is specific to this sample's implementation.

invokeBrowser(url)

Launches the BlackBerry Browser for external-target links.

makePayment(digitalGoodId)

Initiates the purchase of a digital good.

onPageLoad()

Sets up the application environment when your application is launched.

onPaymentFailure(error)

Retrieves the error information when the application unsuccessfully invokes a call to blackberry.payment.purchase().

onPaymentHistoryFailure(error)

Receives the related error code if an error occurs while making a purchase.

onPaymentHistorySuccess(data)

Receives an array of purchases (in the data parameter), after the application successfully invokes a call to blackberry.payment.getExistingPurchase().

onPaymentSuccess(data)

After a successful call is made to blackberry.payment.purchase(), invoke this method to increment your application's inventory with the submitted payment (data).

refreshPaymentHistory(getFromLiveServer)

Retrieves information about the user's past purchases with this application. The getFromLiveServer parameter is returned true if the BlackBerry device can refresh the list of purchases from BlackBerry World's Payment Service server. If it is returned false, then the current list of cached purchases should be returned immediately. Since your app will already know whether a purchase is successful, this should be used when your app first launches, to confirm that the current list of cached purchases is valid.

setContent(id, msg)

Adds msg to the page (targets an element with the value of the parameter id).

toggleDevelopmentMode()

Sets the developmentMode property to on or off.

Sample process flow for purchasing digital goods

The process for purchasing digital goods is designed to be consistent for each payment type and for all BlackBerry device users.

  1. When it is opened, your application should set up the payment environment with the onPageLoad() method.
  2. Display your inventory of digital goods with the displayDigitalGoods() method.
  3. A user clicks a purchase option for digital goods in your application.

    Purchase screen

  4. The application invokes makePayment(digitalGoodId) to initiate the purchase request and send information about the digital goods to the Payment Service server.
  5. If the user isn't logged in using a BlackBerry ID account, the application prompts the user to provide login information without requiring that the user leave the application.

    Payment login

  6. BlackBerry World's Payment Service server prompts the user to confirm the purchase using the default payment type. The user can then change the payment type or set up a new payment type.

    Confimation screen

  7. The Payment Service server verifies that the digital goods are valid and processes the purchase through the payment provider.
  8. Depending on the results of the purchase attempt, one of the following events occurs:
    • If the purchase request is successful, you can find information about purchase from the Payment Service server with the onPaymentSuccess(data) method as well as calling incrementPurchaseCount(goodId).
    • If the purchase request is unsuccessful, the application throws an exception. You can find information about purchase failure with the onPaymentFailure(error) method. For information about handling exceptions, see the API reference.
  9. Update the user's list of purchased goods with the refreshPaymentHistory(getFromLiveServer) method.
  10. If the purchase attempt is successful, the application provides the digital goods to the user in the manner that you designed.

Last modified: 2013-10-02