Repository navigation
Releases
Releases · stripe/stripe-terminal-ios
5.8.1
5.8.1 2026-10-08
Fixes
- Fixed an issue where offline PaymentIntents dropped merchant-supplied creation parameters, causing Tap to Pay on iPhone collection to fail for destination charges using
onBehalfOf.
6.0.0
6.0.0 2026-10-07
- Built with Xcode 27.0, Swift version 6.4.
- The framework is built with
-Xfrontend -disable-module-selectors-in-module-interface, so the public.swiftinterfaceuses the pre-6.3 dot-qualified spelling instead of the SE-0491Module::Typeselector syntax Swift 6.3+ emits by default. Minimum requirement for integrators: Xcode 16.0+, Swift 6.0+.
New
- WisePad 3 now supports amount surcharge and confirm-time on-reader surcharge consent. Collect-time
surchargeNoticeremains unsupported on WisePad 3. - Added
SCPErrorCanceledByReader, returned when an operation is canceled on the reader: the physical cancel button on a mobile reader, or the customer canceling on a smart reader. Programmatic cancellations initiated through the SDK continue to returnSCPErrorCanceled. - Tap to Pay on iPhone now returns
SCPErrorCanceledByReaderwhen the customer dismisses the payment sheet or backs out of PIN entry. Cancellations the integration requests throughSCPCancelablecontinue to returnSCPErrorCanceled. - Added
SCPPaymentMethodCardPresentDetails, which exposes the instrument fields returned bypayment_method.card_presentandpayment_method.interac_present, including available and preferred card networks. - Added
latestChargeandlatestChargeIdtoSCPPaymentIntent, exposing the PaymentIntent's most recent Charge from eitherlatest_chargeor the legacychargeslist. - Preview: Refunds - Added
confirmRefund, which creates a Refund for a PaymentIntent without collecting a payment method or displaying reader UI.- Added
SCPConfirmRefundParametersto configure full or partial refunds and optional Refund fields. - Added
SCPRefundStatusCanceledandSCPRefundStatusRequiresAction. - Added
SCPRefundNextActionto expose required follow-up details. - To request access to this feature, please contact Stripe Support.
- Added
- Preview: Added support for Mexico installments (meses sin intereses, or MSI) for eligible card-present transactions. Use
SCPInstallmentsParametersBuilderto enable installments when creating a PaymentIntent. After payment method collection,SCPInstallmentsParameters.availablePlanscontains the eligible installment plans. After confirmation,SCPInstallmentsParameters.plancontains the plan selected by the cardholder.- To request access to this feature, please contact Stripe Support.
- Preview: Swish — Added
SCPPaymentMethodTypeSwishandSCPSwishDetails, and exposed Swish details throughSCPPaymentMethod.swishandSCPPaymentMethodDetails.swish.- To request access to this feature, please contact Stripe Support.
Updates
- Breaking:
SCPRefund.stripeIdnow returns a nullable string. In Swift,Refund.stripeIdis nowString?. Check for a value before using it. - Breaking: Standardized the PaymentMethod properties on
SCPSetupIntentto matchSCPPaymentIntent. The expandedSCPPaymentMethodis now exposed aspaymentMethod, and its ID is exposed aspaymentMethodId. Replace uses of the previous ID-valuedpaymentMethodproperty withpaymentMethodId, and replacepaymentMethodExpandedwithpaymentMethod. - Breaking: Removed
SCPPaymentIntent.charges. UselatestChargefor the expanded most recent Charge andlatestChargeIdfor its ID. - Breaking: Removed
SCPPaymentIntent.invoice. Retrieve the PaymentIntent's invoice relationship through the Stripe API from your server. - Breaking:
SCPPaymentMethod.cardPresentandSCPPaymentMethod.interacPresentnow returnSCPPaymentMethodCardPresentDetailsinstead ofSCPCardPresentDetails. Transaction-only properties remain onSCPPaymentMethodDetails.cardPresentandSCPPaymentMethodDetails.interacPresent.SCPCardPresentDetails.networkshas been removed; use the correspondingSCPPaymentMethodCardPresentDetails.networksproperty instead. Expiration month and year on the new model are nullable to preserve their absence in API responses. - Breaking: Removed
SCPCardBrand(CardBrand). Thebrandproperties on
SCPCardDetails,SCPCardPresentDetails, andSCPOfflineCardPresentDetails
are now strings.SCPCardPresentDetails.networkand the entries in
SCPNetworks.availableare also strings, andSCPNetworks.preferrednow
exposes the API's preferred network. Replace enum comparisons such as.visa
with string comparisons such as"visa". - Breaking: Replaced
SCPErrorPrinterLowBatterywith the more generalSCPErrorReaderBatteryLow, returned when a reader remains connected but cannot complete an operation, such as printing, because its battery is too low. - Breaking: Removed
SCPCardFundingType(CardFundingType). Thefunding
properties onSCPCardDetails(CardDetails) andSCPCardPresentDetails
(CardPresentDetails) are now nullable strings containing the value returned
by the Stripe API. Replace enum comparisons such as.creditwith string
comparisons such as"credit". Missing funding values are returned asnil,
and values introduced after the installed SDK version are preserved. - Breaking: Removed
SCPTerminal.stringFromCardBrand:(Terminal.stringFromCardBrand).
brandvalues are now strings directly, so no conversion is necessary. - Breaking: Removed
SCPReadMethod(ReadMethod). ThereadMethod
properties onSCPCardPresentDetails(CardPresentDetails) and
SCPOfflineCardPresentDetails(OfflineCardPresentDetails) are now strings
containing canonical Stripe API values such as"contact_emv". Values
introduced after the installed SDK version are preserved, and missing values
are returned as"unknown". - Breaking: Removed
SCPTerminal.stringFromReadMethod:
(Terminal.stringFromReadMethod).readMethodvalues are now strings
directly, so no conversion is necessary. - Breaking: Removed
SCPErrorSimulatedOfflineModeNotAvailableForAccount.
Simulated offline mode is now generally available and is no longer gated
per-account, so this error is never returned.
setSimulatedOfflineModeConfiguration:error:no longer fails when a reader is
connected, and connecting a testmode reader no longer disconnects it for
lacking access. Remove any handling for this error code. Connecting to a
livemode reader still returns
SCPErrorSimulatedOfflineModeNotAvailableInLivemode. - Breaking:
SCPPaymentIntentParametersBuildernow defaultscaptureMethodtoSCPCaptureMethodAutomaticAsyncinstead ofSCPCaptureMethodManual. Integrations that require separate capture, including those using on-receipt tipping, incremental authorization, or extended authorization, must explicitly setSCPCaptureMethodManual. - Breaking:
allowRedisplayis now required when initializingCollectSetupIntentConfigurationBuilder, and all SetupIntent collection and processing methods require aCollectSetupIntentConfiguration. In Swift, migrate fromCollectSetupIntentConfigurationBuilder()toCollectSetupIntentConfigurationBuilder(allowRedisplay: .always)(or another appropriate value), then pass the built configuration assetupConfigtocollectSetupIntentPaymentMethodor ascollectConfigtoprocessSetupIntent. - Breaking: Renamed
SCPRefundParameters(RefundParameters) andSCPRefundParametersBuilder(RefundParametersBuilder) toSCPProcessRefundParameters(ProcessRefundParameters) andSCPProcessRefundParametersBuilder(ProcessRefundParametersBuilder). Update integrations that callprocessRefundto use the new names. Refund behavior is unchanged. - Breaking: Added
ReaderInteractionDelegateas the shared base protocol forMobileReaderDelegateandTapToPayReaderDelegate. The five reader lifecycle and display callbacks shared by Mobile Reader and Tap to Pay now use thereadermethod prefix, allowing integrations that support both reader types to implement these callbacks once.- Rename the five required Swift callbacks from
tapToPayReader(_:didStartInstallingUpdate:cancelable:),tapToPayReader(_:didReportReaderSoftwareUpdateProgress:),tapToPayReader(_:didFinishInstallingUpdate:error:),tapToPayReader(_:didRequestReaderInput:), andtapToPayReader(_:didRequestReaderDisplayMessage:)to their correspondingreader(_:forms. In Objective-C, rename the corresponding selectors fromtapToPayReader:didStartInstallingUpdate:cancelable:,tapToPayReader:didReportReaderSoftwareUpdateProgress:,tapToPayReader:didFinishInstallingUpdate:error:,tapToPayReader:didRequestReaderInput:, andtapToPayReader:didRequestReaderDisplayMessage:to selectors beginning withreader:. - Payment callbacks are not part of
ReaderInteractionDelegate. Mobile Reader and Tap to Pay connections use the separateReaderPaymentInteractionDelegate.reader(_:didRequestInteraction:)callback andPaymentInteractionwrapper types for blocking payment UI. Set the delegate on the connection configuration withsetReaderPaymentInteractionDelegate(_:). - The update API split is intentional:
MobileReaderDelegate.reader(_:didReportAvailableUpdate:)reports a deferred optional update whose installation is user-triggered for Mobile Readers, while the shared installation callbacks also report mandatory Tap to Pay configuration installation during connection. Tap to Pay doesn't report available optional updates.
- Rename the five required Swift callbacks from
- Breaking: Removed
allowCustomerCancelandsetAllowCustomerCancel:fromSCPInternetConnectionConfiguration. Customer-initiated cancellation is controlled per-collection by [customerCancellation](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPCollectPaymentIntentConfigu...
5.8.0
New
- Added support for reading and setting the buzzer volume on supported readers.
- Read the current volume from
SCPReaderSettings.buzzerVolumeviaretrieveReaderSettings:.SCPReaderBuzzerVolumereports the current and maximum volume. - Set the volume by calling
setReaderSettings:completion:withSCPBuzzerVolumeParameters, usinginit(level:)forLoworHigh, orinit(volume:)for a custom volume in the range1...maxVolume. - On a connected reader that does not support buzzer volume control, the volume is reported as unavailable and
setReaderSettings:fails.
- Read the current volume from
- Added
generatedCardExpandedproperty toSCPSetupAttemptCardPresentDetails, exposing the fullSCPPaymentMethodobject when saving a card viaSetupIntent. Fixes #392. - Added
paymentMethodExpandedproperty toSCPSetupIntent, exposing the fullSCPPaymentMethodobject attached to theSetupIntent. - Added
SCPLogLevelError,SCPLogLevelWarning, andSCPLogLevelInfotoSCPLogLevel, matching the granularity available in the Android SDK. Setting a level now prints logs at that severity and above, rather than all-or-nothing. - Added
SCPErrorPrinterLowBatteryerror code. This error is returned when the reader's battery is too low to complete a print operation. - Added
SCPDeviceTypeUnknown(DeviceType.unknown). A reader whosedevice_typethis version of the SDK does not recognize is now surfaced with this device type instead of being omitted, mirroring the Android SDK. The SDK exposes no known capabilities for a reader of this type.
Fixes
- Fixed inaccurate
SCPDisconnectReasonvalues reported for mobile readers connecting over Bluetooth, such as the Stripe Reader M2. A Bluetooth signal loss corroborated by the OS as an out-of-range link timeout is now reported asSCPDisconnectReasonBluetoothSignalLost, selecting "Forget this device" in iOS Settings is now reported asSCPDisconnectReasonPeerRemovedPairingInformation, and an unexpected internal disconnect is no longer misreported asSCPDisconnectReasonDisconnectRequested. Fixes #391. - Fixed a crash during Tap to Pay on iPhone
collectPaymentMethodwhen the connected reader or reader account ID was unexpectedly unavailable. Fixes #395.
5.7.0
5.7.0 2026-07-13
New
- Preview: Surcharging - Added support for collecting surcharges on Tap to Pay on iPhone readers.
- To request access to this feature, please contact Stripe Support.
Fixes
- Fixed an issue where a mobile reader disconnect due to critically low battery was incorrectly reported as a
SCPDisconnectReasonDisconnectRequestedinstead ofSCPDisconnectReasonCriticallyLowBattery.
5.6.0
5.6.0 2026-06-08
New
- Added
SCPCardPresentDetails.overcaptureStatusto indicate whether overcapture is supported for a card present transaction. Fixes #386.- Note for internet reader integrations, this feature requires reader software version
2.43or later to be installed on your internet reader.
- Note for internet reader integrations, this feature requires reader software version
- Added
SCPLocaleConfigparameter toTerminal.initWithTokenProviderto configure localization of API error messages. PassLocaleConfig.cardLanguagePreferenceIfAvailableto localize messages to the cardholder's preferred language when available (falling back to the device locale), orHardcodedLocaleConfigfor a fixed locale.
Fixes
- Fixes #378: Fixed a crash caused by a race condition during internal logging operations.
- Preview: Surcharging - Fixed an issue where
SCPSurchargeDetails.amountwas not included in the amount charged, also causing an incorrectmaximumAmountcalculation. - Fixes a race condition in where the reader state could be mutated after a disconnect, leaving the SDK permanently stuck in the Connected state.
5.5.0
5.5.0 2026-05-04
New
- Preview: Surcharging - Refactored the surcharge API surface.
- Added new
SCPSurchargeDetailsclass withamount,maximumAmount, andstatusonSCPAmountDetails.surcharge. - Breaking:
SCPSurchargeclass (underSCPCardPresentParameters) has been removed. UseSCPSurchargeDetailsformaximumAmountandstatus.statusis now aSCPSurchargeStatusenum instead ofNSString. - Breaking:
SCPPaymentIntent.amountSurcharge(top-level) has been removed. UseSCPAmountDetails.surcharge.amountinstead. - To request access to this feature, please contact Stripe Support.
- Added new
- Tap to Pay: Added method
isTapToPayAccountLinked, which checks if the current Stripe account has a linked Tap to Pay on iPhone account that has accepted the Apple Tap to Pay Terms of Service. - Added simulated offline mode support for testing offline payment flows without a physical network disruption. The simulation capability is currently in preview.
- Added
simulatedOfflineModeConfigurationproperty andsetSimulatedOfflineModeConfiguration:error:method toSCPTerminal. - Added
SCPSimulatedOfflineModeConfigurationandSCPSimulatedOfflineModeConfigurationBuilderto configure SDK and reader offline behavior independently. - Added
SCPSimulatedOfflineModeenum with values:disabled,offlineImmediate,offlineTimeout, andofflineIntermittent. - Returns
SCPErrorSimulatedOfflineModeNotAvailableForAccountif you do not have access, andSCPErrorSimulatedOfflineModeNotAvailableInLivemodeif connected to a livemode reader. - To request access to this feature, please contact Stripe Support.
- Added
- Added support for simulating software update scenarios on physical mobile readers in test mode.
- Added
SCPTestReaderUpdateandSCPTestReaderUpdateTypewith scenarios: available, required, required-for-offline, and low battery. - Set
testReaderUpdateonSCPBluetoothConnectionConfigurationorSCPUsbConnectionConfigurationbefore connecting. SCPSimulatorConfiguration.availableReaderUpdateis deprecated in favor of this new per-connection API.
- Added
Updates
- When offline mode is enabled, the SDK now falls back to offline processing faster when the device can't reach Stripe. Previously, the SDK waited up to 15 seconds before falling back. Now, timeouts are optimized per request type, reducing wait times for common operations like payment creation.
- Tap to Pay: Generic or unknown errors from the Tap to Pay on iPhone reader will now return
SCPErrorGenericReaderErrorinstead ofSCPErrorUnexpectedSdkError.
Fixes
- Fixes #374: Fixed a race condition that could cause a crash during mobile reader discovery over Bluetooth.
5.4.0
5.4.0 2026-03-30
New
- Preview: Terminal Donations - Added support to skip donations flow per transaction by adding a
skipDonationparameter to theSCPCollectPaymentIntentConfigurationmodel.- To request access to this private preview, please contact Stripe Support.
- Preview: Multi Capture - Added
requestMulticapturetoSCPCardPresentParametersfor requesting multicapture support when creating card-present PaymentIntents.- To request access to this feature, please contact Stripe Support.
- Preview: Reauthorizations - Added support to authorize a
PaymentIntentagain after its capture window has lapsed.- Added
requestReauthorizationtoSCPCardPresentParametersfor requesting reauthorization support when creating card-present PaymentIntents. - Added
reauthorizationStatusandreauthorizeBeforeresponse fields toSCPCardPresentDetails. - Added
SCPPaymentIntentStatusRequiresReauthorizationtoSCPPaymentIntentStatus. - To request access to this feature, please contact Stripe Support.
- Added
- Added the
captureBeforeresponse field toSCPCardPresentDetails.- Previously only available via the server-side API.
Updates
SCPApiErrornow exposesrequestLogUrl,adviceCode,networkAdviceCode, andnetworkDeclineCodeto provide more details about Stripe API errors.SCPSetupIntent.lastSetupErrorandSCPSetupAttempt.setupErrornow exposerequestLogUrl,adviceCode,networkAdviceCode, andnetworkDeclineCodeviaSCPApiError.SCPConfirmPaymentIntentError,SCPConfirmSetupIntentError, andSCPConfirmRefundErrornow expose anapiErrorproperty, which is also available viauserInfo[SCPErrorKeyStripeAPIError].
Fixes
- Fixes #377: Fixed a crash caused by delegate callbacks and completion handlers being dispatched on background threads when using Swift concurrency.
- Fixed a crash that could occur during reader discovery.
5.3.0
5.3.0 2026-03-03
Fixes
- Fixes #370: Fixed a race condition that could cause a crash when connecting to readers.
5.2.0
New
-
Added support for tip-eligibility on WisePad 3 devices, allowing configuration of the portion of a transaction amount on which tips are calculated.
-
Added
SCPErrorConfirmInvalidSetupIntenterror code to properly identify invalid SetupIntent confirmation attempts. -
Added support for collecting surcharges on M2 devices.
- To request access to this feature, please contact Stripe Support.
-
Added Tap to Pay support for QR-based non‑card payments.
TapToPayReaderDelegatehas two new callbacks you must implement to enable this:tapToPayReader:didRequestPaymentMethodSelection:availablePaymentOptions:completionto allow your application to choose the payment method type the customer wants.tapToPayReader:didRequestQrCodeDisplay:qrData:completion:to display the QR code.- To request access to this feature, please contact Stripe Support.
Updates
- When connecting to a Tap to Pay on iPhone reader, the SDK now validates device compatibility before making any API calls. Incompatible devices will return an error consistent with
supportsReadersOfType. - Improved Tap to Pay error handling on the
connectReaderfunction. If the app is backgrounded during an Apple proximity reader update, the connection failure is now returned when the app returns to the foreground, rather than being returned immediately.
Fixes
- Fixes an issue where the Tap to Pay reader reconnection fails when the app comes to the foreground, caused by an internal race condition.
5.1.1
- Built with Xcode 26.0 Swift version 6.2.
Fixes
- Fixes a crash that could occur during
disconnectReaderwith internet readers.