Setting up the Payment Service

The Payment Service classes are included in the BlackBerry 10 Native SDK. If you are creating your first app, you can download the tools that you need and learn how to create, build, and run your first project. Before you begin, you must register your app and its digital goods in the BlackBerry World vendor portal. To learn more, see Registering with BlackBerry World.

The following sections describe the steps that you can follow to create in-app purchase opportunities. The code samples in these sections are based on the following samples:

To learn more about how to import an existing project into the Momentics IDE for BlackBerry, see Import an existing project.

To use the Payment Service APIs in your app, you need to link against the correct library by adding the BlackBerry Platform Services (libbps) library to your project.

Create a payment instance

To allow a purchase in your app, you must initialize the Payment Service in your app.

To start receiving Payment Service events, call paymentservice_request_events().

#include <bps/bps.h>
#include <bps/paymentservice.h>
// Initialize the Payment Service 
bps_initialize(); 

// Request all events 
paymentservice_request_events(0);
            

Set the window group ID

You must set the window group ID for your payment instance when your app starts, so that the Payment Service can display dialog boxes. The window group ID of your app is initialized when your app starts.

You can 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 connection mode

By default, your app contacts the Payment Service server for transactions as if your app is in production. If you want to test your app (and you don't want any accidental charges), you should set the connection mode to Test for Cascades apps or local for C apps. In test/local mode, your app doesn't contact the Payment Service server for any transactions. For more information, see Testing in-app purchases.

The connection mode affects all Payment Service requests made from your app. You should set the connection mode when your app starts, before any in-app purchases are created.

You must not change the connection mode while Payment Service operations are outstanding.

// Set connection mode to local
paymentservice_set_connection_mode(true);

Specify an app icon URL

The app icon is displayed on a banner during the purchase process when an app is in production mode. 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 app icons, see Application icons.

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

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

If you need to retreive the icon URL in your code, you can use paymentservice_purchase_arguments_get_app_icon().

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 app name that was registered in BlackBerry World is used.

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

// Set the app 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)

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

Last modified: 2014-09-30



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

comments powered by Disqus