> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure Primer Checkout behavior with PrimerSettings

`PrimerSettings` controls how Primer Checkout processes payments and displays the UI. Pass it to `PrimerCheckout` to customize behavior.

## Basic usage

```swift theme={"dark"}
let settings = PrimerSettings(
  paymentHandling: .auto
)

PrimerCheckout(
  clientToken: clientToken,
  primerSettings: settings
)
```

## PrimerSettings

```swift theme={"dark"}
PrimerSettings(
  paymentHandling: PrimerPaymentHandling = .auto,
  uiOptions: PrimerUIOptions? = nil,
  paymentMethodOptions: PrimerPaymentMethodOptions? = nil
)
```

### Parameters

| Parameter              | Type                          | Default | Description                                                                                         |
| ---------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `paymentHandling`      | `PrimerPaymentHandling`       | `.auto` | Controls whether Primer handles the full payment flow or returns a token for server-side processing |
| `uiOptions`            | `PrimerUIOptions?`            | `nil`   | UI display preferences                                                                              |
| `paymentMethodOptions` | `PrimerPaymentMethodOptions?` | `nil`   | Payment method-specific configuration                                                               |

## Payment handling

| Value     | Description                                                                                                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `.auto`   | Primer handles the complete payment flow including tokenization and payment creation. This is the recommended approach. |
| `.manual` | Primer returns a payment method token. You handle payment creation on your server.                                      |

### Auto (recommended)

```swift theme={"dark"}
let settings = PrimerSettings(paymentHandling: .auto)

PrimerCheckout(
  clientToken: clientToken,
  primerSettings: settings,
  onCompletion: { state in
    switch state {
    case .success(let result):
      print("Payment complete: \(result.payment?.id ?? "")")
    case .failure(let error):
      print("Payment failed: \(error.errorId)")
    default:
      break
    }
  }
)
```

### Manual

```swift theme={"dark"}
let settings = PrimerSettings(paymentHandling: .manual)

PrimerCheckout(
  clientToken: clientToken,
  primerSettings: settings,
  onCompletion: { state in
    switch state {
    case .success(let result):
      // Send token to your server for payment creation
      if let token = result.paymentMethodData?.token {
        createPaymentOnServer(token: token)
      }
    default:
      break
    }
  }
)
```

## Define settings as constants

<Tip>
  Define your settings outside the view body to avoid unnecessary re-creation on each SwiftUI render cycle.
</Tip>

```swift theme={"dark"}
// Define once at the top level
private let primerSettings = PrimerSettings(
  paymentHandling: .auto
)

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerSettings: primerSettings
    )
  }
}
```

## See also

<CardGroup cols={2}>
  <Card title="State and events" icon="bolt" href="/sdk/ios-checkout/v3.0.0-beta/configuration/state-events">
    Handle checkout lifecycle states
  </Card>

  <Card title="Best practices" icon="check" href="/checkout/primer-checkout/configuration/best-practices">
    Recommended patterns for configuration
  </Card>

  <Card title="Common objects" icon="cube" href="/sdk/ios-checkout/v3.0.0-beta/api-reference/common-objects">
    PrimerSettings API reference
  </Card>
</CardGroup>