Setting up the Payment Service

The Payment Service classes are included in the BlackBerry 10 Native SDK. Before you set up the Payment Service, you must register your app and its digital goods in the BlackBerry World storefront. To learn more, see Registering with BlackBerry World.

The following sections describe what you need to create in-app purchase opportunities. The code samples in these sections are based on the Payment Service sample app.

You must include the following header files from the BlackBerry Platform Services (BPS) library:

#include <bps/bps.h>
#include <bps/paymentservice.h>

This solution requires that you register any digital goods that you want to make available in your app in the BlackBerry World vendor portal.

Before you let users make in-app purchases, there are a few things you should do first:

Create a payment instance

To allow a purchase in your app, you must initialize the Payment Service in your app. When you initialize the library, you can call other functions in the BlackBerry Platform Services library, including Payment Service functions. You can then call paymentservice_request_events() to start receiving Payment Service events.

 //Initialize the Payment Service bps_initialize(); // 0
                indicates that all events are requested paymentservice_request_events(0);

Set the connection mode

By default, your app contacts the Payment Service server for transactions if your app is live. If you want to test your app without incurring accidental charges, you should set the connection mode to local. In local mode, your app doesn't contact the Payment Service server for any transactions. To switch to local connection mode, call paymentservice_set_connection_mode() and pass in the argument true. When your app is live, it should not be in local mode. For more information, see Testing in-app purchases.


Do not change the connection mode while Payment Service operations are in progress. This will result in undefined behavior.

Set the window group ID

You must set the window group ID when your application starts, so that the Payment Service can display dialog boxes. You can retrieve the window paymentservice_purchase_arguments_get_group_id() and set the window group ID for your app using the paymentservice_purchase_arguments_set_group_id() function.

// Get the window group ID.
paymentservice_purchase_arguments_set_group_id(args, get_window_group_id());
if (params.metadata) {
    paymentservice_purchase_arguments_set_metadata(args, params.metadata);

Set the app name

When a purchase is initiated, the purchase screens display a banner along the top of the screen. This banner shows the name and icon of the app that the purchase is being made from (your app). If you don't set the app name, the application name that was registered in BlackBerry World is used.

If you need the application name later, you can use paymentservice_purchase_arguments_set_app_name() to retrieve the application name.

You cannot see this banner if you set the connection mode to local because all transactions are simulated. You must set the connection mode to Production.

// Set the application name so that it shows up in the purchase banner.
paymentservice_purchase_arguments_set_app_name(purchase_arguments_t *purchase_arguments, const char *app_name)

Specify an application icon URL

The application icon is displayed in the purchase screen banner during the purchase process. The icon must be available through an external website, with a URL that uses the "http://..." format. The icon can be any standard format (PNG, GIF, JPEG) but it should be a 100x100 pixel square. If you don't provide an icon, the icon that was registered in BlackBerry World is used and it may be scaled to 100 x 100 pixels. For more information about application icons, see Application icons. If you need to retreive the icon URL in your code, you can use paymentservice_purchase_arguments_get_app_icon().

// Set the application URL so that it shows up in the purchase banner.
params->purchase_app_icon = "";

Do not change the connection mode while Payment Service operations are in progress. This will result in undefined behavior.

Last modified: 2014-05-14

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus