Mac Developer Library

Developer

StoreKit Framework Reference SKPaymentQueue Class Reference

Options
Deployment Target:

On This Page
Language:

SKPaymentQueue

Inheritance


Conforms To


Import Statement


Swift

import StoreKit

Objective-C

@import StoreKit;

Availability


Available in OS X v10.7 and later.

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 SKDownload objects 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.

  • Returns whether the user is allowed to make payments.

    Declaration

    Swift

    class func canMakePayments() -> Bool

    Objective-C

    + (BOOL)canMakePayments

    Return Value

    YEStrue if the user is allowed to authorize payment. NOfalse 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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the singleton payment queue instance.

    Declaration

    Swift

    class func defaultQueue() -> SKPaymentQueue!

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Adds an observer to the payment queue.

    Declaration

    Swift

    func addTransactionObserver(_ observer: SKPaymentTransactionObserver!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Removes an observer from the payment queue.

    Declaration

    Swift

    func removeTransactionObserver(_ observer: SKPaymentTransactionObserver!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Returns an array of pending transactions. (read-only)

    Declaration

    Swift

    var transactions: [AnyObject]! { get }

    Objective-C

    @property(readonly) NSArray *transactions

    Discussion

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

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Adds a payment request to the queue.

    Declaration

    Swift

    func addPayment(_ payment: SKPayment!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Completes a pending transaction.

    Declaration

    Swift

    func finishTransaction(_ transaction: SKPaymentTransaction!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

  • Asks the payment queue to restore previously completed purchases.

    Declaration

    Swift

    func restoreCompletedTransactions()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func restoreCompletedTransactionsWithApplicationUsername(_ username: String!)

    Objective-C

    - (void)restoreCompletedTransactionsWithApplicationUsername:(NSString *)username

    Parameters

    username

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

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.9 and later.

  • Adds a set of downloads to the download list.

    Declaration

    Swift

    func startDownloads(_ downloads: [AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.8 and later.

  • Removes a set of downloads from the download list.

    Declaration

    Swift

    func cancelDownloads(_ downloads: [AnyObject]!)

    Objective-C

    - (void)cancelDownloads:(NSArray *)downloads

    Parameters

    downloads

    An array of SKDownload objects to cancel.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.8 and later.

  • Pauses a set of downloads.

    Declaration

    Swift

    func pauseDownloads(_ downloads: [AnyObject]!)

    Objective-C

    - (void)pauseDownloads:(NSArray *)downloads

    Parameters

    downloads

    An array of SKDownload objects to pause.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.8 and later.

  • Resumes a set of downloads.

    Declaration

    Swift

    func resumeDownloads(_ downloads: [AnyObject]!)

    Objective-C

    - (void)resumeDownloads:(NSArray *)downloads

    Parameters

    downloads

    An array of SKDownload objects to resume.

    Import Statement

    Objective-C

    @import StoreKit;

    Swift

    import StoreKit

    Availability

    Available in OS X v10.8 and later.