Initiate the purchase of a digital good.
BPS_API int paymentservice_purchase_request(const char *digital_good_id, const char *digital_good_sku, const char *digital_good_name, const char *metadata, const char *app_name, const char *app_icon, const char *group_id, unsigned *request_id)
The ID of the digital good to purchase. Use a NULL value if digital_good_sku should be used to reference the digital good on the server.
The SKU of the digital good to purchase. Use a NULL value if the digital_good_id should be used to reference the digital good on the server.
(Optional) The name of the digital good to purchase. Use a NULL to omit this argument.
(Optional) The metadata for the digital good. Use a NULL value to omit this argument.
(Optional) The name of the application through which the purchase is being made, or a NULL value to omit this argument. If provided, this name will be displayed in a banner along the top of the purchase confirmation screen that shall be presented to the user.
(Optional) The full URL to an icon to display, or a NULL value to omit this argument. If provided, the icon shall be displayed on the purchase confirmation screen that shall be presented to the user.
The window group ID of the application. This ID is required so that the Payment Service can properly display dialogs.
The Payment Service populates this argument upon successful completion of the request with the request ID. It can be used to correlate the response to the request.
The paymentservice_purchase_request() function initiates the purchase of a digital good.
It is not a requirement to provide both the ID and SKU, and all other arguments are optional. The ID takes precedence when your application provides both the ID and SKU. The SKU is only used only when the digital good cannot be located on the Payment Service server based on the ID.
You should provide the name of the digital good when a single ID or SKU represents multiple digital goods on the Payment Service server and when a more specific digital good name is required for display on the purchase screen. For example, if a game sells additional levels using the Payment Service at a single price point, then a generic "My game level" digital good can be used for all such levels. However, at the time of purchase, the game application can override "My game level" with the name of the level that was purchased. This mechanism is useful to notify the end user of what is being purchased on the purchase confirmation screen.
Metadata offers the application developer a way to store information about each purchase on the Payment Service server and to retrieve that data using the paymentservice_get_existing_purchases_request() function. For example, assume a book vendor offers several titles at a single price point, and represents them on the Vendor Portal as a single digital good. In this case, the ISBN of the book can be provided as metadata. The metadata can be used to uniquely identify the digital good that was purchased. You can also retrieve the entire list of purchased books at any time by using the paymentservice_get_existing_purchases_request() function to obtain previous purchases, filtering on the book's digital good Content ID, and finally, enumerating the ISBNs in the metadata of each purchase.
To further give context to the end user during an in-application purchase, a banner is displayed along the top of the purchase and BlackBerry ID login screens. The banner shows the name and icon of the application that the purchase is being made from.
To customize the name and icon that are displayed, simply provide them as arguments. When the name or icon are not provided as arguments, then they are retrieved from the purchasing application's bar-descriptor.xml file - though this may not work for applications that register with the home screen dynamically. In these cases, it is highly recommended that the purchasing application explicitly provides a name and icon as part of the purchase arguments.
There may be output parameters present, in the form of key/value pairs, in the PURCHASE_RESPONSE. The number of output parameters, if any, can be retrieved via paymentservice_event_get_extra_parameter_count(), and the parameters themselves can be retrieved via paymentservice_event_get_extra_parameter_key_at_index() and paymentservice_event_get_extra_parameter_value_at_index().
BPS_SUCCESS upon success, BPS_FAILURE with errno value set otherwise.
Last modified: 2013-09-30