SCPTerminal


@interface SCPTerminal : NSObject

The SCPTerminal object that is made available by the Stripe Terminal SDK exposes a generic interface for discovering readers, connecting to a reader, and creating payments.

The SCPTerminal object is a singleton, and you cannot create multiple SCPTerminal instances.

  • 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;
  • 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: and setDelegate:.

    Declaration

    Objective-C

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

    Swift

    class var shared: Terminal { get }
  • The terminal’s delegate (optional).

    Set this to handle events from the Terminal instance.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) id<SCPTerminalDelegate>
        delegate;
  • Information about the connected SCPReader, or nil if no reader is connected.

    Declaration

    Objective-C

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

    Swift

    var connectedReader: SCPReader? { get }
  • The terminal’s current connection status.

    Declaration

    Objective-C

    @property (readonly, nonatomic) SCPConnectionStatus connectionStatus;

    Swift

    var connectionStatus: ConnectionStatus { get }
  • The log level for the SDK. The default value is .none.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) SCPLogLevel logLevel;

    Swift

    var logLevel: LogLevel { get set }
  • The terminal’s current payment status.

    Declaration

    Objective-C

    @property (readonly, nonatomic) 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()
  • Begins discovering readers matching the given configuration.

    When discoverReaders is called, the terminal begins scanning for readers using the settings in the given SCPDiscoveryConfiguration. You must implement SCPDiscoveryDelegate to handle displaying discovery results to your user and connecting to a selected reader.

    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.

    Note that if discoverReaders is canceled, the completion block will be called with nil (rather than an SCPErrorCanceled error).

    Declaration

    Objective-C

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

    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.

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

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

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

    Under the hood, the SDK uses the fetchConnectionToken method you defined to fetch a connection token if it does not already have one. It then uses the connection token and reader information to create a reader session.

    Declaration

    Objective-C

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

    Swift

    func connectReader(_ reader: SCPReader, completion: @escaping ReaderCompletionBlock)

    Parameters

    reader

    The reader to connect to. This should be a reader recently returned to the didUpdateDiscoveredReaders: method.

    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.

    Declaration

    Objective-C

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

    Swift

    func disconnectReader(_ completion: @escaping ErrorCompletionBlock)

    Parameters

    completion

    The completion block called when the command completes.

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

    Declaration

    Objective-C

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

    Swift

    func createPaymentIntent(_ parameters: SCPPaymentIntentParameters, completion: @escaping PaymentIntentCompletionBlock)

    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.

    Declaration

    Objective-C

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

    Swift

    func retrievePaymentIntent(clientSecret: String, completion: @escaping PaymentIntentCompletionBlock)

    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 processPayment:completion: to finish the payment.

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

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
        collectPaymentMethod:(nonnull SCPPaymentIntent *)paymentIntent
                    delegate:(nullable id<SCPReaderDisplayDelegate>)delegate
                  completion:(nonnull SCPPaymentIntentCompletionBlock)completion;

    Swift

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

    Parameters

    paymentIntent

    The PaymentIntent to collect a payment method for.

    delegate

    Your delegate for handling reader input events. Providing an SCPReaderDisplayDelegate is required when the connected reader doesn’t have a built-in display (e.g., the BBPOS Chipper 2X BT). These readers will request that your app display messages during the collectPaymentMethod process (e.g., Remove card) via this delegate.

    completion

    The completion block called when the command completes.

  • Processes a payment after collecting a payment method succeeds.

    Synchronous capture

    Stripe Terminal uses two-step card payments to prevent unintended and duplicate payments. When processPayment 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 processPayment 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 processPayment 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 processPayment 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.

    Declaration

    Objective-C

    - (void)processPayment:(nonnull SCPPaymentIntent *)paymentIntent
                completion:(nonnull SCPProcessPaymentCompletionBlock)completion;

    Swift

    func processPayment(_ paymentIntent: SCPPaymentIntent, completion: @escaping ProcessPaymentCompletionBlock)

    Parameters

    paymentIntent

    The PaymentIntent to confirm.

    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.

    Declaration

    Objective-C

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

    Swift

    func cancelPaymentIntent(_ paymentIntent: SCPPaymentIntent, completion: @escaping PaymentIntentCompletionBlock)

    Parameters

    paymentIntent

    The PaymentIntent to cancel.

    completion

    The completion block called when the cancel completes.

  • Reads a card with the given parameters and returns a PaymentMethod.

    NOTE: Most integrations should not use readReusableCard.

    You should create a SCPPaymentIntent and use the associated collectPaymentMethod and processPayment methods if you are simply collecting a payment from a customer.

    You can use readReusableCard to read payment details and defer payment for later. The PaymentMethod created by this method will have type card, suitable for use with online payments.

    Note that if you use this method to defer a payment, the transaction will not receive the beneficial rates and liability shift associated with card present transactions.

    If reading a card fails, the completion block will be called with an error containing details about the failure. If reading a card succeeds, the completion block will be called with a PaymentMethod. You should send the ID of the payment method to your backend for further processing. For example, you can use the fingerprint to look up charges created using the same card.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
        readReusableCard:(nonnull SCPReadReusableCardParameters *)parameters
                delegate:(nonnull id<SCPReaderDisplayDelegate>)delegate
              completion:(nonnull SCPPaymentMethodCompletionBlock)completion;

    Swift

    func readReusableCard(_ parameters: SCPReadReusableCardParameters, delegate: ReaderDisplayDelegate, completion: @escaping PaymentMethodCompletionBlock) -> SCPCancelable?

    Parameters

    parameters

    The parameters for reading the card.

    delegate

    Your delegate for handling reader input events.

    completion

    The completion block called when the command completes.

  • Checks for a reader software update, and returns an update object if an update is available.

    If an update is available, the completion block will be called with an SCPReaderSoftwareUpdate object, indicating that a software update is available. The update object contains information about the update that you can display to the user, such as the estimated installation time.

    If an error occurs while checking for an update, the completion block will be called with an error. If there are no updates available and no errors occur, the completion block will be called with (nil, nil).

    Declaration

    Objective-C

    - (nullable SCPCancelable *)checkForUpdate:
        (nonnull SCPReaderSoftwareUpdateCompletionBlock)completion;

    Swift

    func checkForUpdate(_ completion: @escaping ReaderSoftwareUpdateCompletionBlock) -> SCPCancelable?

    Parameters

    completion

    The completion block called when checking for an update completes.

  • Installs the provided update, and calls the completion block when the installation has completed.

    If an error occurs while installing the update (e.g. because the update was interrupted), the completion block will be called with an error. If the update completed successfully, the completion block will be called with nil. You must pass a delegate to handle events as the update proceeds. 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 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.

    Declaration

    Objective-C

    - (nullable SCPCancelable *)
        installUpdate:(nonnull SCPReaderSoftwareUpdate *)update
             delegate:(nonnull id<SCPReaderSoftwareUpdateDelegate>)delegate
           completion:(nonnull SCPErrorCompletionBlock)completion;

    Parameters

    update

    The reader update.

    delegate

    Your delegate for handling update events.

    completion

    The completion block called when the update 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
  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    - (nonnull instancetype)init;
  • Unavailable

    Use initWithConfiguration:tokenProvider:delegate:

    Declaration

    Objective-C

    - (nonnull instancetype)new;