SCPTerminal

Objective-C


@interface SCPTerminal : NSObject

Swift

class Terminal : NSObject

The SCPTerminal singleton object exposes an interface for discovering readers, connecting to a reader, creating payments, and saving card information for later use.

Before accessing the singleton object using the shared property, you must initialize the SDK by calling initWithTokenProvider: with an object that implements the SCPConnectionTokenProvider protocol. This object should authenticate with your backend, then fetch the secret from a freshly minted ConnectionToken.

The SCPTerminal singleton can only be connected to one reader at a time, and can only perform one operation at a time. As a general rule, make sure the completion handler of one operation has been called before calling another operation from within your app.

The Stripe Terminal SDK sends updates to your app by using the delegate pattern. You may want multiple views in your app to respond to these delegate calls. We recommend creating a central delegate announcer which broadcasts all delegate calls to views and ViewControllers that register themselves with that announcer. We have an example implementation of a TerminalDelegateAnnouncer as part of our example application.

Initializing and accessing the SCPTerminal singleton

  • Initializes the Terminal SDK with the provided token provider and full configuration.

    This method configures the shared Terminal instance with the necessary token provider and optional log level and delegate settings. You must call this method before accessing the shared Terminal instance.

    Declaration

    Objective-C

    + (void)initWithTokenProvider:
            (nonnull id<SCPConnectionTokenProvider>)tokenProvider
                     delegate:(nullable id<SCPTerminalDelegate>)delegate
              offlineDelegate:(nullable id<SCPOfflineDelegate>)offlineDelegate
                     logLevel:(SCPLogLevel)logLevel;

    Swift

    class func initWithTokenProvider(_ tokenProvider: any SCPConnectionTokenProvider, delegate: (any SCPTerminalDelegate)?, offlineDelegate: (any OfflineDelegate)?, logLevel: LogLevel)

    Parameters

    tokenProvider

    The token provider for authentication with Stripe Terminal.
    logLevel

    The log level for the SDK.
    delegate

    The primary delegate for Terminal events.
    offlineDelegate

    The offline delegate for offline-related events.

  • Initializes the Terminal SDK with the provided token provider and delegate.

    This method configures the shared Terminal instance with the necessary token provider and primary delegate. Log level defaults to SCPLogLevelNone and offline delegate defaults to nil.

    Declaration

    Objective-C

    + (void)initWithTokenProvider:
            (nonnull id<SCPConnectionTokenProvider>)tokenProvider
                     delegate:(nullable id<SCPTerminalDelegate>)delegate;

    Swift

    class func initWithTokenProvider(_ tokenProvider: any SCPConnectionTokenProvider, delegate: (any SCPTerminalDelegate)?)

    Parameters

    tokenProvider

    The token provider for authentication with Stripe Terminal.
    delegate

    The primary delegate for Terminal events.

  • Initializes the Terminal SDK with the provided token provider using default settings.

    This convenience method initializes the Terminal SDK with SCPLogLevelNone and no delegates.

    Declaration

    Objective-C

    + (void)initWithTokenProvider:
    (nonnull id<SCPConnectionTokenProvider>)tokenProvider;

    Swift

    class func initWithTokenProvider(_ tokenProvider: any SCPConnectionTokenProvider)

    Parameters

    tokenProvider

    The token provider for authentication with Stripe Terminal.

  • Returns true if Terminal has been initialized by calling initWithTokenProvider:

    Declaration

    Objective-C

    + (BOOL)isInitialized;

    Swift

    class func isInitialized() -> Bool

  • Sets a block to listen for logs from the shared Terminal instance (optional).

    You can use this optional method to listen for logs from the Stripe Terminal SDK and incorporate them into your own remote logs. Note that these logs are subject to change, and provided for informational and debugging purposes only. You should not depend on them for behavior in your app. Also note that the block you provide may be called from any thread.

    To print internal logs from the SDK to the console, you can set logLevel to SCPLogLevelVerbose on the Terminal instance.

    Declaration

    Objective-C

    + (void)setLogListener:(nonnull SCPLogListenerBlock)listener;

    Swift

    class func setLogListener(_ listener: @escaping LogListenerBlock)

  • Returns the shared (singleton) Terminal instance.

    Before accessing the singleton for the first time, you must first call initWithTokenProvider:.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) SCPTerminal *_Nonnull shared;

    Swift

    class var shared: Terminal { get }

  • The Terminal singleton object’s primary delegate. This delegate announces connection and payment status updates to your app.

    Setting this property is mandatory before connecting to a Bluetooth reader, like the BBPOS Chipper 2X BT or the BBPOS WisePad 3. Setting this property is optional before connecting to an internet reader, like the Verifone P400.

    A runtime assert will fire if your app attempts to connect to a reader that requires the delegate.

    Declaration

    Objective-C

    @property (nonatomic, nullable) id<SCPTerminalDelegate> delegate;

    Swift

    var delegate: (any SCPTerminalDelegate)? { get set }

