5.5.0 2026-05-04

New

• Preview: Surcharging - Refactored the surcharge API surface.
  • Added new SCPSurchargeDetails class with amount, maximumAmount, and status on SCPAmountDetails.surcharge.
  • Breaking: SCPSurcharge class (under SCPCardPresentParameters) has been removed. Use SCPSurchargeDetails for maximumAmount and status. status is now a SCPSurchargeStatus enum instead of NSString.
  • Breaking: SCPPaymentIntent.amountSurcharge (top-level) has been removed. Use SCPAmountDetails.surcharge.amount instead.
  • To request access to this feature, please contact Stripe Support.
• 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 simulatedOfflineModeConfiguration property and setSimulatedOfflineModeConfiguration:error: method to SCPTerminal.
  • Added SCPSimulatedOfflineModeConfiguration and SCPSimulatedOfflineModeConfigurationBuilder to configure SDK and reader offline behavior independently.
  • Added SCPSimulatedOfflineMode enum with values: disabled, offlineImmediate, offlineTimeout, and offlineIntermittent.
  • Returns SCPErrorSimulatedOfflineModeNotAvailableForAccount if you do not have access, and SCPErrorSimulatedOfflineModeNotAvailableInLivemode if connected to a livemode reader.
  • To request access to this feature, please contact Stripe Support.
• Added support for simulating software update scenarios on physical mobile readers in test mode.
  • Added SCPTestReaderUpdate and SCPTestReaderUpdateType with scenarios: available, required, required-for-offline, and low battery.
  • Set testReaderUpdate on SCPBluetoothConnectionConfiguration or SCPUsbConnectionConfiguration before connecting.
  • SCPSimulatorConfiguration.availableReaderUpdate is deprecated in favor of this new per-connection API.

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 SCPErrorGenericReaderError instead of SCPErrorUnexpectedSdkError.

Fixes

• Fixes #374: Fixed a race condition that could cause a crash during mobile reader discovery over Bluetooth.