iOS Developer Library — Prerelease

Developer

PassKit Framework Reference PKPassLibrary Class Reference

Options
Deployment Target:

On This Page
Language:

PKPassLibrary

The PKPassLibrary class provides an interface to the user’s library of passes.

The PKPassLibrary is not thread-safe. Use instances of this class only on a single thread.

  • Indicates whether the pass library is available.

    Declaration

    Swift

    class func isPassLibraryAvailable() -> Bool

    Objective-C

    + (BOOL)isPassLibraryAvailable

    Return Value

    YEStrue if the pass library is available; otherwise, NOfalse.

    Discussion

    This method is provided because the pass library may be unavailable even if the PKPassLibrary class exists.

    Availability

    Available in iOS 6.0 and later.

  • Returns the passes in the user’s pass library to which the app has access.

    Declaration

    Swift

    func passes() -> [PKPass]

    Objective-C

    - (NSArray<PKPass *> * nonnull)passes

    Return Value

    The passes in the user’s pass library.

    Discussion

    Your app only has access to certain passes, based on its entitlements. Passes that your app doesn’t have access to are not returned.

    The ordering of the passes is not fixed; calling this method multiple times may return the same passes but in a different order.

    Availability

    Available in iOS 6.0 and later.

  • Returns the pass with the given pass type identifier and serial number.

    Declaration

    Swift

    func passWithPassTypeIdentifier(_ identifier: String, serialNumber serialNumber: String) -> PKPass?

    Objective-C

    - (PKPass * nullable)passWithPassTypeIdentifier:(NSString * nonnull)identifier serialNumber:(NSString * nonnull)serialNumber

    Parameters

    identifier

    The pass’s pass type identifier.

    serialNumber

    The pass’s serial number.

    Return Value

    The pass with the given pass type identifier and serial number, or nil if there is no such pass or if the app doesn’t have the appropriate entitlement.

    Availability

    Available in iOS 6.0 and later.

  • Returns the passes of the specified pass type.

    Declaration

    Swift

    func passesOfType(_ passType: PKPassType) -> [PKPass]

    Objective-C

    - (NSArray<PKPass *> * nonnull)passesOfType:(PKPassType)passType

    Parameters

    passType

    One of the pass types in PKPassType.

    Return Value

    An array of passes of the specified type.

    Availability

    Available in iOS 8.0 and later.

  • Presents lightweight UI for adding multiple passes at once.

    Declaration

    Swift

    func addPasses(_ passes: [PKPass], withCompletionHandler completion: ((PKPassLibraryAddPassesStatus) -> Void)?)

    Objective-C

    - (void)addPasses:(NSArray<PKPass *> * nonnull)passes withCompletionHandler:(void (^ nullable)(PKPassLibraryAddPassesStatus status))completion

    Parameters

    passes

    The passes being added.

    completion

    The completion block called after the user selects an action. This block takes the following parameters:

    status

    Indicates whether the passes were added. If the user selects to review the passes, this status is set to PKPassLibraryShouldReviewPasses. In this case, you must present an instance of PKAddPassesViewController to let the user review and add the passes.

    Discussion

    Use this method when the user has already indicated to your app which passes should be added to Passbook—for example, by selecting from a list. The user is asked to confirm the action, but is not shown each individual pass being added. If you want to let the user review and select individual passes from an array of passes, use an instance of PKAddPassesViewController instead.

    Availability

    Available in iOS 7.0 and later.

  • Indicates whether the user’s pass library contains the specified pass.

    Declaration

    Swift

    func containsPass(_ pass: PKPass) -> Bool

    Objective-C

    - (BOOL)containsPass:(PKPass * nonnull)pass

    Parameters

    pass

    The pass being queried.

    Return Value

    YEStrue if the user’s pass library contains the pass; otherwise, NOfalse.

    Discussion

    This method lets you determine that the pass library contains a pass even though your app wouldn’t be able to read or modify the pass. For example, an email client would not have entitlements to read or write any passes from the library.

    Your app can use this method to provide a UI indicating whether a pass is already in the library.

    Availability

    Available in iOS 6.0 and later.

  • Returns a list of passes stored on a remote device.

    Declaration

    Swift

    func remotePaymentPasses() -> [PKPaymentPass]

    Objective-C

    - (NSArray<PKPaymentPass *> * nonnull)remotePaymentPasses

    Return Value

    An array containing all the passes stored on a device that is paired with the current iOS device (for example, Apple Watch).

    Availability

    Available in iOS 9.0 and later.

  • Removes the pass from the user’s pass library.

    Declaration

    Swift

    func removePass(_ pass: PKPass)

    Objective-C

    - (void)removePass:(PKPass * nonnull)pass

    Parameters

    pass

    The pass being removed.

    Discussion

    This method does nothing if your app doesn’t have the appropriate entitlement.

    Availability

    Available in iOS 6.0 and later.

  • Replaces a pass in the user’s pass library with the given pass.

    Declaration

    Swift

    func replacePassWithPass(_ pass: PKPass) -> Bool

    Objective-C

    - (BOOL)replacePassWithPass:(PKPass * nonnull)pass

    Parameters

    pass

    The new pass.

    Return Value

    YEStrue if the pass was replaced successfully; otherwise NOfalse.

    Discussion

    The new pass replaces the existing pass with the same pass type identifier and serial number. If there is no such pass in the user’s pass library, the replacement fails.

    Availability

    Available in iOS 6.0 and later.

  • Determines whether the app can add a card to Apple Pay for the provided primary account identifier.

    Declaration

    Swift

    func canAddPaymentPassWithPrimaryAccountIdentifier(_ primaryAccountIdentifier: String) -> Bool

    Objective-C

    - (BOOL)canAddPaymentPassWithPrimaryAccountIdentifier:(NSString * nonnull)primaryAccountIdentifier

    Parameters

    primaryAccountIdentifier

    A unique identifier for the underlying funding primary account number (PAN). Note: this is not the PAN itself.

    Return Value

    YEStrue, if a pass can be added to Apple Pay.

    Availability

    Available in iOS 9.0 and later.

  • Activates a payment pass using the provided activation code.

    Deprecation Statement

    This method is deprecated. Use activatePaymentPass:withActivationData:completion: instead.

    Declaration

    Swift

    func activatePaymentPass(_ paymentPass: PKPaymentPass, withActivationCode activationCode: String, completion completion: ((Bool, NSError) -> Void)?)

    Objective-C

    - (void)activatePaymentPass:(PKPaymentPass * nonnull)paymentPass withActivationCode:(NSString * nonnull)activationCode completion:(void (^ nullable)(BOOL success, NSError * nonnull error))completion

    Parameters

    paymentPass

    The payment pass being activated.

    activationCode

    The activation code.

    completion

    The completion block called after activation.

    This block takes the following parameters:

    success

    YEStrue if the pass was authorized; otherwise NOfalse.

    error

    If success is NOfalse, a description of the error.

    Discussion

    The pass must already be provisioned, and it must currently be in the PKPaymentPassActivationStateRequiresActivation state.

    Availability

    Available in iOS 8.0 and later.

    Deprecated in iOS 9.0.

  • Activates a payment pass using the provided activation code.

    Declaration

    Swift

    func activatePaymentPass(_ paymentPass: PKPaymentPass, withActivationData activationData: NSData, completion completion: ((Bool, NSError) -> Void)?)

    Objective-C

    - (void)activatePaymentPass:(PKPaymentPass * nonnull)paymentPass withActivationData:(NSData * nonnull)activationData completion:(void (^ nullable)(BOOL success, NSError * nonnull error))completion

    Parameters

    paymentPass

    The payment pass being activated.

    activationData

    The cryptographic one-time password.

    This data is Base64 encoded and then sent to the payment network. The framework treats this as an opaque value.

    completion

    The completion block called after activation.

    This block takes the following parameters:

    success

    YEStrue if the pass was authorized; otherwise NOfalse.

    error

    If success is NOfalse, a description of the error.

    Discussion

    The pass must already be provisioned, and it must currently be in the PKPaymentPassActivationStateRequiresActivation state.

    Availability

    Available in iOS 8.0 and later.

  • Indicates whether the device supports adding payment passes.

    Deprecation Statement

    This class method is deprecated. Use the isPaymentPassActivationAvailable instance method instead.

    Declaration

    Swift

    class func isPaymentPassActivationAvailable() -> Bool

    Objective-C

    + (BOOL)isPaymentPassActivationAvailable

    Return Value

    YEStrue if the device supports adding payment passes.

    Availability

    Available in iOS 8.0 and later.

    Deprecated in iOS 9.0.

  • Indicates whether the device supports adding payment passes.

    Declaration

    Swift

    func isPaymentPassActivationAvailable() -> Bool

    Objective-C

    - (BOOL)isPaymentPassActivationAvailable

    Return Value

    YEStrue if the device supports adding payment passes.

    Availability

    Available in iOS 9.0 and later.

  • Opens the user interface to set up credit cards for Apple Pay.

    Declaration

    Swift

    func openPaymentSetup()

    Objective-C

    - (void)openPaymentSetup

    Discussion

    Use this method to move users to the interface for adding credit cards. This method will transfer control to the Passbook app on iPhone or the Settings app on iPad. On devices that do not support Apple Pay, this method does nothing.

    Availability

    Available in iOS 8.3 and later.

  • Prevents the iOS device from automatically displaying the Apple Pay interface.

    Declaration

    Swift

    class func requestAutomaticPassPresentationSuppressionWithResponseHandler(_ responseHandler: (PKAutomaticPassPresentationSuppressionResult) -> Void) -> PKSuppressionRequestToken

    Objective-C

    + (PKSuppressionRequestToken)requestAutomaticPassPresentationSuppressionWithResponseHandler:(void (^ nonnull)(PKAutomaticPassPresentationSuppressionResult result))responseHandler

    Parameters

    responseHandler

    The response handler for the request.

    result

    The success or failure of the request.

    Return Value

    A PKSuppressionRequestToken value representing this request. Use this token to end the suppression of Apple Pay passes.

    If this feature is not supported on the device, or if the user has previously denied a request to suppress Apple Pay, this method fails immediately and returns a token value of 0; however, the result handler is still called.

    Discussion

    Only use this method in apps that are required to stay in the foreground when operating near NFC or other RF readers. This method prevents the iOS device from automatically displaying the Apple Pay passes when it detects a compatible reader. This suppression only occurs while the app is in the foreground. The Apple Pay interface is automatically reenabled when the app goes to the background; however, if the app resumes within 24 hours, the Apple Pay interface is automatically suppressed again.

    This method operates asynchronously; it schedules the request and returns immediately. The system performs the actual request on a background thread, and once complete, the system calls the response handler with the result. The response handler is called on an an arbitrary concurrent queue.

    The first time this method is called, the system presents a confirmation dialog to the user. The user can either allow or deny the request. Subsequent requests continue to use the user’s previously selected choice until either the app closes or 24 hours have passed. Then it displays the confirmation dialog again.

    Availability

    Available in iOS 9.0 and later.

    Not available in app extensions.

  • Reenables the automatic display of the Apple Pay interface.

    Declaration

    Swift

    class func endAutomaticPassPresentationSuppressionWithRequestToken(_ requestToken: PKSuppressionRequestToken)

    Objective-C

    + (void)endAutomaticPassPresentationSuppressionWithRequestToken:(PKSuppressionRequestToken)requestToken

    Parameters

    requestToken

    The token you received when you called the requestAutomaticPassPresentationSuppressionWithResponseHandler: method. If you pass in an invalid request token, the system ignores the end request.

    Discussion

    This method reenables the automatic presentation of Apple Pay passes when the device detects a compatible reader.

    Availability

    Available in iOS 9.0 and later.

    Not available in app extensions.

  • Returns a Boolean value that indicates whether the system is suppressing the automatic presentation of Apple Pay passes.

    Declaration

    Swift

    class func isSuppressingAutomaticPassPresentation() -> Bool

    Objective-C

    + (BOOL)isSuppressingAutomaticPassPresentation

    Return Value

    YEStrue if Apple Pay passes are being suppressed.

    Availability

    Available in iOS 9.0 and later.

    Not available in app extensions.

