_SecureElementCredential_SwiftUI · IOS API REFERENCE
CredentialTransaction
class · iOS 18.1+ · SDK 27.1
class CredentialTransaction
A transaction object for performing wired and contactless operations in SwiftUI views.
Use the <doc://com.apple.documentation/documentation/SwiftUI/View/transactionTask(_:action:)> view modifier to create a task for working with a credential. The `action` closure receives a `CredentialTransaction` instance that it can perform actions on.
You can call the methods of `CredentialTransaction` and ``CredentialTransaction/Configuration`` from both apps and app extensions.
> Warning: Don't import UIKit in any file that imports this type. This causes ambiguity resolving the ``SecureElementCredential`` framework's SwiftUI and UIKit symbols.
Activate the current credential to perform a transaction in card emulation mode.
Calling this method requires that the credential's state is `wired`. If successful, the state transitions to ``CredentialSession/State/cardEmulation(credential:)``. If an error occurs, the state is unchanged, unless the error is ``CredentialSession/ErrorCode/resourceUnavailable``, which transitions the state back to ``CredentialSession/State-swift.enum/management``.
When you call this method, the following sequence of events takes place:
1. The system prompts the user to authorize Card Emulation.
2. The system deselects the instance on the wired interface.
3. The system calls the broker interface with authorization information, if applicable. See the integration guide in the [Apple Business Register](https://register.apple.com).
4. The system makes the instance available over the contactless interface and transitions the session to the card emulation state.
This process is guaranteed to preserve contents of the Clear On Reset buffer in the operating system running on the Secure Element. This allows you to create some context in wired mode that remains valid later in card emulation mode.
The caller needs to invoke ``CredentialTransaction/Configuration/invalidate()`` after completing each transaction.
> Important: Calling this method may generate a billable event to the credential provider.
- Parameters:
- options: The options to transition the credential to card emulation mode.
- Throws: An ``CredentialSession/ErrorCode``. The most common errors are:
- ``CredentialSession/ErrorCode/invalidView``: The transaction has no associated scene.
- ``CredentialSession/ErrorCode/userCanceledAuthorization``: The user dismissed the authorization sheet.
- ``CredentialSession/ErrorCode/resourceUnavailable``: The system resource is unavailable.
Prompts the user for authorization and then activates a credential for card emulation.
If this call succeeds, the session state trasitions to ``CredentialSession/State/cardEmulation(credential:)``.
Card emulation ends after 60 seconds, at which point the the event stream publishes a ``CredentialSession/Event/cardEmulationTimeout`` event. If you complete your transaction before the timeout, call ``CredentialSession/endCardEmulation()`` to exit card emulation mode.
The caller needs to invoke ``CredentialTransaction/Configuration/invalidate()`` after completing each transaction.
> Important: Calling this method may generate a billable event to the credential provider.
- Parameters:
- credential: The credential to activate and transition into card emulation state.
- options: The options to activate the credential with, defaults to none.
- Throws: An ``CredentialSession/ErrorCode``. The most common errors are:
- ``CredentialSession/ErrorCode/invalidView``: The transaction has no associated scene.
- ``CredentialSession/ErrorCode/userCanceledAuthorization``: The user dismissed the authorization sheet.
- ``CredentialSession/ErrorCode/resourceUnavailable``: The system resource is unavailable.
Enters wired mode to perform a transaction.
After you call this method, the system shows an authorization screen to the person using the app. If they choose to authorize, the specified instance receives an authentication token. The instance receives this token through the broker interface on the Secure Element as described in the [Apple Business Register](https://register.apple.com/login) Secure Element documents.
If the person using the app declines the authorization, the session throws ``CredentialSession/ErrorCode/accessDenied``.
You can call this method in any session state. The state transitions to ``CredentialSession/State/wired(credential:)`` if successful. If an error occurs, the state is unchanged, unless the error is ``CredentialSession/ErrorCode/resourceUnavailable``, which transitions the state back to ``CredentialSession/State/management``.
The caller must invoke ``CredentialTransaction/Configuration/invalidate()`` after completing each transaction.
- Parameters:
- credential: The installed credential to enter wired mode with.
- instanceAID: The instance applet instance identifier of the installed credential to authorize.
- Throws: An ``CredentialSession/ErrorCode``. The most common errors are:
- ``CredentialSession/ErrorCode/invalidView``: The transaction has no associated scene.
- ``CredentialSession/ErrorCode/credentialDoesNotExist``: The specified credential doesn't exist or the caller doesn't have access to it.
- ``CredentialSession/ErrorCode/instanceDoesNotExist``: The specified instance identifier doesn't exist in the target credential.
- ``CredentialSession/ErrorCode/userCanceledAuthorization``: The user dismissed the authorization sheet.
- ``CredentialSession/ErrorCode/resourceUnavailable``: The system resource is unavailable.
