Troubleshooting — iOS

Quick diagnosis

Symptom	Likely Cause	Solution
Error screen with retry button	Invalid or expired client token	Generate a fresh `clientToken` from your server for each session
No payment methods shown	Dashboard misconfiguration or unsupported currency/country	Verify Dashboard settings and `currencyCode`/`countryCode` in client session
Composable views render nothing	`.primerCheckoutSession` modifier missing above them, or session not yet `.ready`	Apply `.primerCheckoutSession(_:onCompletion:)` around the views; they bind once the session reaches `.ready`
Session re-initializes unexpectedly	`PrimerCheckoutSession` recreated on view updates	Hold the session as a `@StateObject`, not a `let` or `@State` value
Theme or settings not applied	`PrimerCheckoutTheme`/`PrimerSettings` created inside view `body`	Define as constants outside the view body
Delegate callbacks never fire (UIKit)	`PrimerCheckoutPresenterDelegate` not set or deallocated	Set `delegate` on `.shared` before calling `presentCheckout` and retain the delegate
Apple Pay not available	Simulator, no cards in Wallet, or merchant ID mismatch	Test on a real device with cards in Wallet; verify Apple Developer & Dashboard config
Card form shows invalid despite filled fields	Hidden billing fields are also required	Inspect `fieldErrors` on the `PrimerCardFormSession` handed to your card-form slot
Payment fails after submission	Declined card, network issue, or processor error	Handle the `.failure(PrimerError)` terminal state and log `diagnosticsId`
Build error on iOS 14	Minimum deployment target not met	Set deployment target to iOS 15.0+

Configuration and initialization

Error screen after initialization

Cause: Invalid, expired, or malformed client token. The SDK shows an error screen with a retry button — not a blank screen. Solution: Generate a fresh clientToken from your server for each checkout session. Client tokens are single-use and expire.

PrimerCheckout(
  clientToken: freshClientToken, // Always fetch from your server
  onCompletion: { state in
    if case .failure(let error) = state {
      print("[Primer] Error: \(error.errorId)")
      print("[Primer] Description: \(error.errorDescription ?? "N/A")")
      print("[Primer] Diagnostics: \(error.diagnosticsId)")
    }
  }
)

If you see invalid-client-token in the error, your token has expired or was already consumed. Generate a new one from your server.

Payment methods not showing

Cause: Multiple possible causes:

No payment methods configured in the Primer Dashboard for the given currency/country
The SDK only renders payment methods it supports — unsupported types are silently filtered out
Client session missing required currencyCode or countryCode fields

Solution: Check the Xcode console for log messages like "Filtering out unregistered payment method: TYPE". Verify your Dashboard configuration matches the currency and country in your client session. When using the composable PrimerPaymentMethods view, read the available methods from session.selection?.state.paymentMethods.

SwiftUI integration

Composable views render nothing

Cause: The composable views — PrimerCardForm, PrimerPaymentMethods, and PrimerVaultedPaymentMethods — resolve their session from the SwiftUI environment. Without the .primerCheckoutSession(_:onCompletion:) modifier above them, they have no session to bind to. They also stay empty until the session reaches .ready.

A composable view without .primerCheckoutSession above it in the hierarchy cannot resolve a session and will not function. This is the most common cause of “nothing renders” issues.

Solution: Hold a PrimerCheckoutSession as a @StateObject and attach the modifier once around your composable views. The modifier injects the session, the derived PrimerCardFormSession, and the PrimerSelectionSession into the environment, calls start() on appear, and tears the session down on disappear:

struct CheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession

  init(clientToken: String) {
    _session = StateObject(
      wrappedValue: PrimerCheckoutSession(clientToken: clientToken)
    )
  }

  var body: some View {
    ScrollView {
      VStack(spacing: 24) {
        PrimerPaymentMethods()
        PrimerCardForm()
      }
    }
    .primerCheckoutSession(session) { state in
      // Receives the terminal PrimerCheckoutState exactly once.
    }
  }
}

If you only need the prebuilt screens, use the managed PrimerCheckout view instead — it owns its own session and requires no modifier.

Session re-initializes unexpectedly

Cause: PrimerCheckoutSession is recreated whenever SwiftUI re-evaluates the enclosing body. Storing it in a let, a computed property, or @State (initialized inline) causes a fresh session — and a fresh client-token initialization — on every view update. Solution: Own the session as a @StateObject so SwiftUI keeps a single instance for the lifetime of the view:

// WRONG: a new session (and re-initialization) on every body evaluation
struct CheckoutView: View {
  let session = PrimerCheckoutSession(clientToken: clientToken)
  var body: some View { ... }
}

