Initiating a purchase

You can initiate a purchase in your app using the paymentservice_purchase_request() function. You receive a response to this function when a user completes the purchase process (which may include steps such as signing in to a BlackBerry ID account, setting up a preferred payment method, and so on).

When you call the paymentservice_purchase_request() function, only the ID or SKU of the digital good to be purchased is required; you don't need to provide both. If you do provide both, the ID takes precedence.

To analyze the results of the paymentservice_purchase_request(), you must first use the paymentservice_event_get_response_code() function to verify if the request finished. If the Payment Service server is unable to finish the request, an error is returned.

If an error is returned, you can use paymentservice_event_get_error_info() and paymentservice_event_get_error_text() to present a dialog box or toast to your user. If no error is returned, you can use the paymentservice_event_get_metadata() function to present information about the successful purchase to the user.

The following code sample requests a purchase:

do_purchase(int selected_index, char** result_str)
{
    unsigned request_id = 0;
    purchase_params_t params = *available_purchase_info[selected_index];

    paymentservice_purchase_request(params.digital_good_id, params.digital_good_sku, params.digital_good_name,
            params.metadata, params.purchase_app_name, params.purchase_app_icon, get_window_group_id(), &request_id);

    sprintf(*result_str, "Sent purchase request. ID: %d\n", request_id);
}

When you call paymentservice_purchase_request() the digital good name and the purchase metadata are optional parameters, that you might use in the following scenario.

Display a specific name when a single ID or SKU represents multiple digital goods

This approach makes sure that the user is aware of what they are purchasing on the purchase confirmation screen. For example, if a game sells additional levels at a single price point, you can use a generic digital good called "My game level" for all such levels. When a user makes a purchase, the game app should override "My game level" with the name of the level that the user purchased.

do_purchase(int selected_index, char** result_str)
{
    unsigned request_id = 0;
    purchase_params_t params = *available_purchase_info[selected_index];

    paymentservice_purchase_request(params.digital_good_id, params.digital_good_sku, params.digital_good_name,
            params.metadata, params.purchase_app_name, params.purchase_app_icon, get_window_group_id(), &request_id);

    sprintf(*result_str, "Sent purchase request. ID: %d\n", request_id);
}

Last modified: 2013-12-24

comments powered by Disqus