Accessing the current state of the singleton

  • Information about the connected SCPReader, or nil if no reader is connected.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) SCPReader *connectedReader;

    Swift

    var connectedReader: SCPReader? { get }

  • The Terminal instance’s current connection status.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCPConnectionStatus connectionStatus;

    Swift

    var connectionStatus: ConnectionStatus { get }

  • The log level for the SDK. The default value is .none.

    Declaration

    Objective-C

    @property (nonatomic) SCPLogLevel logLevel;

    Swift

    var logLevel: LogLevel { get set }

  • The simulator configuration settings that will be used when connecting to and creating payments with a simulated reader. This object will always exist; to set the configuration settings, set the readwrite properties on Terminal.shared.simulatorConfiguration.

    See

    SCPSimulatorConfiguration

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCPSimulatorConfiguration *_Nonnull simulatorConfiguration;

    Swift

    var simulatorConfiguration: SimulatorConfiguration { get }

  • The Terminal instance’s current payment status.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCPPaymentStatus paymentStatus;

    Swift

    var paymentStatus: PaymentStatus { get }

  • Clears the current connection token, saved reader sessions, and any other cached credentials. You can use this method to switch accounts in your app, e.g. to switch between live and test Stripe API keys on your backend.

    Warning

    This method will fail if the terminal is currently connected to a reader. You must disconnect from the reader before clearing cached credentials.

    In order to switch accounts in your app:

    • if a reader is connected, call disconnectReader: first
    • call clearCachedCredentials to clear the current credentials
    • configure the tokenProvider object to return connection tokens for the new account. The tokenProvider is implemented by your code, and you can do this however you want.
    • call discoverReaders and connectReader to connect to a reader. The connect call will request a new connection token from your backend server via the token provider.

    An overview of the lifecycle of a connection token under the hood:

    • When the Terminal singleton is initialized, the SDK attempts to proactively request a connection token from your backend server.
    • When connect is called, the SDK uses the connection token and reader information to create a reader session.

    • Subsequent calls to connect will re-use the reader session if the SDK has successfully connected to the reader already. Otherwise, it will require a new connection token when you call connect again.

    Note

    In Swift, this method is refined to return a Result type.

    Declaration

    Objective-C

    - (BOOL)clearCachedCredentials:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    Out parameter for any errors that occur. Will be set to SCPErrorUnexpectedOperationError if called while connected to a reader.

    Return Value

    YES if credentials were successfully cleared, NO if an error occurred.

Reader discovery, connection, and updates

  • Use this method to determine whether the mobile device supports a given reader type using a particular discovery method. This is useful for the Tap To Pay reader discovery method where support will vary according to operating system and hardware capabilities.

    Declaration

    Objective-C

    - (BOOL)supportsReadersOfType:(SCPDeviceType)deviceType
              discoveryMethod:(SCPDiscoveryMethod)discoveryMethod
                    simulated:(BOOL)simulated
                        error:(NSError *_Nullable *_Nullable)error;

    Parameters

    deviceType

    Reader device type to determine support for.
    discoveryMethod

    Associated discovery method.
    simulated

    Determines whether to check for availability of simulated discovery to discover a device simulator. The Terminal SDK comes with the ability to simulate behavior without using physical hardware. This makes it easy to quickly test your integration end-to-end, from pairing with a reader to taking payments.
    error

    If not supported, an error indicating the reason. @returns YES if supported, NO otherwise.

  • Begins discovering readers based on the given discovery configuration.

    When discoverReaders is called, the terminal begins scanning for readers using the settings in the given SCPDiscoveryConfiguration. You must implement SCPDiscoveryDelegate to get notified of discovered readers and display discovery results to your user.

    The discovery process will stop on its own when the terminal successfully connects to a reader, if the command is canceled, or if a discovery error occurs.

    See

    https://stripe.com/docs/terminal/readers/connecting

    Declaration

    Objective-C

    - (nonnull SCPCancelable *)
    discoverReaders:(nonnull id<SCPDiscoveryConfiguration>)configuration
           delegate:(nonnull id<SCPDiscoveryDelegate>)delegate
         completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func discoverReaders(_ configuration: any SCPDiscoveryConfiguration, delegate: any SCPDiscoveryDelegate, completion: @escaping ErrorCompletionBlock) -> SCPCancelable

    Parameters

    configuration

    The configuration for reader discovery.
    delegate

    Your delegate for reader discovery.
    completion

    The completion block called when the command completes.

  • Attempts to connect to the given reader with a given connection configuration.

    To connect to mobile readers, your app must register that reader to a Location upon connection. The location is specified in the connection configuration for the reader.

    Throughout the lifetime of the connection, the reader will communicate with your app via the SCPReaderDelegate to announce reader related events.

    If the connection succeeds, the completion block will be called with the connected reader, and SCPTerminal.connectionStatus will change to .connected.

    If the connection fails, the completion block will be called with an error.

    If the SDK is actively discovery when connect is called the SDK will complete the discover command.

    When this method is called, the SDK uses a connection token and the given reader information to register the reader to your Stripe account. If the SDK does not already have a connection token, it will call the fetchConnectionToken method in your SCPConnectionTokenProvider implementation.

    If a mobile reader’s battery is critically low the connect call will fail with SCPErrorBluetoothDisconnected. Plug your reader in to start charging and try again.

    See

    https://stripe.com/docs/terminal/readers/connecting

    Declaration

    Objective-C

    - (void)connectReader:(nonnull SCPReader *)reader
     connectionConfig:(nonnull SCPConnectionConfiguration *)connectionConfig
           completion:(nonnull SCPReaderCompletionBlock)completion;

    Swift

    func connectReader(_ reader: SCPReader, connectionConfig: ConnectionConfiguration) async throws -> SCPReader

    Parameters

    reader

    The reader to connect to. This should be a reader recently returned to the didUpdateDiscoveredReaders: method in the discovery delegate.
    connectionConfig

    The connection configuration for options while connecting to a reader. See SCPConnectionConfiguration and its subclasses for more details.
    completion

    The completion block called when the command completes.

  • Retrieves a list of SCPLocation objects belonging to your merchant. You must specify the ID of one of these locations to register the reader to while connecting to a Bluetooth reader.

    See

    https://stripe.com/docs/terminal/readers/fleet-management#bluetooth-readers

    Declaration

    Objective-C

    - (void)listLocations:(nullable SCPListLocationsParameters *)parameters
           completion:(nonnull SCPLocationsCompletionBlock)completion;

    Swift

    func listLocations(parameters: SCPListLocationsParameters?) async throws -> ([SCPLocation], Bool)

    Parameters

    parameters

    The optional parameters to pass to the List all Locations API endpoint. Pass nil to use the default parameters.
    completion

    The completion block called when the command completes.

  • Installs the available update for the connected reader.

    Stripe Terminal reader updates will either be updated automatically upon connection, or announced as available but not automatically installed. When the Stripe Terminal SDK announces an optional update, you can present that update to your app’s user and let them decide when to perform that update. When your user chooses to perform a reader update, call this method to start the installation.

    In your app you should display the progress of the update to the user. You should also instruct the user to wait for the update to complete: “Do not leave this page, and keep the reader in range and powered on until the update is complete.” You can set UIApplication.shared.isIdleTimerDisabled to true while the update is being installed to prevent the device from automatically locking.

    If an error occurs while installing the update (e.g. because the update was interrupted), the SCPMobileReaderDelegate will receive reader:didFinishInstallingUpdate:error: with the error. If the update completed successfully, the same method will be called with nil error.

    You must implement the ability to update your reader’s software in your app. Though we expect required software updates to be very rare, by using Stripe Terminal, you are obligated to include this functionality.

    Note

    It is an error to call this method when the SDK is connected to the Verifone P400 or WisePOS E readers.

    See

    https://stripe.com/docs/terminal/readers/bbpos-chipper2xbt#updating-reader-software

    See

    https://stripe.com/docs/terminal/readers/bbpos-wisepad3#updating-reader-software

    Declaration

    Objective-C

    - (void)installAvailableUpdate;

    Swift

    func installAvailableUpdate()

  • Reboots the connected reader.

    If the reboot succeeds, the completion block is called with nil. If the reboot fails, the completion block is called with an error.

    @note: This method is only available for Bluetooth readers.

    See

    https://stripe.com/docs/terminal/readers/connecting

    Declaration

    Objective-C

    - (void)rebootReader:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func rebootReader() async throws

    Parameters

    completion

    The completion block called when the command completes.

  • Attempts to disconnect from the currently connected reader.

    If the disconnect succeeds, the completion block is called with nil. If the disconnect fails, the completion block is called with an error.

    See

    https://stripe.com/docs/terminal/readers/connecting

    Declaration

    Objective-C

    - (void)disconnectReader:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func disconnectReader() async throws

    Parameters

    completion

    The completion block called when the command completes.

