Payments Library

File: JVE.Payment.pas Inheritance: TComponent ⬅ TJVEPayment

This component allows the user to request payments from the user. It supports native payments, made through the AppStore (on iOS and Mac OS X) and Google Play (on Android; not available in Delphi XE5), and PayPal payments (on all platforms).

Unlike other classes, due to Apple’s requirements (i.e. digital goods must be bought via an in‑app payments; non-digital goods must not be an in-app purchase), this class will not fallback to PayPal automatically. To use PayPal on a mobile platform, the payment item must define PayPal in its Platforms list and it must not define the mobile platform.

 

The component is capable of managing all In-App Payments required by an application and it is usually more efficient to have one such component taking care of all the payments, rather than creating separate components for various payments. Notice, this component works with remote servers, so processing is mostly not immediate (sometimes taking several seconds to complete).

You can still create multiple instances of this component, if, for example, you need to create PayPal payments to varying recipients.

The diagram of properties, this component exposed is as follows:

jvepayments

The properties of each payment are as follows:

  • iOSIdentifier – the unique identifies of the payment, to be used to access Apple Store from an iOS device.
  • MacIdentifier – the unique identifies of the payment, to be used to access Apple Store from a Mac device.
  • PPIdentifier – the unique identifies of the payment, used for PayPal: could be any unique identifier of the payment, for the item (unique for the user, not globally unique across users).
  • Persistent – specifies whether the item is persistent (buy once, use forever or “non-consumable”), like “unlock all levels”, or consumable (can be bought several times), like “3 more lives”. Android products are always persistent; use Consume procedure to consume them.
  • Platforms – the list of platforms, which support this payment.
  • Title – this is the PayPal item; for additional use, see below section Caching Prices.
  • PriceCache – a read/only property; see below section Caching Prices.
  • PPCurrency and PPPrice – the price and currency of the payment, for PayPal use. Since PayPal does not allow products to be predefined, you need to supply the amount to charge for each payment. You should keep this figure accurate, because it is also used in Google Analytics reporting, when the real price of the item is not known.
  • PPType – specifies the type of the item: ptGoods, ptServices or ptDigitalGoods. Notice, as of the writing of this document, PayPal used a special site for Digital Goods, which failed miserably in most browsers, so its use is strictly discouraged.
  • Purchased – a read/only property, which indicates whether a Persistent item was purchased. Notice, this property does not contact the server to verify the purchase, only local storage; see RestorePurchases method for that function.

 

For the component itself, the properties are:

  • Items – the collection of In-App Payments this component exposes.
  • PPAPIApplicationId, PPAPIUserId, PPAPIPassword, PPAPISignature and PPAPISandbox – these properties control the way the control connects to PayPal services; you don’t need to change them, if you are not using PayPal payments. See Configuring PayPal Payments section below for more details.
  • PPRecipientEmail – the email of the payment recipient.
  • AndroidLicense – the license key of the app, as generated within the available console.
  • ShowShade – specifies whether the app is shaded, when it processes requests. See In‑Progress App Shading section below.

 

Only one method is provided for the item: Buy, which initiates the purchase process for the item. The process runs in background; any inquiries needed are presented in modal dialogs. See events section below to learn how to respond to issues in this process.

The following methods are provided for the component:

  • CanBuyNatively – this class function returns whether buying natively is supported. On platforms, which only support PayPal always returns True.
  • Buy(Id) – a convenience method: calls the Buy method of the item, identified by is Identifier; returns True if the identifier was found, returns False
  • RestorePurchases – restores any previously made purchases (only for non-consumable items), see Persistent Products for more details.
  • CachePrices – See Caching Prices section below.
  • IsBusy – Indicates whether the component is currently busy restoring or buying some items; OnFinished will be called when done.

 

The following events are exposed by this component and by items:

  • OnFinished – called after a buy or restore purchases request is finished processing. This method is guaranteed to be called after every Busy period. The default behavior is to present an error message, unless the Status returned is psSuccess or psCancelled.
  • OnPurchased – called when an item was purchased (or its purchase restored). You must always listen to this event, even if you have not requested a purchase (if previous session did, but failed, Apple might deliver the product in the next session without any request).
  • OnPriceCached – see Caching Prices.