// CORRECT: one session for the lifetime of the view
struct CheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession

  init(clientToken: String) {
    _session = StateObject(
      wrappedValue: PrimerCheckoutSession(clientToken: clientToken)
    )
  }

  var body: some View { ... }
}

The .primerCheckoutSession modifier drives the lifecycle for you — you normally never call start() or cancel() yourself. Call session.refresh() only when you need to reload after a client-session update (for example, an amount or currency change).

Theme or settings not applied

Cause: Creating PrimerCheckoutTheme() or PrimerSettings() inside the SwiftUI body property. SwiftUI re-evaluates body frequently, creating new objects each time. Solution: Define configuration as constants outside the view body:

private let primerTheme = PrimerCheckoutTheme(
  colors: ColorOverrides(primerColorBrand: .blue)
)
private let primerSettings = PrimerSettings(paymentHandling: .auto)

struct CheckoutView: View {
  let clientToken: String

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

See Best Practices for more SwiftUI performance tips.

UIKit integration

Delegate callbacks never fire

Cause: PrimerCheckoutPresenterDelegate not set on PrimerCheckoutPresenter.shared before calling presentCheckout, or the delegate object was deallocated.

The delegate is a weak reference. Ensure the delegate object (typically your view controller) is retained for the lifetime of the checkout presentation. If the delegate is deallocated, callbacks silently stop.

Solution: Set the delegate before presenting and implement all required methods:

class CheckoutViewController: UIViewController, PrimerCheckoutPresenterDelegate {

  func showCheckout() {
    // Set delegate BEFORE presenting
    PrimerCheckoutPresenter.shared.delegate = self

    PrimerCheckoutPresenter.presentCheckout(
      clientToken: clientToken,
      from: self
    )
  }

  // Required delegate methods
  func primerCheckoutPresenterDidCompleteWithSuccess(_ result: PaymentResult) {
    // Handle successful payment
  }

  func primerCheckoutPresenterDidFailWithError(_ error: PrimerError) {
    print("Payment failed: \(error.errorId)")
  }

