Payment

Entry point for purchasing digital goods.

Since: BlackBerry WebWorks 2.0

API that permits BlackBerry device users to initiate the purchase of digital goods from within your application. For example, this API can be used to allow users to purchase additional levels in a gaming application, music from a radio application, or any other digital good registered on the Vendor Portal for BlackBerry World. The digital good being purchased must be associated with the calling application in the Vendor Portal for BlackBerry World.

Purchases are initiated via the purchase method. The amount of time that elapses before a response is returned depends on how quickly the user completes the purchase process (which may include steps such as signing in to their BlackBerry ID account and setting up their preferred billing method). The purchase method dispatches a callbackOnSuccess on success, or dispatches a callbackOnFailure on failure.

When calling the purchase method only the ID or SKU of the digital good to be purchased is required; it is not necessary to provide both, and all other arguments are optional. If both the ID and SKU are provided, then the ID takes precedence; the SKU is only used if the digital good could not 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 the user already owns), such a list can be obtained with the blackberry.payment.getExistingPurchases() method. This method requires the same user interaction as the purchase method, so it can also be a long-running method.

Installation:

To use this API in your project, add the payment plugin:

webworks plugin add com.blackberry.payment
Properties:
Boolean developmentMode

cancelSubscription()

Initiates a request to cancel a subscription for a digital good.

If successful the subscription becomes canceled and will not be renewed at the end of the current subscription period. The subscription will remain valid until the end of the current subscription period. The subscription to cancel is identified by a purchase ID that is returned at the time of purchase or queried by calling getExistingPurchases. The cancelation of a non-subscription digital good is not permitted.

Synopsis:

void blackberry.payment.cancelSubscription(purchaseID, onSuccess, onFailure)

Parameters:

purchaseID {String}

purchaseID The purchase ID when the subscription was purchased.

onSuccess {Function}

Function to be balled on success.

data.cancelSubscription {Boolean}

True if the cancellation was successful.

onFailure {Function}

Function to be invoked when an error occurs.

error {PaymentError}

A PaymentError object containing details about the error.

Example:

<script type="text/javascript">

    function cancelSubscription() {
        try {
            blackberry.payment.cancelSubscription("12345", onSuccess, onFailure);
        } catch (e) {
            alert ("Error" + e);
        }
    }

    function onSuccess(data) {
        alert("Cancellation " + (data.subscriptionCancelled ? "" : "NOT ") + "successful");
    }

    function onFailure(error) {
        alert("Error occurred: " + error.errorText + ", " + error.errorID);
    }

</script>
            

checkAppSubscription()

Initiates a call to check whether the currently logged in BBID user has rights to the current app-level subscription. If the calling application is not a subscription app, this will return false.

Synopsis:

void blackberry.payment.checkAppSubscription(onSuccess, onFailure)

Arguments:

onSuccess {Function}

Function to be called on success.

subscriptionExists {Boolean}

Whether the subscription to the application is currently active.

onFailure {Function}

Function to be called when an error occurs.

error {PaymentError}

A PaymentError object containing details about the error.

Example:

<script type="text/javascript">

    function checkAppSubscription() {
        try {
            blackberry.payment.checkAppSubscription(onSuccess, onFailure);
        } catch (e){
            alert("Error" + e);
        }
    }

    function onSuccess(data) {
        alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the app.");
    }

    function onFailure(error) {
        alert("Error occurred: " + error.errorText + ", " + error.errorID);
    }

</script>
            

checkExisting()

Initiates a call to check whether the currently logged in BBID user has rights to the provided digital good subscription at this time.

Synopsis:

void blackberry.payment.checkExisting(args, onSuccess, onFailure)

Parameters:

args {Object}

Contains information that describes the digital good. One of ID or SKU needs to be specified, and if both are specified, the ID takes precedence and SKU will be ignored.

id {String}

ID of the digital good

sku

SKU of the digital good

onSuccess {Function}

Function to be invoked on successful call

data.subscriptionExists {Boolean}

True if the cancellation was successful.

onFailure {Function}

Function to be called when an error occurs.

error {PaymentError}

A PaymentError object containing details about the error.

Example:

<script type="text/javascript">

    function checkSubscription() {
        try {
            blackberry.payment.checkExisting({
                id": 12345"
            }, onSuccess, onFailure);
        } catch (e) {
            alert ("Error" + e);
        }
    }

    function onSuccess(data) {
        alert("User is " + (data.subscriptionExists ? "" : "not ") + "subscribed to the item.");
    }

    function onFailure(error) {
        alert("Error occurred: " + error.errorText + ", " + error.errorID);
    }

</script>
            

getExistingPurchases()

Retrieves the previous successful purchases made by the user from within the calling application.

Synopsis:

void blackberry.payment.getExistingPurchases(refresh, onSuccess, onFailure)

Arguments:

refresh {Boolean}

if the BlackBerry should be allowed to refresh the list of purchases from the Payment Service server. False if the current list of cached purchases should be returned immediately.

onSuccess {Function}

Function to be invoked on successful call.

data {Purchase}

An array of Purchase items.

onFailure {Function}

Function to be invoked when an error occurs.

error {PaymentError}

A PaymentError object containing details about the error.

Example:

