SKPaymentQueue Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/StoreKit.framework
Availability
Available in OS X v10.7 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:

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)

@property(nonatomic, readonly) NSArray *transactions
Discussion

The value of this property is undefined when there are no observers attached to the payment queue.

Availability
  • Available in OS X v10.7 and later.
Declared In
SKPaymentQueue.h

Class Methods

canMakePayments

Returns whether the user is allowed to make payments.

+ (BOOL)canMakePayments
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

defaultQueue

Returns the singleton payment queue instance.

+ (SKPaymentQueue *)defaultQueue
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

Instance Methods

addPayment:

Adds a payment request to the queue.

- (void)addPayment:(SKPayment *)payment
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

addTransactionObserver:

Adds an observer to the payment queue.

- (void)addTransactionObserver:(id<SKPaymentTransactionObserver>)observer
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

cancelDownloads:

Removes a set of downloads from the download list.

- (void)cancelDownloads:(NSArray *)downloads
Parameters
downloads

An array of SKDownload objects to cancel.

Availability
  • Available in OS X v10.8 and later.
Declared In
SKPaymentQueue.h

finishTransaction:

Completes a pending transaction.

- (void)finishTransaction:(SKPaymentTransaction *)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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

pauseDownloads:

Pauses a set of downloads.

- (void)pauseDownloads:(NSArray *)downloads
Parameters
downloads

An array of SKDownload objects to pause.

Availability
  • Available in OS X v10.8 and later.
Declared In
SKPaymentQueue.h

removeTransactionObserver:

Removes an observer from the payment queue.

- (void)removeTransactionObserver:(id<SKPaymentTransactionObserver>)observer
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

restoreCompletedTransactions

Asks the payment queue to restore previously completed purchases.

- (void)restoreCompletedTransactions
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 OS X v10.7 and later.
Declared In
SKPaymentQueue.h

restoreCompletedTransactionsWithApplicationUsername:

Asks the payment queue to restore previously completed purchases, providing an opaque identifier for the user’s account.

- (void)restoreCompletedTransactionsWithApplicationUsername:(NSString *)username
Parameters
username

An opaque identifier for the user’s account on your system.

Availability
  • Available in OS X v10.9 and later.
Declared In
SKPaymentQueue.h

resumeDownloads:

Resumes a set of downloads.

- (void)resumeDownloads:(NSArray *)downloads
Parameters
downloads

An array of SKDownload objects to resume.

Availability
  • Available in OS X v10.8 and later.
Declared In
SKPaymentQueue.h

startDownloads:

Adds a set of downloads to the download list.

- (void)startDownloads:(NSArray *)downloads
Parameters
downloads

An array of SKDownload objects 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 OS X v10.8 and later.
Declared In
SKPaymentQueue.h