Functions and structures to allow users to purchase digital goods in applications using the BlackBerry Platform Services (BPS) Payment Service API.

The Payment Service API permits BlackBerry device users to initiate the purchase of digital goods from within your application. Digital goods available for purchase must be registered on the Vendor Portal for BlackBerry World. For example, you can use the API to allow users to purchase additional levels in a gaming application or music from a radio application.

Purchases are initiated using the paymentservice_purchase_request() function. The amount of time that elapses before a response is returned depends on how quickly the user completes the purchase process. The purchase process may include steps such as signing in to their BlackBerry ID account, setting up their preferred billing method, and so on. The Payment Service dispatches a PURCHASE_RESPONSE event on purchase completion. The event contains a response code that can be used to determine whether the purchase request was successful or not.

When calling the purchase function, you must provide either the ID or SKU of the digital good to be purchased. It is not a requirement to provide both the ID and SKU, and all other arguments are optional. When both the ID and SKU are provided, the ID takes precedence. The SKU is only used when the digital good cannot be located on the Payment Service server based on the ID.

If an application requires a list of its digital goods that have already been purchased by the user (for example, to avoid offering for sale a digital good that the user already owns), this list can be obtained with the paymentservices_get_existing_purchases_request() function. This function requires the same user interaction as the purchase function, so it can also be a long-running method. Upon completion of the request, the PaymentService dispatches a GET_EXISTING_PURCHASES_RESPONSE event, which contains the success/failure response code.

The strings that are passed as input to the request functions and the strings returned by the getter functions are ASCII-encoded by default. When UTF-8 encoding is required, it is the responsibility of the application to convert the UTF-8 encoded string to char* format. Conversely, it is your responsibility to convert a returned char* format to a UTF-8 encoded values as required.