SKPaymentQueue Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/StoreKit.framework |
| Availability | Available in iOS 3.0 and later. |
| Companion guide | |
| Declared in | SKPaymentQueue.h |
Overview
The SKPaymentQueue class provides a queue of payment transactions to be processed by the App Store. The payment queue communicates with the App Store and presents a user interface so that the user can authorize payment. The contents of the queue are persistent between launches of your app.
To process a payment, first attach at least one observer object to the queue. Then, add a payment object for the item the user wants to purchase. Each time you add a payment object, the queue creates a transaction object to process that payment and enqueues it to be processed. After payment is fulfilled, the queue updates the transaction object and then calls any observer objects to provide them the updated transaction. Your observer should process the transaction and then remove it from the queue.
The exact mechanism you use to process a processed transaction depends on the design of your app and the product being purchased. Here are a few common examples:
If the product is a feature already built into your app, then to process the transaction, your app would enable the feature.
If the product includes downloadable content provided by the App Store, your app would retrieve the
SKDownloadobjects from the transaction and ask the payment queue to download them. You would provide the actual content files to be served by the App Store to iTunes Connect when you create the product information.If the product represents downloadable content provided by your own server, your app might open a network connection to your server and download the content from there.
For more information on designing the payment processing portion of your app, see In-App Purchase Programming Guide.
Tasks
Determining Whether the User Can Make Payments
Getting the Queue
Adding and Removing the Observer
Managing Transactions
Restoring Purchases
Downloading Content
Properties
transactions
Returns an array of pending transactions. (read-only)
Discussion
The value of this property is undefined when there are no observers attached to the payment queue.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
SKPaymentQueue.hClass Methods
canMakePayments
Returns whether the user is allowed to make payments.
Return Value
YES if the user is allowed to authorize payment. NO if they do not have permission.
Discussion
An iPhone can be restricted from accessing the Apple App Store. For example, parents can restrict their children’s ability to purchase additional content. Your application should confirm that the user is allowed to authorize payments before adding a payment to the queue. Your application may also want to alter its behavior or appearance when the user is not allowed to authorize payments.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.hdefaultQueue
Returns the singleton payment queue instance.
Return Value
The shared payment queue.
Discussion
Applications do not create a payment queue. Instead, they retrieve the singleton queue by calling this class method.
Special Considerations
The payment queue is not available in Simulator. Attempting to retrieve the payment queue logs a warning.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.hInstance Methods
addPayment:
Adds a payment request to the queue.
Parameters
- payment
A payment request.
Discussion
An application should always have at least one observer of the payment queue before adding payment requests.
The payment request must have a product identifier registered with the Apple App Store and a quantity greater than 0. If either property is invalid, addPayment: throws an exception.
When a payment request is added to the queue, the payment queue processes that request with the Apple App Store and arranges for payment from the user. When that transaction is complete or if a failure occurs, the payment queue sends the SKPaymentTransaction object that encapsulates the request to all transaction observers.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.haddTransactionObserver:
Adds an observer to the payment queue.
Parameters
- observer
The observer to add to the queue.
Discussion
Your application should add an observer to the payment queue during application initialization. If there are no observers attached to the queue, the payment queue does not synchronize its list of pending transactions with the Apple App Store, because there is no observer to respond to updated transactions.
If an application quits when transactions are still being processed, those transactions are not lost. The next time the application launches, the payment queue will resume processing the transactions. Your application should always expect to be notified of completed transactions.
If more than one transaction observer is attached to the payment queue, no guarantees are made as to the order they will be called in. It is safe for multiple observers to call finishTransaction:, but not recommended. It is recommended that you use a single observer to process and finish the transaction.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.hcancelDownloads:
Removes a set of downloads from the download list.
Parameters
- downloads
An array of
SKDownloadobjects to cancel.
Availability
- Available in iOS 6.0 and later.
Declared In
SKPaymentQueue.hfinishTransaction:
Completes a pending transaction.
Parameters
- transaction
The transaction to finish.
Discussion
Your application should call this method from a transaction observer that received a notification from the payment queue. Calling finishTransaction: on a transaction removes it from the queue. Your application should call finishTransaction: only after it has successfully processed the transaction and unlocked the functionality purchased by the user.
Calling finishTransaction: on a transaction that is in the SKPaymentTransactionStatePurchasing state throws an exception.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
SKPaymentQueue.hpauseDownloads:
Pauses a set of downloads.
Parameters
- downloads
An array of
SKDownloadobjects to pause.
Availability
- Available in iOS 6.0 and later.
Declared In
SKPaymentQueue.hremoveTransactionObserver:
Removes an observer from the payment queue.
Parameters
- observer
The observer to remove.
Discussion
If there are no observers attached to the queue, the payment queue does not synchronize its list of pending transactions with the Apple App Store, because there is no observer to respond to updated transactions.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.hrestoreCompletedTransactions
Asks the payment queue to restore previously completed purchases.
Discussion
Your application calls this method to restore transactions that were previously finished so that you can process them again. For example, your application would use this to allow a user to unlock previously purchased content onto a new device.
When you create a new product to be sold in your store, you choose whether that product can be restored or not. See the In-App Purchase Programming Guide for more information.
The payment queue will deliver a new transaction for each previously completed transaction that can be restored. Each transaction includes a copy of the original transaction.
After the transactions are delivered, the payment queue calls the observer’s paymentQueueRestoreCompletedTransactionsFinished: method. If an error occurred while restoring transactions, the observer will be notified through its paymentQueue:restoreCompletedTransactionsFailedWithError: method.
Availability
- Available in iOS 3.0 and later.
Declared In
SKPaymentQueue.hresumeDownloads:
Resumes a set of downloads.
Parameters
- downloads
An array of
SKDownloadobjects to resume.
Availability
- Available in iOS 6.0 and later.
Declared In
SKPaymentQueue.hstartDownloads:
Adds a set of downloads to the download list.
Parameters
- downloads
An array of
SKDownloadobjects to begin downloading.
Discussion
In order for a download object to be queued, it must be associated with a transaction that has been successfully purchased, but not yet finished.
Availability
- Available in iOS 6.0 and later.
Declared In
SKPaymentQueue.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)