# iOS SDK integration

A guide to integrating the Peach Orchestration mobile SDK into a native iOS app using Swift and the `Hyperswitch` framework. Minimum: iOS 15.1+.

## What this page covers
- Ten sections: Prerequisites, Installation, Configuration, Basic integration, Payment methods, Saved cards, Error handling, Customisation, Testing, Troubleshooting
- Xcode/Swift prerequisites and getting Dashboard credentials (publishable key `pk_snd_xxx`/`pk_prd_xxx`)
- Installing via CocoaPods (or Swift Package Manager for the authentication module)
- Creating and presenting the `PaymentSheet` with a `client_secret` from your backend
- Payment methods: cards, Apple Pay, Google Pay (Catalyst), bank redirects, PayJustNow (BNPL)
- Saved cards via customer configuration + ephemeral keys, and Setup Intents
- Theming with `PaymentSheet.Appearance`, dark mode, error handling and retry logic
- Test cards, XCTest unit/UI tests, and troubleshooting (Apple Pay, 3DS, deep links)

## Key steps / API

Package: `pod 'hyperswitch-sdk-ios'` (optional subspecs `/scancard`, `/netcetera3ds`). Import with `import Hyperswitch`. SPM exposes the `HyperswitchAuthentication` library.

```swift
import Hyperswitch

// 1. Create the session with your publishable key
let paymentSession = PaymentSession(
    publishableKey: "pk_test_your_publishable_key",
    customBackendUrl: "https://app.sandbox-next.peachpayments.com/api"
)

// 2. Initialise with a client secret fetched from your server
paymentSession.initPaymentSession(paymentIntentClientSecret: clientSecret)

// 3. Present the payment sheet
let configuration = PaymentSheet.Configuration()
paymentSession.presentPaymentSheet(viewController: self, configuration: configuration) { result in
    switch result {
    case .completed(let data): // success
    case .canceled(let data):  // user dismissed
    case .failed(let error):   // error
    }
}
```

Other real API surface referenced in the source:
- `PaymentSheet.Configuration` fields: `merchantDisplayName`, `applePay` (`PaymentSheet.ApplePayConfiguration`), `googlePay` (`PaymentSheet.GooglePayConfiguration`), `returnURL`, `paymentMethodOrder`, `customer` (`PaymentSheet.CustomerConfiguration(id:ephemeralKeySecret:)`), `savePaymentMethodOptIn`
- `PaymentSession.handleURLCallback(url)` — handle 3DS/redirect return in `AppDelegate`
- Setup Intent: construct `PaymentSheet(setupIntentClientSecret:configuration:)` to save a card without charging
- Theming: `PaymentSheet.Appearance` with `.colors`, `.cornerRadius`, `.borderWidth`, `.shadow`, `.font`, `.primaryButton`
- SwiftUI: `PaymentSheet.PaymentButton(paymentSession:configuration:onCompletion:)`

Sandbox API base is `https://app.sandbox-next.peachpayments.com/api`; production is `https://app.next.peachpayments.com/api`. Apple Pay requires the merchant ID and certificates to be configured on your Peach Payments account.

## Related
- [iOS SDK customisation](/sdk-customization-ios.md): live simulator that restyles the iOS payment sheet
- [Android SDK](/sdk-mobile-android.md): native Android equivalent
- [Web SDK](/sdk-web.md): browser integration
- [API Playground](/playground.md): create a payment intent and get a `client_secret`
- [Testing](/docs/testing.md): test cards and sandbox guidance

---

Interactive version: https://playground.peachpayments.com/sdk-mobile/ios