Data Types

  • A token representing a request to suppress the automatic presentation of payment passes.

    Declaration

    Swift

    typealias PKSuppressionRequestToken = Int

    Objective-C

    typedef NSUInteger PKSuppressionRequestToken;

    Discussion

    You receive a suppression request token when you begin suppressing the automatic presentation of passes. Use the token to end the suppression and re-enable Apple Pay.

    Import Statement

    Objective-C

    @import PassKit;

    Swift

    import PassKit

    Availability

    Available in iOS 9.0 and later.

  • Keys used to get values from the user information dictionary of pass library notifications.

    Declaration

    Swift

    let PKPassLibraryAddedPassesUserInfoKey: String let PKPassLibraryRemovedPassInfosUserInfoKey: String let PKPassLibraryReplacementPassesUserInfoKey: String let PKPassLibraryPassTypeIdentifierUserInfoKey: String let PKPassLibrarySerialNumberUserInfoKey: String

    Objective-C

    NSString * const PKPassLibraryAddedPassesUserInfoKey; NSString * const PKPassLibraryRemovedPassInfosUserInfoKey; NSString * const PKPassLibraryReplacementPassesUserInfoKey; NSString * const PKPassLibraryPassTypeIdentifierUserInfoKey; NSString * const PKPassLibrarySerialNumberUserInfoKey;

    Constants

    • PKPassLibraryAddedPassesUserInfoKey

      PKPassLibraryAddedPassesUserInfoKey

      An array of the PKPass objects that were added.

      Available in iOS 6.0 and later.

    • PKPassLibraryRemovedPassInfosUserInfoKey

      PKPassLibraryRemovedPassInfosUserInfoKey

      An array of dictionaries describing the passes that were removed.

      The dictionary contains the keys PKPassLibraryPassTypeIdentifierUserInfoKey and PKPassLibrarySerialNumberUserInfoKey.

      Available in iOS 6.0 and later.

    • PKPassLibraryReplacementPassesUserInfoKey

      PKPassLibraryReplacementPassesUserInfoKey

      An array of the PKPass objects that were replaced.

      Available in iOS 6.0 and later.

    • PKPassLibraryPassTypeIdentifierUserInfoKey

      PKPassLibraryPassTypeIdentifierUserInfoKey

      The pass type identifier of the pass.

      Used by the dictionary that is the value of PKPassLibraryRemovedPassInfosUserInfoKey.

      Available in iOS 6.0 and later.

    • PKPassLibrarySerialNumberUserInfoKey

      PKPassLibrarySerialNumberUserInfoKey

      The serial number of the pass.

      Used by the dictionary that is the value of PKPassLibraryRemovedPassInfosUserInfoKey.

      Available in iOS 6.0 and later.

  • Statuses used when adding passes to the pass library.

    Declaration

    Swift

    enum PKPassLibraryAddPassesStatus : Int { case DidAddPasses case ShouldReviewPasses case DidCancelAddPasses }

    Objective-C

    typedef enum : NSInteger { PKPassLibraryDidAddPasses, PKPassLibraryShouldReviewPasses, PKPassLibraryDidCancelAddPasses, } PKPassLibraryAddPassesStatus;

    Constants

    • DidAddPasses

      PKPassLibraryDidAddPasses

      Status used when passes were successfully added.

      Available in iOS 7.0 and later.

    • ShouldReviewPasses

      PKPassLibraryShouldReviewPasses

      Status used when the app should display the UI to let the user review the passes.

      Available in iOS 7.0 and later.

    • DidCancelAddPasses

      PKPassLibraryDidCancelAddPasses

      Status used when the user cancelled and the passes were not added.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import PassKit;

    Swift

    import PassKit

    Availability

    Available in iOS 7.0 and later.

  • The result of an attempt to suppress automatic pass presentation.

    Declaration

    Swift

    enum PKAutomaticPassPresentationSuppressionResult : UInt { case NotSupported case AlreadyPresenting case Denied case Cancelled case Success }

    Objective-C

    typedef enum : NSUInteger { PKAutomaticPassPresentationSuppressionResultNotSupported = 0, PKAutomaticPassPresentationSuppressionResultAlreadyPresenting, PKAutomaticPassPresentationSuppressionResultDenied, PKAutomaticPassPresentationSuppressionResultCancelled, PKAutomaticPassPresentationSuppressionResultSuccess } PKAutomaticPassPresentationSuppressionResult;

    Constants

    • NotSupported

      PKAutomaticPassPresentationSuppressionResultNotSupported

      The suppression of automatic pass presentation is not supported for this device.

      Available in iOS 9.0 and later.

    • AlreadyPresenting

      PKAutomaticPassPresentationSuppressionResultAlreadyPresenting

      The device is already presenting passes. Automatic presentation of passes cannot be suppressed.

      Available in iOS 9.0 and later.

    • Denied

      PKAutomaticPassPresentationSuppressionResultDenied

      Either the user prevented the suppression, or an internal error occurred.

      Available in iOS 9.0 and later.

    • Cancelled

      PKAutomaticPassPresentationSuppressionResultCancelled

      The suppression was cancelled before the response handler was fired.

      Available in iOS 9.0 and later.

    • Success

      PKAutomaticPassPresentationSuppressionResultSuccess

      Automatic pass presentation is suppressed.

      Available in iOS 9.0 and later.

    Import Statement

    Objective-C

    @import PassKit;

    Swift

    import PassKit

    Availability

    Available in iOS 9.0 and later.

  • Posted after the pass library has been changed.

    The notification is sent by an instance of the PKPassLibrary class. If there are no instances of the class, notifications are not sent. The notification may be sent on any thread or work queue.

    The user info dictionary of the notification describes the change. See Notification Keys for the keys used.

    Declaration

    Swift

    let PKPassLibraryDidChangeNotification: String

    Import Statement

    Objective-C

    @import PassKit;

    Swift

    import PassKit

    Availability

    Available in iOS 6.0 and later.

  • Posted when an Apple Pay card is added to or removed from a device that is paired with the current iOS device (for example, Apple Watch).

    The notification is sent by an instance of the PKPassLibrary class. If there are no instances of the class, notifications are not sent. The notification may be sent on any thread or work queue.

    The user info dictionary of the notification describes the change. See Notification Keys for the keys used.

    Declaration

    Swift

    let PKPassLibraryRemotePaymentPassesDidChangeNotification: String

    Import Statement

    Objective-C

    @import PassKit;

    Swift

    import PassKit

    Availability

    Available in iOS 9.0 and later.