Development Guide

Local Navigation

Documentazione sui prodotti  >  Documentazione per gli sviluppatori  >  Servizio a pagamento  >  Development Guide Payment Service SDK - 1.8

Initiating a purchase

Before initiating a purchase by invoking PaymentEngine.purchase(), create a PurchaseArguments object to represent the digital goods. The Payment Service API provides a builder class for creating a PurchaseArguments object on the device.

You can invoke the appropriate methods on the PurchaseArgumentsBuilder object depending on the information that you provide with the purchase request. For a purchase to be authenticated, you must provide either the SKU or the ID for the digital goods. The SKU is a value that you specify when you register the digital goods in the vendor portal for the BlackBerry App World storefront. You can invoke DigitalGoods.get() to retrieve the SKUs for the digital goods. To determine which SKUs are available during runtime, call DigitalGoods.get(). The ID is an identifier that is assigned to your digital goods in the vendor portal.

If the purchase request is successful, a PurchaseResult object is returned, which contains information about the purchase. If the purchase is unsuccessful, an exception is thrown.

Code sample: Creating a PurchaseArguments object and initiating a purchase

PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
    .withDigitalGoodId( "1234" )
    .withDigitalGoodName( "My Product" )
    .withDigitalGoodSku( "Ab34t2eC" )
    .withPurchasingAppName( "My Application" );
try 
{
    PurchaseResult result = engine.purchase(arguments.build());
} 
catch (IllegalArgumentException iae) 
{
    //code that is executed if an exception is thrown
} 
catch (PaymentException pe) 
{
    //code that is executed if an exception is thrown
}

Arguments for purchases

The following table describes the arguments that you can pass to PaymentEngine.purchase().

Argument

Description

digitalGoodSKU

  • Required argument (can be substituted with the ID).
  • An identifier that you assign to digital goods when you register the digital goods in the BlackBerry App World vendor portal.
  • An alphanumeric string that can contain hyphens (-) and underscores (_), must not contain only numbers, and is 5 to 100 characters in length.
  • If specified along with the ID, the SKU is ignored.

digitalGoodID

  • Required argument (can be substituted with the SKU).
  • An identifier that the vendor portal assigns to your digital goods after you register the digital goods in the vendor portal.
  • If specified along with the SKU, the SKU is ignored.

digitalGoodName

  • Optional argument.
  • A name that overrides the name that you specified for the digital goods when you registered the digital goods in the vendor portal (the registered name might be a generic name that describes an entire batch of digital goods).
  • Appears on the purchase confirmation dialogs in your application to provide users with context for what they are purchasing.

metadata

  • Optional argument.
  • A unique identifier that is required if you need to differentiate between the digital goods that reference the same SKU (for example, if your application sells eBooks, the identifier could be an ISBN number).
  • Returned with each Purchase object when you make a getExistingPurchases() call.

purchaseAppName

  • Optional argument.
  • Overrides the application name retrieved from the application descriptor.
  • Should always be specified if the name of the application, as it appears on the Home screen of the device, can change dynamically (for example, if the application name changes when the icon for the application receives focus).
  • Appears on the purchase confirmation dialogs in your application to provide users with context for what they are purchasing.

purchaseAppIcon

  • Optional argument.
  • Overrides the icon for the application that the purchase request originates from .
  • Must be 100 x 100 pixels.
  • Must be loaded from an external website.
  • Should always be specified if the icon for the application, as it appears on the Home screen of the device, can change dynamically (for example, if the icon changes when new content is available in the application).
  • Appears on the purchase confirmation dialogs in your application to provide users with context for what they are purchasing.
Back To Top
Next topic: Managing subscriptions
Previous topic: Retrieving information about past purchases

Was this information helpful? Send us your comments.