Interupted / Pending / Acknowledging Purchases
Pending purchases are purchases that are currently still in progress and you are yet to deliver the appropriate product and call
Pending purchases may occur when a purchase is interupted, for example, the user left the application during a purchase, or they were initiated from an external source.
Purchases will remain in the pending purchases queue until you call
finishPurchase() with the appropriate purchase.
The main reason for this process is to allow you to verify the transaction with your server before delivering the product to your user and informing the billing service that the purchase has been delivered to the user.
From version 8, this process is applicable to Apple's In-App Purchases, Google Play Billing and Amazon In-App Purchases! The process continues to work across all services and platforms.
The services use slightly different terminology in their documentation you may need to be aware of:
- Apple uses "pending";
- Google uses "acknowledged", i.e. an un-acknowledged purchase is a pending purchase,
- when we finish a purchase we "acknowledge" the purchase;
- Amazon uses "fulfilled", i.e. an un-fulfillled purchase is a pending purchase,
- when we finish a purchase we "notify of fulfillment" of the purchase;
Get Pending Purchases
You can retrieve the list of pending purchases by calling the
getPendingPurchases() function. This will return the array of
Purchase objects that are currently 'pending'.
The pending purchases queue may not be initialised immediately, so you may find that in your
InAppBillingEvent.SETUP_SUCCESS event handler that the pending purchases queue is empty even though there are pending purchases.
The queue can be updated just after setup has completed which will be indicated by the normal
PurchaseEvent.PURCHASES_UPDATED event. This is particularly true on iOS/tvOS where the payment queue update (which populates the pending purchases) will occur a short time after setup succeeds.
We suggest you add event listeners for the
PurchaseEvent.PURCHASES_UPDATED event before you call
setup() to make sure you process all pending notifications at startup. You should also perform a check of the pending purchcases in your
InAppBillingEvent.SETUP_SUCCESS handler. Purchases that are already available at startup may not trigger a purchases updated event so you must handling purchases in both cases.
Note: Do not rely on the
PurchaseEvent.PURCHASES_UPDATEDevent as part of your flow. This event may not be dispatched if there aren't any pending purchases, or if they are available in the setup success handler.
Google Play Billing Acknowledgement
With Google Play Billing the call to
finishPurchase() performs the acknowledgement of the purchase.
It's very important to note that if you don't acknowledge a purchase (i.e. call finish purchase) it will be refunded.
Google Play supports purchasing products from inside of your app (in-app) or outside of your app (out-of-app). In order for Google Play to ensure a consistent purchase experience regardless of where the user purchases your product, you must acknowledge all purchases received through the Google Play Billing Library as soon as possible after granting entitlement to the user. If you do not acknowledge a purchase within three days, the user automatically receives a refund, and Google Play revokes the purchase.