  func primerCheckoutPresenterDidDismiss() {
    // Handle checkout dismissed
  }
}

Checkout not presented

Cause: Calling presentCheckout while already presenting — the call is silently ignored with no visible feedback. Solution: Check PrimerCheckoutPresenter.isPresenting before calling:

guard !PrimerCheckoutPresenter.isPresenting else {
  print("Checkout already visible")
  return
}
PrimerCheckoutPresenter.presentCheckout(clientToken: clientToken, from: self)

Card form

Form shows invalid despite all visible fields being filled

Cause: The form validation considers all configured fields, including billing address fields that may not be visible on screen. Backend configuration (the Dashboard-driven CardFormConfiguration) controls which billing fields are required. Solution: Inspect state.fieldErrors on the PrimerCardFormSession to identify which specific fields are failing validation. The session is handed to each PrimerCardForm slot — observe it with @ObservedObject:

PrimerCardForm(cardDetails: { session in
  VStack(alignment: .leading) {
    CardFormDefaults.cardDetails(session)
    ForEach(session.state.fieldErrors) { error in
      Text("\(String(describing: error.fieldType)): \(error.message)")
        .foregroundColor(.red)
        .font(.caption)
    }
  }
})

Use session.state.isValid to gate the submit button and session.state.errorMessage(for:) to display a per-field message.

Apple Pay

Apple Pay not available

Cause: Multiple possible causes:

Running on the iOS Simulator (Apple Pay requires a real device)
No payment cards added to the user’s Wallet
Apple Pay not configured in the Primer Dashboard
Merchant identifier mismatch between Apple Developer portal and Primer Dashboard

Solution: Test on a physical device with a card added to Wallet. Verify Apple Pay configuration in both the Apple Developer portal and Primer Dashboard. There is no separate Apple Pay view or scope — once you configure Apple Pay via PrimerSettings(paymentMethodOptions:) with a PrimerApplePayOptions(merchantIdentifier:), Apple Pay surfaces automatically as a CheckoutPaymentMethod (with type == "APPLE_PAY") in PrimerPaymentMethods, or as a managed screen in PrimerCheckout. If it never appears, confirm the method is present in session.selection?.state.paymentMethods. See the Apple Pay integration guide.

Installation

SPM package not found

Cause: Build fails with “No such module ‘PrimerSDK’”. Solution: Re-add the SPM package:

In Xcode, go to File > Add Package Dependencies
Enter the Primer SDK repository URL
Select the correct version and add to your target

CocoaPods installation fails

Cause: pod install fails or doesn’t include the Primer SDK. Solution: Verify your Podfile and reinstall:

# Podfile
pod 'PrimerSDK'

pod install --repo-update

Minimum deployment target

Cause: Crash or build error on iOS 14 or earlier. Solution: The Primer Checkout iOS SDK requires iOS 15.0 or later. Update your deployment target:

// In Xcode: General > Deployment Info > iOS 15.0

Validation vs payment errors

Understanding the difference helps with proper error handling:

Error Type	When It Occurs	How It’s Handled
Validation errors	During input (invalid format, missing fields)	Handled automatically by input components; prevents form submission
Payment failures	After form submission (declined card, network issues)	Requires explicit handling with error container or custom code

Don’t confuse these two error types. Validation errors prevent form submission and are shown inline. Payment failures occur after the form is submitted and require explicit handling.

Debugging tips

Log the terminal state

The onCompletion closure on PrimerCheckout or the .primerCheckoutSession(_:onCompletion:) modifier fires exactly once with the terminal PrimerCheckoutState:

PrimerCheckout(clientToken: clientToken) { state in
  print("[Primer] Terminal state: \(state)")
}

For the composable flow, log it from the modifier instead:

.primerCheckoutSession(session) { state in
  print("[Primer] Terminal state: \(state)")
}

Inspect available payment methods

Read the available methods from the PrimerSelectionSession once the session is .ready:

if let methods = session.selection?.state.paymentMethods {
  for method in methods {
    print("[Primer] Available: \(method.type) (\(method.name))")
  }
}

Check session readiness

The composable views bind only once the session reaches .ready. Observe session.phase to confirm initialization completed and the child sessions resolved:

print("[Primer] Phase: \(session.phase)")
print("[Primer] Card form ready: \(session.cardForm != nil)")
print("[Primer] Selection ready: \(session.selection != nil)")

Log card form validation errors

Read fieldErrors from the PrimerCardFormSession handed to a PrimerCardForm slot:

PrimerCardForm(submitButton: { session in
  let _ = session.state.fieldErrors.forEach { error in
    print("[Primer] Field error - \(error.fieldType): \(error.message)")
  }
  return CardFormDefaults.submitButton(session)
})

Extract diagnostics for support

if case .failure(let error) = state {
  print("[Primer] Error ID: \(error.errorId)")
  print("[Primer] Description: \(error.errorDescription ?? "N/A")")
  print("[Primer] Diagnostics ID: \(error.diagnosticsId)")
  print("[Primer] Recovery: \(error.recoverySuggestion ?? "N/A")")
}

Getting help

When contacting Primer support, include:

The diagnosticsId from any error callbacks
Your iOS version, Xcode version, and SDK version
Steps to reproduce the issue

if case .failure(let error) = state {
  print("Include in support request:")
  print("  Error ID: \(error.errorId)")
  print("  Description: \(error.errorDescription ?? "N/A")")
  print("  Diagnostics ID: \(error.diagnosticsId)")
  print("  Recovery: \(error.recoverySuggestion ?? "N/A")")
}

Events guide

Event handling patterns

Build a custom card form

Card form tutorial

Best practices

SwiftUI performance tips

​Quick diagnosis

​Configuration and initialization

​Error screen after initialization

​Payment methods not showing

​SwiftUI integration

​Composable views render nothing

​Session re-initializes unexpectedly

​Theme or settings not applied

​UIKit integration

​Delegate callbacks never fire

​Checkout not presented

​Card form

​Form shows invalid despite all visible fields being filled

​Apple Pay

​Apple Pay not available

​Installation

​SPM package not found

​CocoaPods installation fails

​Minimum deployment target

​Validation vs payment errors

​Debugging tips

​Log the terminal state

​Inspect available payment methods

​Check session readiness

​Log card form validation errors

​Extract diagnostics for support

​Getting help

​See also

Events guide

Build a custom card form

Best practices

Quick diagnosis

Configuration and initialization

Error screen after initialization

Payment methods not showing

SwiftUI integration

Composable views render nothing

Session re-initializes unexpectedly

Theme or settings not applied

UIKit integration

Delegate callbacks never fire

Checkout not presented

Card form

Form shows invalid despite all visible fields being filled

Apple Pay

Apple Pay not available

Installation

SPM package not found

CocoaPods installation fails

Minimum deployment target

Validation vs payment errors

Debugging tips

Log the terminal state

Inspect available payment methods

Check session readiness

Log card form validation errors

Extract diagnostics for support

Getting help

See also