net.rim.blackberry.payment.PaymentSystem

PaymentSystem

Methods | Events | Constants | Examples


Packagenet.rim.blackberry.payment
Classpublic class PaymentSystem
InheritancePaymentSystem Inheritance flash.events.EventDispatcher

Entry point for purchasing digital goods.

An 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 App World. The digital good being purchased must be associated with the calling application in the Vendor Portal for BlackBerry App World.

Purchases are initiated using 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, setting up their preferred billing method, and so on.). The purchase method dispatches a PaymentSuccessEvent on success, or dispatches a PaymentErrorEvent 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 a digital good for sale that the user already owns), you can use the getExistingPurchases method. This method requires the same user interaction as the purchase method, so it can also be a long-running method.



Class information:
BlackBerry 10 Version:   10.0.0

View the examples



Public Methods

 MethodDefined By
  
PaymentSystem(target:IEventDispatcher = null)
Constructs a PaymentSystem object in order to listen for success and failure events.
PaymentSystem
  
cancelSubscription(purchaseID:String = null):void
Cancels the subscription of a digital good.
PaymentSystem
  
checkExisting(digitalGoodID:String = null, digitalGoodSKU:String = null):void
Checks whether a digital good's subscription is still active.
PaymentSystem
  
getExistingPurchases(allowRefresh:Boolean = false):void
Retrieves the previous successful purchases made by the user from within the calling application.
PaymentSystem
  
getPrice(digitalGoodID:String = null, digitalGoodSKU:String = null):void
Retrieves the price of a digital good
PaymentSystem
  
purchase(digitalGoodID:String = null, digitalGoodSKU:String = null, digitalGoodName:String = null, metaData:String = null, purchaseAppName:String = null, purchaseAppIcon:String = null):void
Initiates the purchase of a digital good.
PaymentSystem
  
setConnectionMode(mode:String):void
Sets the connection mode used in the application.
PaymentSystem

Events

 Event Summary Defined By
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem
  PaymentSystem

Public Constants

 ConstantDefined By
  CONNECTION_MODE_LOCAL : String = connection_mode_local
[static] Constant used for enabling local connection mode in the setConnectionMode() method.
PaymentSystem
  CONNECTION_MODE_NETWORK : String = connection_mode_network
[static] Constant used for enabling network connection mode in the setConnectionMode() method.
PaymentSystem

Constructor Detail

PaymentSystem()


public function PaymentSystem(target:IEventDispatcher = null)

Constructs a PaymentSystem object in order to listen for success and failure events.

Parameters

target:IEventDispatcher (default = null)

Method Detail

cancelSubscription()


public function cancelSubscription(purchaseID:String = null):void

Cancels the subscription of a digital good.

Parameters

purchaseID:String (default = null) — Purchase ID

The puchase ID of the subscription you wish to cancel. This ID is located within the Purchase object returned from a successful purchase() or getExistingPurchases() call.

checkExisting()


public function checkExisting(digitalGoodID:String = null, digitalGoodSKU:String = null):void

Checks whether a digital good's subscription is still active. Note: A subscription remains active until its subscription period ends, even if it's been canceled.

Parameters

digitalGoodID:String (default = null) — Digital Good ID

Only the ID or SKU of the digital good is required; it is not necessary to provide both. If both the ID and SKU are provided, then the ID takes precedence; the SKU is only used if the digital good cannot be located by the Payment Service based on the ID.

digitalGoodSKU:String (default = null) — Digital Good SKU

See description of digitalGoodID

getExistingPurchases()


public function getExistingPurchases(allowRefresh:Boolean = false):void

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

Parameters

allowRefresh:Boolean (default = false) — True if the Playbook 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. If connectionMode is set to CONNECTION_MODE_LOCAL then you cannot set allowRefresh = true or the Payment System will throw PaymentSystem.PAYMENT_ERROR as no network calls are allowed.

getPrice()


public function getPrice(digitalGoodID:String = null, digitalGoodSKU:String = null):void

Retrieves the price of a digital good

Parameters

digitalGoodID:String (default = null) — Digital Good ID

Only the ID or SKU of the digital good is required; it is not necessary to provide both. If both the ID and SKU are provided, then the ID takes precedence; the SKU is only used if the digital good cannot be located by the Payment Service based on the ID.

digitalGoodSKU:String (default = null) — Digital Good SKU

See description of digitalGoodID

purchase()


public function purchase(digitalGoodID:String = null, digitalGoodSKU:String = null, digitalGoodName:String = null, metaData:String = null, purchaseAppName:String = null, purchaseAppIcon:String = null):void

Initiates the purchase of a digital good.

Parameters

digitalGoodID:String (default = null) — Digital Good ID

Only the ID or SKU of the digital good to be purchased is required; it is not necessary to provide both. If both the ID and SKU are provided, then the ID takes precedence; the SKU is only used if the digital good cannot be located by the Payment Service based on the ID.

digitalGoodSKU:String (default = null) — Digital Good SKU

See description of digitalGoodID

Optional Arguments

digitalGoodName:String (default = null) — Digital Good Name

