PaymentManager

#include <bb/platform/PaymentManager>

To link against this class, add the following line to your .pro file: LIBS += -lbbplatform

Allows applications to manage digital good purchases and subscriptions.

PaymentManager allows BlackBerry device users to initiate the purchase of digital goods from within an 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.

The application interacts with the PaymentManager by creating a PaymentManager instance and calling the appropriate request method, which returns an appropriate PaymentReply subclass on success, or 0 on failure. When the request has been processed, the PaymentReply::finished() signal will be emitted on the returned reply instance and the appropriate *Finished() signal will be emitted on the PaymentManager instance. Results of the request, including success/failure, can be queried from the reply instance. See PaymentReply and subclasses for more on this.

To 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). The application name and icon can be customized by calling setApplicationName(const QString&) and setApplicationIconUrl(const QUrl&). If the name and icon are not provided, 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 this case, the purchasing application should explicitly provide a name and icon.

The amount of time that elapses before a reply finishes 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, etc.

Purchases are initiated with the requestPurchase() method.

A list of already-purchased digital goods can be retrieved with the requestExistingPurchases() method.

The price of a digital good or subscription can be obtained with the requestPrice() method. If the digital good is a subscription, then the additional details pertaining to the subscription can be obtained using PaymentManager::requestSubscriptionTerms().

The status and terms of subscriptions can be queried with the requestSubscriptionStatus and requestSubscriptionTerms() methods respectively. Note that subscriptions remain active until the subscription period ends, even if they have been canceled.

Subscription can be canceled with the requestCancelSubscription() method.

Note:

After the request has finished, it is the responsibility of the user to delete the reply object at an appropriate time. Do not directly delete it inside the slot connected to any of the finished signals. You can use the QObject::deleteLater() function.

,

The returned reply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The reply can be reparented if necessary (e.g., if it needs to live longer than the PaymentManager).

Since:

BlackBerry 10.0.0

Public Static Attributes Index

const QStringAPP_SUBSCRIPTION

Public Functions Index

PaymentManager (QObject *parent=0)
virtual ~PaymentManager ()
voidsetWindowGroupId (const QString &windowGroupId)
QStringwindowGroupId () const
voidsetApplicationName (const QString &applicationName)
QStringapplicationName () const
voidsetApplicationIconUrl (const QUrl &applicationIconUrl)
QUrlapplicationIconUrl () const
Q_INVOKABLE PurchaseReply *requestPurchase (const QString &digitalGoodId, const QString &digitalGoodSku=QString(), const QString &digitalGoodName=QString(), const QString &purchaseMetadata=QString(), const QVariantMap &extraParameters=QVariantMap())
Q_INVOKABLE ExistingPurchasesReply *requestExistingPurchases (bool forceServerRefresh=true)
Q_INVOKABLE PriceReply *requestPrice (const QString &digitalGoodId, const QString &digitalGoodSku=QString())
Q_INVOKABLE SubscriptionTermsReply *requestSubscriptionTerms (const QString &digitalGoodId, const QString &digitalGoodSku=QString())
Q_INVOKABLE SubscriptionStatusReply *requestSubscriptionStatus (const QString &digitalGoodId, const QString &digitalGoodSku=QString())
Q_INVOKABLE CancelSubscriptionReply *requestCancelSubscription (const QString &purchaseId)

Static Public Functions Index

voidsetConnectionMode (bb::platform::PaymentConnectionMode::Type connectionMode)

Signals Index

voidpurchaseFinished (bb::platform::PurchaseReply *reply)
voidexistingPurchasesFinished (bb::platform::ExistingPurchasesReply *reply)
voidpriceFinished (bb::platform::PriceReply *reply)
voidsubscriptionTermsFinished (bb::platform::SubscriptionTermsReply *reply)
voidsubscriptionStatusFinished (bb::platform::SubscriptionStatusReply *reply)
voidcancelSubscriptionFinished (bb::platform::CancelSubscriptionReply *reply)