<script type="text/javascript">

    function getExistingPurchases() {
        try {
            blackberry.payment.getExistingPurchases(true, onSuccess, onFailure);
        } catch (e) {
            alert ("Error" + e);
        }
    }

    function onSuccess(purchases) {
        for (var i = 0; i < purchases.length; i++) {
            var transId = purchases[i].transactionID;
            var sku = purchases[i].digitalGoodSKU;
            var dgId = purchases[i].digitalGoodID;
            alert("Purchased Item " + i + ": " + transId + "," + sku + "," + dgId);
        }
    }

    function onFailure(err) {
        alert("Error occurred: " + err.errorText + ", " + err.errorID);
    }

</script>
            

getPrice()

Initiates a request for the price of a digital good. The request can be initiated using either the ID or the SKU of the digital good to be purchased.

Synopsis:

void blackberry.payment.getPrice(args, onSuccess, onFailure)

Parameters:

args {Object}

Contains information that describes the digital good. One of ID or SKU needs to be specified, and if both are specified, the ID takes precedence and SKU will be ignored.

id {String}

ID of the digital good.

sku

SKU of the digital good

onSuccess {Function}

Function to be called on success.

data {Object}

The data object of the success callback.

price {String}

The cost of the digital good.

initialPeriod {String}

The number of days in the subscriptions initial period. This will only be present if the digital good represents a subscription item.

renewalPrice {String}

The subscription renewal price. This will only be present if the digital good represents a subscription item.

renewalPeriod {String}

The number of days in the subscription renewal period. This will only be present if the digital good represents a subscription item.

onFailure {Function}

Function to be invoked when an error occurs

error {PaymentError}

A PaymentError object containing details about the error

Example:

<script type="text/javascript">

    function getPrice() {
        try {
            blackberry.payment.getPrice({
                "id:" "123"
            }, onSuccess, onFailure);
        } catch (e) {
            alert ("Error" + e);
        }
    }

    function onSuccess(data) {
        var price = data.price;

        alert("Digital good price: " + price);

        if (data.initialPeriod) {
            var initialPeriod = data.initialPeriod;
            var renewalPrice = data.renewalPrice;
            var renewalPeriod = data.renewalPeriod;
            alert("Subscription Info: " + initialPeriod + "," + renewalPrice + "," + renewalPeriod);
        }
    }


    function onFailure(err) {
        alert("Error occurred: " + err.errorText + ", " + err.errorID);
    }

</script>
            

purchase()

Initiates the purchase of a digital good. Purchases can be initiated using either the ID or the SKU of the digital good to be purchased, but it is not necessary to provide both. To customize the name and icon that are displayed on the purchase dialog banners, provide the purchaseAppName and/or purchaseAppIcon arguments. If not provided, the name and icon that were registered with App World will be used.

Synopsis:

void blackberry.payment.purchase(args, onSuccess, onFailure)

Parameters:

args {Object}

Contains information that describes the digital good. One of ID or SKU needs to be specified, and if both are specified, the ID takes precedence and SKU will be ignored.

digitalGoodID {String}

ID of the digital good being purchased

digitalGoodSKU {String}

SKU of the digital good being purchased.

digitalGoodName {String}

Name of the digital good being purchased

metaData {Object}

Metadata associated with the digital good. Metadata offers the application developer a way to store information about each purchase on the Payment Service server.

purchaseAppName {String}

Name of the application requesting the purchase.

purchaseAppIcon {String}

Icon of the application requesting the purchase.

extraParameters {Object}

Set of extra parameters, in the form of key/value pairs, to associate with the purchase.

onSuccess {function}

Function to be invoked on successful call

data {Boolean}

A Purchase object containing the details of the successful purchase.

onFailure {function}

Function to be invoked when an error occurs

error {PaymentError}

A PaymentError object containing details about the error

Example:

<script type="text/javascript">
function purchase() {
    try {
        blackberry.payment.purchase({
		    "digitalGoodID":"123",
		    "digitalGoodSKU":"someSKU",
		    "digitalGoodName":"SomeName",
		    "metaData":"metadata",
		    "purchaseAppName":"WebWorks APP",
		    "purchaseAppIcon":null,
		    "extraParameters": {
			    "key1": "value1",
			    "key2": "value2"
		    }
		},
		onSuccess, onFailure);
	} catch (e) {
		alert ("Error" + e);
	}
}

function onSuccess(purchasedItem) {
    var transId = purchasedItem.transactionID;
	var sku = purchasedItem.digitalGoodSKU;
	var dgId = purchasedItem.digitalGoodID;
	alert("Purchased Item: " + transId + "," + sku +  "," + dgId);
}

function onFailure(error) {
    alert("Error occurred: " + error.errorText + ", " + error.errorID);
}
</script>
            

developmentMode

Defines the development mode used in the application.

If development mode is set to true, the application does not contact the Payment Service server for any transactions. For purchases, a simulated purchase screen is displayed, allowing the user to choose the result of the purchase. For retrieving existing purchases, only simulated successful purchases are returned. This mode is useful for testing how your application handles the possible results without requiring network connections or currency. THIS MODE SHOULD NOT BE USED IN PRODUCTION CODE. If development mode is set to false, purchases and retrievals of existing purchases proceed normally, contacting the Payment Service server as necessary. This is the default development mode, and applications in production should not modify it.

Synopsis:

{Boolean}

Last modified: 2014-10-09



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

comments powered by Disqus