A digital good name should be provided in the case where a single ID/SKU represents multiple digital goods on the Payment Service server, and a more specific digital good name should be displayed 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 purchase time, the game application should override "My game level" with the name of the level being purchased. In this way, the end user is aware of exactly what they are purchasing on the purchase confirmation screen.

metaData:String (default = null) — Metadata

Metadata offers the application developer a way to store information about each purchase on the Payment Service server, and to retrieve that data using net.rim.blackberry.api.payment.PaymentSystem.getExistingPurchases(boolean). For example, assume a book vendor offers many 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, which uniquely identifies the digital good that was purchased. The entire list of purchased books can then be retrieved at any time by obtaining previous purchases using the getExistingPurchases method, filtering on the book's digital good Content ID, and finally enumerating the ISBNs in the metadata of each purchase.

purchaseAppName:String (default = null) — Purchase Application Name

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, showing the name and icon of the application the purchase is being made from (that is, the purchasing application). To customize the name and icon that are displayed, simply provide them as arguments. If the name and icon are not provided as arguments, then they are retrieved from the purchasing application's descriptor. However, 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 provide a name and icon as part of the purchase arguments.

purchaseAppIcon:String (default = null) — Purchase Application Icon

See description of purchaseAppName.

setConnectionMode()


public function setConnectionMode(mode:String):void

Sets the connection mode used in the application. If connection mode is set to local, 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 the connection mode is set to network, purchases and retrievals of existing purchases proceed normally, contacting the Payment Service server as necessary. This is the default connection mode, and applications in production should not modify it.

Parameters

mode:String

Event Detail

cancelSubscriptionError


cancelSubscriptionSuccess


checkExistingError


checkExistingSuccess


getExistingPurchasesError


getExistingPurchasesSuccess


getPriceError


getPriceSuccess


purchaseError


purchaseSuccess


Constant Detail

CONNECTION_MODE_LOCAL


public static const CONNECTION_MODE_LOCAL:String = connection_mode_local

Constant used for enabling local connection mode in the setConnectionMode() method.

CONNECTION_MODE_NETWORK


public static const CONNECTION_MODE_NETWORK:String = connection_mode_network

Constant used for enabling network connection mode in the setConnectionMode() method.

Examples

     
     import net.rim.blackberry.events.PaymentErrorEvent;
     import net.rim.blackberry.events.PaymentSuccessEvent;
     import net.rim.blackberry.payment.PaymentSystem;
     import net.rim.blackberry.payment.Purchase;
     
     private var paymentSystem:PaymentSystem;
     
     public function init():void {
         paymentSystem = new PaymentSystem();
         paymentSystem.addEventListener(PaymentSuccessEvent.PURCHASE_SUCCESS, purchaseSuccessHandler);
         paymentSystem.addEventListener(PaymentErrorEvent.PURCHASE_ERROR, purchaseErrorHandler);
         paymentSystem.addEventListener(PaymentSuccessEvent.GET_EXISTING_PURCHASES_SUCCESS, getExistingPurchasesSuccess);
         paymentSystem.addEventListener(PaymentErrorEvent.GET_EXISTING_PURCHASES_ERROR, getExistingPurchasesError);
         paymentSystem.setConnectionMode(PaymentSystem.CONNECTION_MODE_LOCAL);
     }
     
     public function purchase():void{                
         paymentSystem.purchase(null, "YOUR_DG_SKU", "Digital Good Name", "metadata", "Application Name", "http://www.rim.com/products/appworld_3col.jpg"); 
     }
     
     private function purchaseSuccessHandler(event:PaymentSuccessEvent):void{
         var purchase:Purchase = event.purchase;
         trace("Purchase Success - "+purchase.date+" : "+purchase.digitalGoodID+" : "+purchase.digitalGoodSKU+" : "+purchase.licenseKey+" : "+purchase.metaData+" : "+purchase.transactionID);
     }
     
     private function purchaseErrorHandler(event:PaymentErrorEvent):void{
          trace("Purchase Error - "+event.errorID+" : "+event.text+" ("+ event.errorInfo +")");
     }
     
     public function getExistingPurchases():void{
         paymentSystem.getExistingPurchases(); 
     }
     
     private function getExistingPurchasesSuccess(event:PaymentSuccessEvent):void{
         trace("Get Existing Purchases Success");
     
         var purchases:Array = event.existingPurchases;
         if(purchases.length == 0){
              trace("There are currently zero existing purchases");
         }else{
             for(var i:uint=0;i<purchases.length;i++){
                 var purchase:Purchase = purchases[i] as Purchase;
                 trace(purchase.date+" : "+purchase.digitalGoodID+" : "+purchase.digitalGoodSKU+" : "+purchase.licenseKey+" : "+purchase.metaData+" : "+purchase.transactionID);
             }    
         }    
     }
     
     private function getExistingPurchasesError(event:PaymentErrorEvent):void{
          trace("Get Existing Purchases Error - "+event.errorID+" : "+event.text+" ("+ event.errorInfo +")");
     }
     
     




comments powered by Disqus