Taking payments

  • Creates a new SCPPaymentIntent with the given parameters.

    Note: If the information required to create a PaymentIntent isn’t readily available in your app, you can create the PaymentIntent on your server and use the retrievePaymentIntent method to retrieve the PaymentIntent in your app.

    - note: This cannot be used with the Verifone P400. If used with the
Verifone P400, the completion handler will be called with
an SCPErrorFeatureNotAvailableWithConnectedReader error.

    See

    https://stripe.com/docs/terminal/payments#create

    Declaration

    Objective-C

    - (void)createPaymentIntent:(nonnull SCPPaymentIntentParameters *)parameters
                 completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func createPaymentIntent(_ parameters: PaymentIntentParameters) async throws -> PaymentIntent

    Parameters

    parameters

    The parameters for the PaymentIntent to be created.
    completion

    The completion block called when the command completes.

  • Retrieves a SCPPaymentIntent with a client secret.

    If the information required to create a PaymentIntent isn’t readily available in your app, you can create the PaymentIntent on your server and use this method to retrieve the PaymentIntent in your app.

    See

    https://stripe.com/docs/terminal/payments#create

    Declaration

    Objective-C

    - (void)retrievePaymentIntent:(nonnull NSString *)clientSecret
                   completion:
                       (nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func retrievePaymentIntent(clientSecret: String) async throws -> PaymentIntent

    Parameters

    clientSecret

    The client secret of the PaymentIntent to be retrieved.
    completion

    The completion block called when the command completes.

  • Collects a payment method for the given SCPPaymentIntent.

    Note: collectPaymentMethod does not apply any changes to the PaymentIntent API object. Updates to the PaymentIntent are local to the SDK, and persisted in-memory.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call collectPaymentMethod again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with a PaymentIntent with status .requiresConfirmation, indicating that you should call confirmPaymentIntent:completion: to finish the payment.

    Note that if collectPaymentMethod is canceled, the completion block will be called with a Canceled error.

    See

    https://stripe.com/docs/terminal/payments#collect

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectPaymentMethod:(nonnull SCPPaymentIntent *)paymentIntent
              completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func collectPaymentMethod(_ paymentIntent: PaymentIntent, completion: @escaping PaymentIntentCompletionBlock) -> SCPCancelable?

    Parameters

    paymentIntent

    The PaymentIntent to collect a payment method for.
    completion

    The completion block called when the command completes.

  • Collects a payment method for the given PaymentIntent, with the specified configuration.

    Note: collectPaymentMethod does not apply any changes to the PaymentIntent API object. Updates to the PaymentIntent are local to the SDK, and persisted in-memory.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectPaymentMethod:(nonnull SCPPaymentIntent *)paymentIntent
           collectConfig:
               (nullable SCPCollectPaymentIntentConfiguration *)collectConfig
              completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func collectPaymentMethod(_ paymentIntent: PaymentIntent, collectConfig: CollectPaymentIntentConfiguration?, completion: @escaping PaymentIntentCompletionBlock) -> SCPCancelable?

    Parameters

    paymentIntent

    The PaymentIntent to collect a payment method for.
    collectConfig

    The CollectConfiguration object that contains settings for this call.
    completion

    The completion block called when the command completes.

  • Confirm a payment after collecting a payment method succeeds.

    Synchronous capture

    Stripe Terminal uses two-step card payments to prevent unintended and duplicate payments. When confirmPaymentIntent completes successfully, a charge has been authorized on the customer’s card, but not yet been “captured”. Your app must synchronously notify your backend to capture the PaymentIntent in order to settle the funds to your account.

    Handling failures

    When confirmPaymentIntent fails, the SDK returns an error that includes the updated SCPPaymentIntent. Your app should inspect the updated PaymentIntent to decide how to retry the payment.

    1. If the updated PaymentIntent is nil, the request to Stripe’s servers timed out and the PaymentIntent’s status is unknown. We recommend that you retry confirmPaymentIntent with the original PaymentIntent. If you instead choose to abandon the original PaymentIntent and create a new one, do not capture the original PaymentIntent. If you do, you might charge your customer twice.

    2. If the updated PaymentIntent’s status is still .requiresConfirmation (e.g., the request failed because your app is not connected to the internet), you can call confirmPaymentIntent again with the updated PaymentIntent to retry the request.

    3. If the updated PaymentIntent’s status changes to .requiresPaymentMethod (e.g., the request failed because the card was declined), call collectPaymentMethod with the updated PaymentIntent to try charging another card.

    See

    https://stripe.com/docs/terminal/payments#process

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    confirmPaymentIntent:(nonnull SCPPaymentIntent *)paymentIntent
              completion:
                  (nonnull SCPConfirmPaymentIntentCompletionBlock)completion;

    Swift

    func confirmPaymentIntent(_ paymentIntent: PaymentIntent, completion: @escaping ConfirmPaymentIntentCompletionBlock) -> SCPCancelable?

    Parameters

    paymentIntent

    The PaymentIntent to confirm.
    completion

    The completion block called when the confirm completes.

  • Confirm a payment after collecting a payment method succeeds.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    confirmPaymentIntent:(nonnull SCPPaymentIntent *)paymentIntent
           confirmConfig:
               (nullable SCPConfirmPaymentIntentConfiguration *)confirmConfig
              completion:
                  (nonnull SCPConfirmPaymentIntentCompletionBlock)completion;

    Swift

    func confirmPaymentIntent(_ paymentIntent: PaymentIntent, confirmConfig: ConfirmPaymentIntentConfiguration?, completion: @escaping ConfirmPaymentIntentCompletionBlock) -> SCPCancelable?

    Parameters

    paymentIntent

    The PaymentIntent to confirm.
    confirmConfig

    The ConfirmConfiguration object that contains settings for this call.
    completion

    The completion block called when the confirm completes.

  • Processes a payment by collecting a payment method and confirming the payment intent in a single operation.

    This method combines the functionality of collectPaymentMethod and confirmPaymentIntent into a single call.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    processPaymentIntent:(nonnull SCPPaymentIntent *)paymentIntent
           collectConfig:
               (nullable SCPCollectPaymentIntentConfiguration *)collectConfig
           confirmConfig:
               (nullable SCPConfirmPaymentIntentConfiguration *)confirmConfig
              completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func processPaymentIntent(_ paymentIntent: PaymentIntent, collectConfig: CollectPaymentIntentConfiguration?, confirmConfig: ConfirmPaymentIntentConfiguration?, completion: @escaping PaymentIntentCompletionBlock) -> SCPCancelable?

    Parameters

    paymentIntent

    The PaymentIntent to process.
    collectConfig

    The configuration for collecting the payment method.
    confirmConfig

    The configuration for confirming the payment intent.
    completion

    The completion block called when the payment completes.

    Return Value

    A cancelable that can be used to cancel the payment process.

  • Cancels an SCPPaymentIntent.

    If the cancel request succeeds, the completion block will be called with the updated PaymentIntent object with status Canceled. If the cancel request fails, the completion block will be called with an error.

    Note

    This cannot be used with the Verifone P400 reader. If used with the Verifone P400, the completion handler will be called with an SCPErrorFeatureNotAvailableWithConnectedReader error.

    See

    https://stripe.com/docs/terminal/payments/refunds

    Declaration

    Objective-C

    - (void)cancelPaymentIntent:(nonnull SCPPaymentIntent *)paymentIntent
                 completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func cancelPaymentIntent(_ paymentIntent: PaymentIntent) async throws -> PaymentIntent

    Parameters

    paymentIntent

    The PaymentIntent to cancel.
    completion

    The completion block called when the cancel completes.

Saving payment details for later use

  • Creates a new SCPSetupIntent with the given parameters.

    See

    https://stripe.com/docs/api/setup_intents/create

    Declaration

    Objective-C

    - (void)createSetupIntent:(nonnull SCPSetupIntentParameters *)setupIntentParams
               completion:(nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func createSetupIntent(_ setupIntentParams: SCPSetupIntentParameters) async throws -> SCPSetupIntent

    Parameters

    setupIntentParams

    The parameters that control the creation of the SetupIntent.
    completion

    The completion block called when the command completes.

  • Retrieves an SCPSetupIntent with a client secret.

    If you’ve created a SetupIntent on your backend, you must retrieve it in the Stripe Terminal SDK before calling collectSetupIntentPaymentMethod.

    Declaration

    Objective-C

    - (void)retrieveSetupIntent:(nonnull NSString *)clientSecret
                 completion:(nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func retrieveSetupIntent(clientSecret: String) async throws -> SCPSetupIntent

    Parameters

    clientSecret

    The client secret of the SetupIntent to be retrieved.
    completion

    The completion block called when the command completes.

  • Cancels an SCPPaymentIntent.

    If the cancel request succeeds, the completion block will be called with the updated PaymentIntent object with status Canceled. If the cancel request fails, the completion block will be called with an error.

    See

    https://stripe.com/docs/api/setup_intents/cancel

    Declaration

    Objective-C

    - (void)cancelSetupIntent:(nonnull SCPSetupIntent *)intent
               completion:(nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func cancelSetupIntent(_ intent: SCPSetupIntent) async throws -> SCPSetupIntent

    Parameters

    intent

    The SetupIntent to cancel.
    completion

    The completion block called when cancellation completes.

  • Collects a payment method for the given SCPSetupIntent.

    This method does not update the SetupIntent API object. All updates are local to the SDK and only persisted in memory. You must confirm the SetupIntent to create a PaymentMethod API object and (optionally) attach that PaymentMethod to a customer.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call collectSetupIntentPaymentMethod again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with a SetupIntent with status .requiresConfirmation, indicating that you should call confirmSetupIntent:completion: to finish the payment.

    Note that if collectSetupIntentPaymentMethod is canceled, the completion block will be called with a Canceled error.

    Card networks require that you collect consent from the customer before saving and reusing their card information. The SetupIntent confirmation API method normally takes a mandate_data hash that lets you specify details about the customer’s consent. The Stripe Terminal SDK will fill in the mandate_data hash with relevant information, but in order for it to do so, you must specify whether you have gathered consent from the cardholder to collect their payment information in this method’s second parameter.

    The payment method will not be collected without the cardholder’s consent.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectSetupIntentPaymentMethod:(nonnull SCPSetupIntent *)setupIntent
                     allowRedisplay:(SCPAllowRedisplay)allowRedisplay
                         completion:
                             (nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func collectSetupIntentPaymentMethod(_ setupIntent: SCPSetupIntent, allowRedisplay: AllowRedisplay, completion: @escaping SetupIntentCompletionBlock) -> SCPCancelable?

    Parameters

    setupIntent

    The SetupIntent to which payment method information is attached.
    allowRedisplay

    A value that should be set to always or limited if you have successfully collected consent from the cardholder to save their payment information.
    completion

    The completion block called when collection completes.

  • Collects a payment method for the given SCPSetupIntent.

    This method does not update the SetupIntent API object. All updates are local to the SDK and only persisted in memory. You must confirm the SetupIntent to create a PaymentMethod API object and (optionally) attach that PaymentMethod to a customer.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call collectSetupIntentPaymentMethod again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with a SetupIntent with status .requiresConfirmation, indicating that you should call confirmSetupIntent:completion: to finish the payment.

    Note that if collectSetupIntentPaymentMethod is canceled, the completion block will be called with a Canceled error.

    Card networks require that you collect consent from the customer before saving and reusing their card information. The SetupIntent confirmation API method normally takes a mandate_data hash that lets you specify details about the customer’s consent. The Stripe Terminal SDK will fill in the mandate_data hash with relevant information, but in order for it to do so, you must specify whether you have gathered consent from the cardholder to collect their payment information in this method’s second parameter.

    The payment method will not be collected without the cardholder’s consent.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectSetupIntentPaymentMethod:(nonnull SCPSetupIntent *)setupIntent
                     allowRedisplay:(SCPAllowRedisplay)allowRedisplay
                        setupConfig:
                            (nullable SCPCollectSetupIntentConfiguration *)
                                setupConfig
                         completion:
                             (nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func collectSetupIntentPaymentMethod(_ setupIntent: SCPSetupIntent, allowRedisplay: AllowRedisplay, setupConfig: CollectSetupIntentConfiguration?, completion: @escaping SetupIntentCompletionBlock) -> SCPCancelable?

    Parameters

    setupIntent

    The SetupIntent to which payment method information is attached.
    allowRedisplay

    A value that should be set to always or limited if you have successfully collected consent from the cardholder to save their payment information.
    setupConfig

    An optional SCPCollectSetupIntentConfiguration to configure per-setup overrides.
    completion

    The completion block called when collection completes.

  • Confirms a SetupIntent after the payment method has been successfully collected.

    Handling failures

    When confirmSetupIntent fails, the SDK returns an error that includes the updated SCPSetupIntent. Your app should inspect the updated SetupIntent to decide how to proceed.

    1. If the updated SetupIntent is nil, the request to Stripe’s servers timed out and the SetupIntent’s status is unknown. We recommend that you retry confirmSetupIntent with the original SetupIntent.

    2. If the updated SetupIntent’s status is still .requiresConfirmation (e.g., the request failed because your app is not connected to the internet), you can call confirmSetupIntent again with the updated SetupIntent to retry the request.

    3. If the updated SetupIntent’s status is .requiresAction, there might be authentication the cardholder must perform offline before the saved PaymentMethod can be used.

    See

    https://stripe.com/docs/api/setup_intents/confirm

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    confirmSetupIntent:(nonnull SCPSetupIntent *)setupIntent
            completion:(nonnull SCPConfirmSetupIntentCompletionBlock)completion;

    Swift

    func confirmSetupIntent(_ setupIntent: SCPSetupIntent, completion: @escaping ConfirmSetupIntentCompletionBlock) -> SCPCancelable?

    Parameters

    setupIntent

    The SetupIntent to confirm
    completion

    The completion block called when the confirmation completes

  • Processes a setup intent by collecting a payment method and confirming the setup intent in a single operation.

    This method combines the functionality of collectSetupIntentPaymentMethod and confirmSetupIntent into a single call.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    processSetupIntent:(nonnull SCPSetupIntent *)setupIntent
        allowRedisplay:(SCPAllowRedisplay)allowRedisplay
         collectConfig:
             (nullable SCPCollectSetupIntentConfiguration *)collectConfig
            completion:(nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func processSetupIntent(_ setupIntent: SCPSetupIntent, allowRedisplay: AllowRedisplay, collectConfig: CollectSetupIntentConfiguration?, completion: @escaping SetupIntentCompletionBlock) -> SCPCancelable?

    Parameters

    setupIntent

    The SetupIntent to process.
    allowRedisplay

    Controls how this SetupIntent may be shown to the customer in the Stripe Dashboard.
    collectConfig

    The configuration for collecting the setup intent payment method.
    completion

    The completion block called when the setup intent completes.

    Return Value

    A cancelable that can be used to cancel the setup intent process.

Card-present refunds

  • Initiates an in-person refund with a given set of SCPRefundParameters by collecting the payment method that is to be refunded.

    Some payment methods, like Interac Debit payments, require that in-person payments also be refunded while the cardholder is present. The cardholder must present the Interac card to the card reader; these payments cannot be refunded via the dashboard or the API.

    For payment methods that don’t require the cardholder be present, see https://stripe.com/docs/terminal/payments/refunds

    This method allows you to design an in-person refund flow into your app.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call processRefund again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with an nil error. At that point, you can call confirmRefund to finish refunding the payment method.

    The completion block will either be called with the successful SCPRefund or with an NSError. If the error is of type SCPConfirmRefundError.

    Note that if processRefund is canceled, the completion block will be called with a Canceled error.

    When processRefund fails, the SDK returns an error that may include the failed SCPRefund that led to a failure.

    Your app should inspect the error. If its of type SCPConfirmRefundError it can be inspected for additional details about the refund that led to the failure.

    1. If the error is a SCPConfirmRefundError and the refund property is nil, the request to Stripe’s servers timed out and the refund’s status is unknown. We recommend that you retry processRefund with the original SCPRefundParameters.
    2. If the SCPConfirmRefundError has a failure_reason, the refund was declined. We recommend that you take action based on the decline code you received.

    Note

    processRefund is only available for payment methods that require in-person refunds. For all other refunds, use the Stripe Dashboard or the Stripe API.

    See

    https://stripe.com/docs/terminal/canada#interac-refunds

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    processRefund:(nonnull SCPRefundParameters *)refundParams
    collectConfig:(nullable SCPCollectRefundConfiguration *)collectConfig
       completion:(nonnull SCPConfirmRefundCompletionBlock)completion;

    Swift

    func processRefund(_ refundParams: RefundParameters, collectConfig: CollectRefundConfiguration?, completion: @escaping ConfirmRefundCompletionBlock) -> SCPCancelable?

    Parameters

    refundParams

    The refund parameters.
    collectConfig

    The configuration for collecting the refund payment method.
    completion

    The completion block called when the refund completes.

    Return Value

    A cancelable that can be used to cancel the refund process.

Offline mode

  • Set to receive offline reporting events from the SDK.

    Declaration

    Objective-C

    @property (nonatomic, nullable) id<SCPOfflineDelegate> offlineDelegate;

    Swift

    var offlineDelegate: (any OfflineDelegate)? { get set }

  • The offline-related statistics and status for both the SDK and any connected smart reader.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCPOfflineStatus *_Nonnull offlineStatus;

    Swift

    var offlineStatus: OfflineStatus { get }

  • Creates a new SCPPaymentIntent with the given parameters.

    Note: If the information required to create a PaymentIntent isn’t readily available in your app, you can create the PaymentIntent on your server and use the retrievePaymentIntent method to retrieve the PaymentIntent in your app.

    - note: This cannot be used with the Verifone P400. If used with the
Verifone P400, the completion handler will be called with
an SCPErrorFeatureNotAvailableWithConnectedReader error.

    See

    https://stripe.com/docs/terminal/payments#create

    Declaration

    Objective-C

    - (void)createPaymentIntent:(nonnull SCPPaymentIntentParameters *)parameters
               createConfig:(nullable SCPCreateConfiguration *)createConfig
                 completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func createPaymentIntent(_ parameters: PaymentIntentParameters, createConfig: CreateConfiguration?) async throws -> PaymentIntent

    Parameters

    parameters

    The parameters for the PaymentIntent to be created.
    createConfig

    Optional configuration overrides used when creating this payment intent.
    completion

    The completion block called when the command completes.

Displaying information to customers

  • Clears the reader display and resets it to the splash screen.

    Note

    Only available for the Verifone P400 and BBPOS WisePOS E.

    Declaration

    Objective-C

    - (void)clearReaderDisplay:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func clearReaderDisplay() async throws

    Parameters

    completion

    The completion block called when the command completes.

  • Updates the reader display with cart information. This method is for display purposes only and has no correlation with what the customer is actually charged. Tax and total are also not automatically calculated and must be set in SCPCart.

    Note

    Only available for the Verifone P400 and BBPOS WisePOS E.

    Declaration

    Objective-C

    - (void)setReaderDisplay:(nonnull SCPCart *)cart
              completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func setReaderDisplay(_ cart: Cart) async throws

    Parameters

    cart

    The cart containing the information that will be displayed.
    completion

    The completion block called when the command completes.

  • Configures settings on the connected reader.

    Declaration

    Objective-C

    - (void)setReaderSettings:(nonnull id<SCPReaderSettingsParameters>)params
               completion:(nonnull SCPReaderSettingsCompletionBlock)completion;

    Swift

    func setReaderSettings(_ params: any ReaderSettingsParameters) async throws -> SCPReaderSettings

    Parameters

    params

    The SCPReaderSettingsParameters instance with the values to set on the reader.
    completion

    The SCPReaderSettingsCompletionBlock to be called when the operation completes.

  • Retrieves the current settings from the connected reader.

    Declaration

    Objective-C

    - (void)retrieveReaderSettings:
    (nonnull SCPReaderSettingsCompletionBlock)completion;

    Swift

    func retrieveReaderSettings() async throws -> SCPReaderSettings

    Parameters

    completion

    The SCPReaderSettingsCompletionBlock to be called when the operation completes.

  • Displays forms and collects information from customers. Available for BBPOS WisePOS E and Stripe S700.

    See

    https://stripe.com/docs/terminal/features/collect-inputs

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectInputs:(nonnull SCPCollectInputsParameters *)collectInputsParams
       completion:(nonnull SCPCollectInputsCompletionBlock)completion;

    Swift

    func collectInputs(_ collectInputsParams: CollectInputsParameters, completion: @escaping CollectInputsCompletionBlock) -> SCPCancelable?

    Parameters

    collectInputsParams

    parameters to configure forms
    completion

    The completion block called when the command completes.

  • Collects data using the hardware interfaces on the reader. Currently available on mobile readers that support magstripe.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectData:(nonnull SCPCollectDataConfiguration *)collectDataConfiguration
     completion:(nonnull SCPCollectedDataCompletionBlock)completion;

    Swift

    func collectData(_ collectDataConfiguration: CollectDataConfiguration, completion: @escaping CollectedDataCompletionBlock) -> SCPCancelable?

    Parameters

    collectDataConfiguration

    The CollectDataConfiguration object that contains settings for this call
    completion

    The completion block called when the command completes.

  • Prints the specified content to the connected reader’s printer, if available.

    Declaration

    Objective-C

    - (void)print:(nonnull SCPPrintContent *)content
    completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    @warn_unqualified_access func print(_ content: PrintContent) async throws

    Parameters

    content

    The content to print.
    completion

    The completion block called when the command completes.

  • Returns an unlocalized string for the given reader input options, e.g. “Swipe / Insert”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromReaderInputOptions:
    (SCPReaderInputOptions)options;

    Swift

    class func stringFromReaderInputOptions(_ options: ReaderInputOptions = []) -> String

  • Returns an unlocalized string for the given reader display message, e.g. “Retry Card”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromReaderDisplayMessage:
    (SCPReaderDisplayMessage)message;

    Swift

    class func stringFromReaderDisplayMessage(_ message: ReaderDisplayMessage) -> String

  • Returns an unlocalized string for the given reader event, e.g. “Card Inserted”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromReaderEvent:(SCPReaderEvent)event;

    Swift

    class func stringFromReaderEvent(_ event: ReaderEvent) -> String

  • Returns an unlocalized string for the given connection status, e.g. “Connecting”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromConnectionStatus:(SCPConnectionStatus)status;

    Swift

    class func stringFromConnectionStatus(_ status: ConnectionStatus) -> String

  • Returns an unlocalized string for the given payment status, e.g. “Not Ready”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromPaymentStatus:(SCPPaymentStatus)status;

    Swift

    class func stringFromPaymentStatus(_ status: PaymentStatus) -> String

  • Returns an unlocalized string for the given device type.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromDeviceType:(SCPDeviceType)deviceType;

    Swift

    class func stringFromDeviceType(_ deviceType: DeviceType) -> String

  • Returns an unlocalized string for the given discovery method.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromDiscoveryMethod:(SCPDiscoveryMethod)method;

    Swift

    class func stringFromDiscoveryMethod(_ method: DiscoveryMethod) -> String

  • Returns an unlocalized string for the given card brand.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromCardBrand:(SCPCardBrand)cardBrand;

    Swift

    class func stringFromCardBrand(_ cardBrand: CardBrand) -> String

  • Returns an unlocalized string for the given payment intent status.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromPaymentIntentStatus:
    (SCPPaymentIntentStatus)paymentIntentStatus;

    Swift

    class func stringFromPaymentIntentStatus(_ paymentIntentStatus: PaymentIntentStatus) -> String

  • Returns an unlocalized string for the given capture method.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromCaptureMethod:(SCPCaptureMethod)captureMethod;

    Swift

    class func stringFromCaptureMethod(_ captureMethod: CaptureMethod) -> String

  • Returns an unlocalized string for the given read method.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromReadMethod:(SCPReadMethod)method;

    Swift

    class func stringFromReadMethod(_ method: ReadMethod) -> String

  • Returns an unlocalized string for the given network status, e.g. “Online”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromNetworkStatus:(SCPNetworkStatus)networkStatus;

    Swift

    class func stringFromNetworkStatus(_ networkStatus: NetworkStatus) -> String

  • Returns an unlocalized string for the given disconnect reason, e.g. “Reboot requested”

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromDisconnectReason:(SCPDisconnectReason)reason;

    Swift

    class func stringFromDisconnectReason(_ reason: DisconnectReason) -> String

  • Returns an unlocalized string for the given offline behavior.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromOfflineBehavior:(SCPOfflineBehavior)behavior;

    Swift

    class func stringFromOfflineBehavior(_ behavior: OfflineBehavior) -> String

  • Returns an unlocalized string for the given payment method type.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromPaymentMethodType:
    (SCPPaymentMethodType)paymentMethodType;

    Swift

    class func stringFromPaymentMethodType(_ paymentMethodType: PaymentMethodType) -> String

  • Returns an unlocalized string for the given error.

    Declaration

    Objective-C

    + (nonnull NSString *)stringFromError:(SCPError)error;

    Swift

    class func stringFromError(_ error: ErrorCode.Code) -> String

  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    + (nonnull instancetype)new;

Deprecations

  • Deprecated

    collectRefundPaymentMethod has been replaced by processRefund

    Initiates an in-person refund with a given set of SCPRefundParameters by collecting the payment method that is to be refunded.

    Some payment methods, like Interac Debit payments, require that in-person payments also be refunded while the cardholder is present. The cardholder must present the Interac card to the card reader; these payments cannot be refunded via the dashboard or the API.

    For payment methods that don’t require the cardholder be present, see https://stripe.com/docs/terminal/payments/refunds

    This method, along with confirmRefund, allow you to design an in-person refund flow into your app.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call collectRefundPaymentMethod again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with an nil error. At that point, you can call confirmRefund to finish refunding the payment method.

    Calling any other SDK methods between collectRefundPaymentMethod and confirmRefund will result in undefined behavior.

    Note that if collectRefundPaymentMethod is canceled, the completion block will be called with a Canceled error.

    See

    https://stripe.com/docs/terminal/canada#interac-refunds

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectRefundPaymentMethod:(nonnull SCPRefundParameters *)refundParams
                    completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func collectRefundPaymentMethod(_ refundParams: RefundParameters, completion: @escaping ErrorCompletionBlock) -> SCPCancelable?

    Parameters

    refundParams

    The SCPRefundParameters object that describes how the refund will be created.
    completion

    The completion block called when the command completes.

  • Deprecated

    collectRefundPaymentMethod has been replaced by processRefund

    Initiates an in-person refund with a given set of SCPRefundParameters by collecting the payment method that is to be refunded.

    Some payment methods, like Interac Debit payments, require that in-person payments also be refunded while the cardholder is present. The cardholder must present the Interac card to the card reader; these payments cannot be refunded via the dashboard or the API.

    For payment methods that don’t require the cardholder be present, see https://stripe.com/docs/terminal/payments/refunds

    This method, along with confirmRefund, allow you to design an in-person refund flow into your app.

    If collecting a payment method fails, the completion block will be called with an error. After resolving the error, you may call collectRefundPaymentMethod again to either try the same card again, or try a different card.

    If collecting a payment method succeeds, the completion block will be called with an nil error. At that point, you can call confirmRefund to finish refunding the payment method.

    Calling any other SDK methods between collectRefundPaymentMethod and confirmRefund will result in undefined behavior.

    Note that if collectRefundPaymentMethod is canceled, the completion block will be called with a Canceled error.

    See

    https://stripe.com/docs/terminal/canada#interac-refunds

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
    collectRefundPaymentMethod:(nonnull SCPRefundParameters *)refundParams
                  refundConfig:
                      (nullable SCPCollectRefundConfiguration *)refundConfig
                    completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

    func collectRefundPaymentMethod(_ refundParams: RefundParameters, refundConfig: CollectRefundConfiguration?, completion: @escaping ErrorCompletionBlock) -> SCPCancelable?

    Parameters

    refundParams

    The SCPRefundParameters object that describes how the refund will be created.
    refundConfig

    An optional SCPCollectRefundConfiguration to configure per-refund overrides.
    completion

    The completion block called when the command completes.

  • Deprecated

    confirmRefund has been replaced by processRefund

    Confirms an in-person refund after the refund payment method has been collected.

    The completion block will either be called with the successful SCPRefund or with an SCPConfirmRefundError.

    When confirmRefund fails, the SDK returns an error that either includes the failed SCPRefund or the SCPRefundParameters that led to a failure. Your app should inspect the SCPConfirmRefundError to decide how to proceed.

    1. If the refund property is nil, the request to Stripe’s servers timed out and the refund’s status is unknown. We recommend that you retry confirmRefund with the original SCPRefundParameters.

    2. If the SCPConfirmRefundError has a failure_reason, the refund was declined. We recommend that you take action based on the decline code you received.

    Note

    collectRefundPaymentMethod:completion and confirmRefund are only available for payment methods that require in-person refunds. For all other refunds, use the Stripe Dashboard or the Stripe API.

    See

    https://stripe.com/docs/terminal/canada#interac-refunds

    Declaration

    Objective-C

    - (nullable SCPCancelable *)confirmRefund:
    (nonnull SCPConfirmRefundCompletionBlock)completion;

    Swift

    func confirmRefund(completion: @escaping ConfirmRefundCompletionBlock) -> SCPCancelable?

    Parameters

    completion

    The completion block called when the command completes.