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 set a ConnectionToken provider: 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

  • Sets the token provider for the shared (singleton) SCPTerminal instance.

    You must set a token provider before calling shared to initialize the Terminal singleton. We recommend calling setTokenProvider: in your AppDelegate’s application:didFinishLaunchingWithOptions: method. Alternatively, you can wrap your call to setTokenProvider: with a dispatch_once in Objective-C, or use a static constructor in Swift.

    Note that you may only set a token provider before requesting the shared Terminal instance for the first time. In order to switch accounts in your app, e.g. to switch between live and test Stripe API keys on your backend, refer to the documentation for the clearCachedCredentials method on the shared Terminal instance.

    Declaration

    Objective-C

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

    Swift

    class func setTokenProvider(_ tokenProvider: SCPConnectionTokenProvider)

  • Returns true if a token provider has been set, through setTokenProvider:

    Declaration

    Objective-C

    + (BOOL)hasTokenProvider;

    Swift

    class func hasTokenProvider() -> 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 setTokenProvider:.

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

    In order to switch accounts in your app:

    • if a reader is connected, call disconnectReader:
    • 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 clearCachedCredentials
    • 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.

    Declaration

    Objective-C

    - (void)clearCachedCredentials;

    Swift

    func clearCachedCredentials()

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 Local Mobile 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.

    You must call connectBluetoothReader or connectInternetReader while a discovery is taking place. You can only connect to a reader that was returned from the SCPDiscoveryDelegate‘s didUpdateDiscoveredReaders method.

    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: SCPDiscoveryConfiguration, delegate: 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 Bluetooth reader with a given connection configuration.

    To connect to a Bluetooth reader, your app must register that reader to a Location upon connection. You should create a SCPBluetoothConnectionConfiguration at some point before connecting which specifies the location to which this reader belongs.

    Throughout the lifetime of the connection, the reader will communicate with your app via the SCPBluetoothReaderDelegate to announce transaction status, battery level, and software update information.

    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.

    The SDK must be actively discovering readers in order to connect to one. The discovery process will stop if this connection request succeeds, otherwise the SDK will continue discovering.

    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 the 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)connectBluetoothReader:(nonnull SCPReader *)reader
                      delegate:(nonnull id<SCPBluetoothReaderDelegate>)delegate
              connectionConfig:(nonnull SCPBluetoothConnectionConfiguration *)
                                   connectionConfig
                    completion:(nonnull SCPReaderCompletionBlock)completion;

    Swift

    func connectBluetoothReader(_ reader: SCPReader, delegate: BluetoothReaderDelegate, connectionConfig: SCPBluetoothConnectionConfiguration) 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.
    delegate

    The delegate used during the lifetime of the connection. See SCPBluetoothReaderDelegate.
    connectionConfig

    The connection configuration for options while connecting to a reader. See SCPBluetoothConnectionConfiguration for more details.
    completion

    The completion block called when the command completes.

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

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

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

    The SDK must be actively discovering readers in order to connect to one. The discovery process will stop if this connection request succeeds, otherwise the SDK will continue discovering.

    When this method is called, the SDK uses a connection token and the given reader information to create a reader session. If the SDK does not already have a connection token, it will call the `fetchConnectionToken method you defined to fetch one.

    If connectionConfig is set to nil, the SDK will resort to default connection behavior; see the SCPInternetConnectionConfiguration header documentation for more details.

    See

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

    Declaration

    Objective-C

    - (void)connectInternetReader:(nonnull SCPReader *)reader
             connectionConfig:
                 (nullable SCPInternetConnectionConfiguration *)connectionConfig
                   completion:(nonnull SCPReaderCompletionBlock)completion;

    Swift

    func connectInternetReader(_ reader: SCPReader, connectionConfig: SCPInternetConnectionConfiguration?) 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 SCPInternetConnectionConfiguration for more details.
    completion

    The completion block called when the command completes.

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

    To connect to a Local Mobile reader, your app must register that reader to a Location upon connection. You should create a SCPLocalMobileConnectionConfiguration before connecting which specifies the location to which this reader belongs.

    Throughout the lifetime of the connection, the reader will communicate with your app via the SCPLocalMobileReaderDelegate as appropriate.

    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.

    The SDK must be actively discovering readers in order to connect to one. The discovery process will stop if this connection request succeeds, otherwise the SDK will continue discovering.

    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.

    Note that during connection, an update may occur to ensure that the local mobile reader has the most up to date software and configurations.

    See

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

    Declaration

    Objective-C

    - (void)
    connectLocalMobileReader:(nonnull SCPReader *)reader
                    delegate:(nonnull id<SCPLocalMobileReaderDelegate>)delegate
            connectionConfig:(nonnull SCPLocalMobileConnectionConfiguration *)
                                 connectionConfig
                  completion:(nonnull SCPReaderCompletionBlock)completion;

    Swift

    func connectLocalMobileReader(_ reader: SCPReader, delegate: LocalMobileReaderDelegate, connectionConfig: SCPLocalMobileConnectionConfiguration) 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.
    delegate

    The delegate used during the lifetime of the connection. See SCPLocalMobileReaderDelegate.
    connectionConfig

    The connection configuration for options while connecting to a reader. See SCPLocalMobileConnectionConfiguration 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 SCPBluetoothReaderDelegate 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 SCPCollectConfiguration *)collectConfig
              completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

    func collectPaymentMethod(_ paymentIntent: PaymentIntent, collectConfig: CollectConfiguration?, 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

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

    Swift

    func confirmPaymentIntent(_ paymentIntent: PaymentIntent) async -> (PaymentIntent?, SCPConfirmPaymentIntentError?)

    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

    - (void)confirmPaymentIntent:(nonnull SCPPaymentIntent *)paymentIntent
               confirmConfig:(nullable SCPConfirmConfiguration *)confirmConfig
                  completion:(nonnull SCPConfirmPaymentIntentCompletionBlock)
                                 completion;

    Swift

    func confirmPaymentIntent(_ paymentIntent: PaymentIntent, confirmConfig: ConfirmConfiguration?) async -> (PaymentIntent?, SCPConfirmPaymentIntentError?)

    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.

  • 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:customerConsentCollected: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
           customerConsentCollected:(BOOL)customerConsentCollected
                         completion:
                             (nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

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

    Parameters

    setupIntent

    The SetupIntent to which payment method information is attached.
    customerConsentCollected

    A boolean that should be set to true 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:customerConsentCollected: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
           customerConsentCollected:(BOOL)customerConsentCollected
                        setupConfig:
                            (nullable SCPSetupIntentConfiguration *)setupConfig
                         completion:
                             (nonnull SCPSetupIntentCompletionBlock)completion;

    Swift

    func collectSetupIntentPaymentMethod(_ setupIntent: SCPSetupIntent, customerConsentCollected: Bool, setupConfig: SetupIntentConfiguration?, completion: @escaping SetupIntentCompletionBlock) -> SCPCancelable?

    Parameters

    setupIntent

    The SetupIntent to which payment method information is attached.
    customerConsentCollected

    A boolean that should be set to true if you have successfully collected consent from the cardholder to save their payment information.
    setupConfig

    An optional SCPSetupIntentConfiguration 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

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

    Swift

    func confirmSetupIntent(_ setupIntent: SCPSetupIntent) async -> (SCPSetupIntent?, SCPConfirmSetupIntentError?)

    Parameters

    setupIntent

    The SetupIntent to confirm
    completion

    The completion block called when the confirmation completes

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

  • 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 SCPRefundConfiguration *)refundConfig
                    completion:(nonnull SCPErrorCompletionBlock)completion;

    Swift

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

    Parameters

    refundParams

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

    An optional SCPRefundConfiguration to configure per-refund overrides.
    completion

    The completion block called when the command completes.

  • 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

    - (void)confirmRefund:(nonnull SCPConfirmRefundCompletionBlock)completion;

    Swift

    func confirmRefund() async -> (SCPRefund?, SCPConfirmRefundError?)

    Parameters

    completion

    The completion block called when the command completes.

Offline mode

  • Set to receive offline reporting events from the SDK.

    Declaration

    Objective-C

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

    Swift

    var offlineDelegate: 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: 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.

  • 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: SCPReadMethod) -> 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

  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    + (nonnull instancetype)new;