Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Payment Service SDK

Selling digital goods in your application

The Payment Service SDK provides a set of classes that allow you to hook your application into the Payment Service, which processes the purchases that users make in the BlackBerry World storefront. You can use the Payment Service APIs to create a highly secure and consistent purchase experience that permits users to make purchases without leaving your application.

To sell digital goods from your application you must be a registered vendor with BlackBerry World, and your application containing digital goods must be distributed exclusively through BlackBerry World. Digital goods go through a vetting process along with your applications. To sign up as a vendor, visit http://appworld.blackberry.com/isvportal.

Users can purchase digital goods using any of the payment types supported by BlackBerry World. Payment methods can include billing to the wireless service provider (if available), credit card, or PayPal. To purchase digital goods, users must have the BlackBerry World storefront 3.1 or later installed on their BlackBerry devices.

Features

Feature

Description

Support for multiple payment types

The Payment Service permits BlackBerry device users to purchase digital goods by using PayPal, a credit card, or wireless service provider billing (if supported by the user's wireless service provider). The purchase process is designed to be consistent for all users, regardless of the type of payment they choose to use.

The revenue that you receive for the sale of digital goods remains the same regardless of the payment type that the user chooses.

Support for multiple license models

The Payment Service supports the sale of consumable digital goods, digital goods that require a one-time payment, and subscription-based digital goods. Consumable digital goods are purchased by users for each use. One-time payment digital goods are purchased by users only once, and the Payment Service server blocks subsequent purchases. Subscription-based digital goods are purchased initially by users, and then users are charged at regular intervals for continued use of the digital goods.

Simple and flexible implementation

The Payment Service SDK provides the functionality to handle the login and confirmation screens for a purchase so that you don't have to develop them yourself. The Payment Service also provides flexibility by allowing you to control the look and feel for how you present your users with purchase options and for how you deliver digital goods to your users.

Highly secure and reliable payment processing

To purchase digital goods, users must authenticate themselves with the Payment Service server by providing their BlackBerry ID credentials in the application. The Payment Service server handles the communication with payment providers (PayPal, credit card companies, and wireless service providers) so that you don't need to set up these relationships yourself and implement support for each payment provider in your application.

Thorough testing capabilities

The Payment Service SDK can support live testing. When testing your application with the live Payment Service server, you can configure a BlackBerry ID account and initiate test purchases of your digital goods without actually charging the account.

Architecture: Payment Service framework


Architecture diagram showing the components of the Payment Service framework

Component

Description

Content server

The content server is an optional component that you can set up to send digital goods to your users after they purchase digital goods. You might not require this component if you include the digital goods in the source code for your application and programmatically unlock the digital goods for users after a purchase.

If you set up a content server, you can provide the URL for the content server in the vendor portal for the BlackBerry App World storefront. The Payment Service server can use the URL to send notifications about successful purchases to your content server.

Payment providers

The payment providers are the organizations that offer payment types that device users can use to purchase digital goods (PayPal, credit card, wireless service provider billing). The Payment Service server handles the communications with the payment providers so that you don't have to implement support for each payment method in your application.

Payment Service server

The Payment Service server facilitates the interactions that can occur between your application, payment providers, the vendor portal, and your content server.

Vendor portal for BlackBerry App World

The vendor portal provides a UI that you can use to register your digital goods. You must add information about the digital goods, such as the name, a SKU, and pricing.

Process flow: 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. A user clicks a purchase option for digital goods in your application.


  2. The application creates a PurchaseArguments object which contains information about the digital goods.
    PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
        .withDigitalGoodSku( "abc123" )
        .withDigitalGoodName( "Adventures of a BlackBerry WebWorks Developer" )
        .withPurchasingAppName( "My eBooks" )
        .withMetadata ( "ISBN 34560202010" );
  3. The application invokes PaymentEngine.purchase(PurchaseArguments) to initiate the purchase request and send information about the digital goods to the Payment Service server.
    try 
    {
        PurchaseResult purchaseResult = engine.purchase(arguments.build());
    } 
    catch (PaymentException e) 
    {
        Dialog.inform(e.getMessage());
    }
  4. 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.


  5. The application prompts the user to confirm the purchase using the default payment type. The user can change the payment type or set up a new payment type.


  6. The Payment Service server verifies that the digital goods are valid and processes the purchase through the payment provider.
  7. Depending on the results of the purchase attempt, one of the following events occurs:
    • If the purchase request is successful, the Payment Service server returns a PurchaseResult object to the application that contains details about the successful purchase. If the application utilizes a content server, the Payment Service server can send information about the successful purchase to the content server as well.
    • If the purchase request is unsuccessful, the application throws an exception. For information about handling exceptions, view the API reference for the Payment Service SDK.
  8. If the purchase attempt is successful, the application provides the digital goods to the user in the manner that you designed.