Properties

QString windowGroupId

Represents window group id.

The window group id for the calling app's main window

Since:

BlackBerry 10.2.0

QString applicationName

Represents application name.

Application name

Since:

BlackBerry 10.2.0

QUrl applicationIconUrl

Represents application icon url.

Application icon url

Since:

BlackBerry 10.2.0

Public Static Attributes

const QString APP_SUBSCRIPTION ()

Used as a parameter to requestSubscriptionStatus when checking the status of an app level subscription.

Since:

BlackBerry 10.0.0

Public Functions

PaymentManager (

Constructs a new PaymentManager instance.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

virtual~PaymentManager ()

Destructor.

Since:

BlackBerry 10.0.0

void setWindowGroupId (

Sets the window group id.

Use this method to set the window group id. The window group id is required by the PaymentManager so that it can display dialog windows properly. Depending on the type of application, the window group id can be set and/or retrieved in different ways. For example, a Cascades application will set the window group id upon application start up. This value can then be retrieved using bb::cascades::Application::mainWindow()->groupId(), and passed to the PaymentManager using this method.

Parameters
windowGroupId

The window group id to set.
Since:

BlackBerry 10.0.0

QString windowGroupId ()

Gets the window group id.

Gets the window group id, as set by calling setWindowGroupId().

Return:

The window group id.

Since:

BlackBerry 10.0.0

void setApplicationName (

Sets the application name.

The application name is displayed on a banner shown to the user during the purchase process. If the name is not provided, then it is 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.

Parameters
applicationName

The application name to set.
Since:

BlackBerry 10.0.0

QString applicationName ()

Gets the application name.

Gets the application name, as set by calling setApplicationName().

Return:

The application name.

Since:

BlackBerry 10.0.0

void setApplicationIconUrl (
  • const QUrl &applicationIconUrl)

Sets the application icon URL.

This icon is displayed on a banner shown to the user during the purchase process. The icon must be available through an external website, with a URL of the form "http://...". If the icon is not provided, then it is 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 an icon.

Parameters
applicationIconUrl

The application icon to set.
Since:

BlackBerry 10.0.0

QUrl applicationIconUrl ()

Gets the application icon URL.

Gets the application icon URL, as set by calling setApplicationIconUrl().

Return:

The application icon URL.

Since:

BlackBerry 10.0.0

Q_INVOKABLE PurchaseReply * requestPurchase (

Requests the purchase of a digital good or subscription.

Only one of the ID or SKU of the digital good or subscription is required in order to request a purchase. If both are provided, then the ID takes precedence, and the SKU will only be used in case the ID cannot be found. To use only the SKU, pass an empty string as the digitalGoodId.

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 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. This way, the end user is aware of exactly what they are purchasing on the purchase confirmation screen.

Purchase metadata offers the application developer a way to store information about each purchase on the Payment server, and to retrieve that data via requestExistingPurchases(). 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 purchase 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 via the requestExistingPurchases() method, filtering on the book's digital good ID, and finally enumerating the ISBNs in the purchase metadata.

Extra parameters, in the form of key/value pairs in a QVariantMap, can be associated with the purchase request. Any type with a valid QVariant::toString() can be used as a value in the map. Output parameters may be present in the PurchaseReceipt and can be retrieved via PurchaseReceipt::extraParameters(). Input and output parameters may not be directly related (i.e., output parameters may be present in the PurchaseReceipt where none were input, or vice versa). Extra parameters are only relevant to the initial purchase (and would not be present, for example, in PurchaseReceipt objects returned by requestExistingPurchases()).

If the request is successfully made, a PurchaseReply is returned. The returned object can be used to obtain information about the request, including when the request has finished. See PurchaseReply for more on this.

Determining when the request has finished can be done through the PurchaseReply::finished() signal or the PaymentManager::purchaseFinished() signal.

Note:

After the request has finished, it is the responsibility of the user to delete the PurchaseReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned PurchaseReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The PurchaseReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
digitalGoodId

The digital good ID. If empty, the ID is ignored and the SKU is used instead.

digitalGoodSku

The digital good SKU.

digitalGoodName

The digital good name. If empty, the name will be pulled from the Payment server.

purchaseMetadata

Optional information to associate with a successful purchase.

extraParameters

Set of extra parameters to associate with a purchase request.
Return:

A new PurchaseReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE ExistingPurchasesReply * requestExistingPurchases (
  • boolforceServerRefresh)

Requests the list of previous purchases.

If the request is successfully made, an ExistingPurchasesReply is returned. The returned object can be used to obtain information about the request, including when the request has finished.
See:

ExistingPurchasesReply for more on this.

Determining when the request has finished can be done through the ExistingPurchasesReply::finished() signal or the PaymentManager::existingPurchasesFinished() signal.
Note:

After the request has finished, it is the responsibility of the user to delete the ExistingPurchasesReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned ExistingPurchasesReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The ExistingPurchasesReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
forceServerRefresh

If true, the list of purchases is retrieved from the Payment server; otherwise, the current cached list of purchases is returned.
Return:

A new ExistingPurchasesReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE PriceReply * requestPrice (

Requests the price of a digital good or subscription.

Only one of the ID or SKU of the digital good or subscription is required in order to retrieve the price. If both are provided, then the ID takes precedence, and the SKU will only be used if the ID cannot be found. To use only the SKU, pass an empty string as the digitalGoodId.

If the request is successfully made, a PriceReply is returned. The returned object can be used to obtain information about the request, including when the request has finished.
See:

PriceReply for more on this.

Determining when the request has finished can be done through the PriceReply::finished() signal or the PaymentManager::priceFinished() signal.
Note:

After the request has finished, it is the responsibility of the user to delete the PriceReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned PriceReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The PriceReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
digitalGoodId

The digital good ID. If empty, the ID is ignored and the SKU is used instead.

digitalGoodSku

The digital good SKU.
Return:

A new PriceReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE SubscriptionTermsReply * requestSubscriptionTerms (

Requests the terms of a subscription.

The subscription terms include the initial subscription period, renewal price, and renewal period.

Only one of the ID or SKU of the digital good or subscription is required in order to retrieve the subscription terms. If both are provided, then the ID takes precedence, and the SKU will only be used in case the ID cannot be found. To use only the SKU, pass an empty string as the digitalGoodId.

If the request is successfully made, a SubscriptionTermsReply is returned. The returned object can be used to obtain information about the request, including when the request has finished.
See:

SubscriptionTermsReply for more on this.

Determining when the request has finished can be done through the SubscriptionTermsReply::finished signal() or the PaymentManager::subscriptionTermsFinished() signal.
Note:

After the request has finished, it is the responsibility of the user to delete the SubscriptionTermsReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned SubscriptionTermsReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The SubscriptionTermsReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
digitalGoodId

The digital good ID. If empty, the ID is ignored and the SKU is used instead.

digitalGoodSku

The digital good SKU.
Return:

A new SubscriptionTermsReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE SubscriptionStatusReply * requestSubscriptionStatus (

Requests whether a subscription is active.

If the request is successfully made, a SubscriptionStatusReply is returned. The returned object can be used to obtain information about the request, including when the request has finished.
See:

SubscriptionStatusReply for more on this.

Determining when the request has finished can be done through the SubscriptionStatusReply::finished signal or the PaymentManager::subscriptionStatusFinished signal.
Note:

After the request has finished, it is the responsibility of the user to delete the SubscriptionStatusReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned SubscriptionStatusReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The SubscriptionStatusReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
digitalGoodId

The digital good ID. If empty, the ID is ignored and the SKU is used instead. To check the status of a subscription app (not a digital good), use PaymentManager::APP_SUBSCRIPTION as the digitalGoodId parameter.

digitalGoodSku

The digital good SKU.
Return:

A new SubscriptionStatusReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE CancelSubscriptionReply * requestCancelSubscription (

Requests cancellation of a subscription.

To cancel a subscription to a digital good, obtain the purchase id from when the subscription was purchased. This can be obtained from the original purchase or from the list of previous successful purchases (as retrieved using requestExistingPurchases()).

If the request is successfully made, a CancelSubscriptionReply is returned. The returned object can be used to obtain information about the request, including when the request has finished.
See:

CancelSubscriptionReply for more on this.

Determining when the request has finished can be done through the CancelSubscriptionReply::finished() signal or the PaymentManager::cancelSubscriptionFinished() signal.
Note:

Canceled subscriptions remain active until the subscription period ends.

,

After the request has finished, it is the responsibility of the user to delete the CancelSubscriptionReply object at an appropriate time. Do not directly delete it inside the slot connected to one of the finished signals. You can use the QObject::deleteLater() function.

,

The returned CancelSubscriptionReply is a child of the PaymentManager to avoid memory leaks if the caller fails to delete it manually. The CancelSubscriptionReply can be reparented if necessary (e.g. if it needs to live longer than the PaymentManager).

Parameters
purchaseId

The purchase id from when the subscription was purchased.
Return:

A new CancelSubscriptionReply if the request was successfully made, or 0 if the request could not be sent due to an internal error.

Since:

BlackBerry 10.0.0

Static Public Functions

void setConnectionMode (

Sets the global Payment API connection mode.

The Payment API can be put into a PaymentConnectionMode::Test connection mode for easier local testing.
See:

PaymentConnectionMode::Test for more on this.

The default connection mode is PaymentConnectionMode::Production.
Note:

The connection mode affects the Payment API as a whole, and is not linked to a PaymentManager instance. Changing connections modes while any Payment operations are outstanding is unsupported and will result in undefined behavior. Ideally, this function will only be called at startup, before any PaymentManager instances are created.

,

PaymentConnectionMode::Test should not be used in production code.

Parameters
connectionMode

The new connection mode for the Payment API.
Since:

BlackBerry 10.0.0

Signals

void purchaseFinished (

Emitted when a request initiated by requestPurchase() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the PurchaseReply object at an appropriate time.

Parameters
reply

The PurchaseReply that was returned by requestPurchase().
Since:

BlackBerry 10.0.0

void existingPurchasesFinished (

Emitted when a request initiated by requestExistingPurchases() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the ExistingPurchasesReply object at an appropriate time.

Parameters
reply

The ExistingPurchasesReply that was returned by requestExistingPurchases().
Since:

BlackBerry 10.0.0

void priceFinished (

Emitted when a request initiated by requestPrice() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the PriceReply object at an appropriate time.

Parameters
reply

The PriceReply that was returned by requestPrice().
Since:

BlackBerry 10.0.0

void subscriptionTermsFinished (

Emitted when a request initiated by requestSubscriptionTerms() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the SubscriptionTermsReply object at an appropriate time.

Parameters
reply

The SubscriptionTermsReply that was returned by requestSubscriptionTerms().
Since:

BlackBerry 10.0.0

void subscriptionStatusFinished (

Emitted when a request initiated by requestSubscriptionStatus() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the SubscriptionStatusReply object at an appropriate time.

Parameters
reply

The SubscriptionStatusReply that was returned by requestSubscriptionStatus().
Since:

BlackBerry 10.0.0

void cancelSubscriptionFinished (

Emitted when a request initiated by requestCancelSubscription() has finished.

Note:

After the request has finished, it is the responsibility of the user to delete the CancelSubscriptionReply object at an appropriate time.

Parameters
reply

The CancelSubscriptionReply that was returned by requestCancelSubscription().
Since:

BlackBerry 10.0.0