PrimerSelectionSession

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.5). The API is subject to change before the stable release.

PrimerSelectionSession is the observable session that drives payment-method selection. It exposes the available methods, the current selection, search and filtering state, and vaulted-card actions (including CVV recapture) as a single @Published state value, and provides the methods that mutate that state. A single PrimerSelectionSession backs both PrimerPaymentMethods (the list of available methods) and PrimerVaultedPaymentMethods (saved methods). Both views resolve the same session from the environment supplied by the .primerCheckoutSession(_:) modifier, so you rarely construct or hold it yourself — you read it from the slots those views hand you.

PrimerSelectionSession is a @MainActor, ObservableObject final class available on iOS 15.0 and later (@available(iOS 15.0, *)). Observe it with @ObservedObject and call its methods from the main actor.

Declaration

@available(iOS 15.0, *)
@MainActor
public final class PrimerSelectionSession: ObservableObject {
  @Published public private(set) var state: PrimerPaymentMethodSelectionState
  public var vaultedPaymentMethods: [PrimerHeadlessUniversalCheckout.VaultedPaymentMethod] { get }
}

The session is created and injected by the SDK. The slots of PrimerPaymentMethods and PrimerVaultedPaymentMethods receive it directly, so you do not initialize it yourself.

Properties

Property	Type	Description
`state`	`PrimerPaymentMethodSelectionState`	The latest selection state, bridged from the underlying selection scope. Read-only (`@Published public private(set)`) — drive UI from it and call the session’s methods to change it.
`vaultedPaymentMethods`	`[PrimerHeadlessUniversalCheckout.VaultedPaymentMethod]`	Read-only (`@Published public private(set)`). The customer’s saved (vaulted) payment methods. Published, so a list you build yourself re-renders when the set changes, after `delete(_:)` or when the SDK’s own saved-methods screen deletes one. Empty when none are available.

state is the snapshot you render from; vaultedPaymentMethods is the list of saved cards. Which card the SDK’s own screens act on is reflected back through state.selectedVaultedPaymentMethod. Keep the highlight in your own view state.

Methods

Method	Description
`select(_ method: CheckoutPaymentMethod)`	Selects a payment method, starting its flow (card form, redirect, native wallet, etc.).
`cancel()`	Cancels the current selection flow.
`selectVaulted(_ method: PrimerHeadlessUniversalCheckout.VaultedPaymentMethod)`	Pays with a saved payment method. Call it from your pay button, not from a row tap.
`delete(_ method:) async throws`	Deletes a saved payment method, then refreshes `vaultedPaymentMethods`.
`showAll()`	Presents the SDK’s saved-payment-methods screen, where the customer can pick a different method or delete one.

select(_:)

public func select(_ method: CheckoutPaymentMethod)

Selects a payment method to begin its payment flow. Call this from a method row’s tap handler. The selected method is reflected in state.selectedPaymentMethod.

Parameter	Type	Description
`method`	`CheckoutPaymentMethod`	The payment method the user chose. Typically the value passed into the `method` slot of `PrimerPaymentMethods`.

cancel()

public func cancel()

Cancels the in-progress selection flow.

selectVaulted(_:)

public func selectVaulted(_ method: PrimerHeadlessUniversalCheckout.VaultedPaymentMethod)

Pays with a saved payment method. This is the pay verb, so call it from your pay button rather than from a row tap. A card that needs CVV recapture raises the SDK’s CVV screen first, and that screen finishes the payment. The outcome arrives through .primerCheckoutSession(_:theme:onCompletion:). Keep which row looks selected in your own view state. Returns immediately; the payment runs on.

Before 3.0.0-beta.7 this method only marked a method as selected. It now starts a payment. A row tap wired to it will charge the customer.

Parameter	Type	Description
`method`	`PrimerHeadlessUniversalCheckout.VaultedPaymentMethod`	The saved method to select.

delete(_:)

public func delete(_ method: PrimerHeadlessUniversalCheckout.VaultedPaymentMethod) async throws

Deletes a saved payment method and refreshes vaultedPaymentMethods. Throws if the deletion fails, leaving the list unchanged.

Parameter	Type	Description
`method`	`PrimerHeadlessUniversalCheckout.VaultedPaymentMethod`	The saved method to remove.

Deletion is immediate — there is no confirmation step. Add your own if you want one. (The SDK’s own saved-methods screen, reached via showAll(), does confirm before it deletes.)

Button("Delete", role: .destructive) {
    Task {
        do { try await session.delete(method) }
        catch { showError(error) }
    }
}

showAll()

public func showAll()

Presents the SDK’s saved-payment-methods screen: the full list, where the customer can select a different method for payment or delete one. Works in both the managed PrimerCheckout modal and the inline integration.

PrimerVaultedPaymentMethods already wires this into its default header, so you only need to call it directly if you have replaced the header slot or built your own saved-methods UI.

PrimerPaymentMethodSelectionState

PrimerPaymentMethodSelectionState is the immutable snapshot published by state. It conforms to Equatable. Every stored property is public internal(set) — readable from your code but mutated only by the SDK, so treat it as read-only and call the session’s methods to change selection.

@available(iOS 15.0, *)
public struct PrimerPaymentMethodSelectionState: Equatable {
  public internal(set) var paymentMethods: [CheckoutPaymentMethod]
  public internal(set) var isLoading: Bool
  public internal(set) var selectedPaymentMethod: CheckoutPaymentMethod?
  public internal(set) var searchQuery: String
  public internal(set) var filteredPaymentMethods: [CheckoutPaymentMethod]
  public internal(set) var error: String?
  public internal(set) var selectedVaultedPaymentMethod: PrimerHeadlessUniversalCheckout.VaultedPaymentMethod?
  public internal(set) var isVaultPaymentLoading: Bool
  public internal(set) var isPaymentMethodsExpanded: Bool
}

Properties

Property	Type	Description
`paymentMethods`	`[CheckoutPaymentMethod]`	All available payment methods for the current session.
`isLoading`	`Bool`	Whether the available payment methods are still loading.
`selectedPaymentMethod`	`CheckoutPaymentMethod?`	The currently selected available method, or `nil`.
`searchQuery`	`String`	The current search text applied to the method list.
`filteredPaymentMethods`	`[CheckoutPaymentMethod]`	The methods matching `searchQuery`.
`error`	`String?`	An error message for the selection flow, or `nil`.
`selectedVaultedPaymentMethod`	`PrimerHeadlessUniversalCheckout.VaultedPaymentMethod?`	The currently selected saved method, or `nil`.
`isVaultPaymentLoading`	`Bool`	Whether a payment with the selected vaulted method is in progress.
`isPaymentMethodsExpanded`	`Bool`	Whether the payment methods section is expanded (showing all methods). Defaults to `true`; becomes `false` when the user selects a vaulted method.

Because the state is Equatable, SwiftUI only re-renders observers when a meaningful field changes. Drive your custom rows and empty states directly from these properties rather than caching copies.

CheckoutPaymentMethod

paymentMethods and filteredPaymentMethods are arrays of CheckoutPaymentMethod, the model describing a single selectable method. It is documented in full on the PrimerPaymentMethods page; the key fields are id, type, name, icon, and the surcharge and styling properties.

Usage

Reading state and selecting a method

PrimerPaymentMethods hands each method slot a CheckoutPaymentMethod and an onSelect closure that calls select(_:) for you. To select outside a slot — for example from a custom header — call select(_:) on the session directly.

import SwiftUI
import PrimerSDK

struct CheckoutScreen: View {
  @StateObject private var session = PrimerCheckoutSession(clientToken: clientToken)

  var body: some View {
    ScrollView {
      PrimerPaymentMethods(
        method: { paymentMethod, onSelect in
          Button(action: onSelect) {
            HStack {
              if let icon = paymentMethod.icon {
                Image(uiImage: icon)
                  .resizable()
                  .scaledToFit()
                  .frame(width: 28, height: 28)
              }
              Text(paymentMethod.buttonText ?? paymentMethod.name)
              Spacer()
              if let surcharge = paymentMethod.formattedSurcharge {
                Text(surcharge).foregroundColor(.secondary)
              }
            }
            .padding()
          }
          .buttonStyle(.plain)
        }
      )
    }
    .primerCheckoutSession(session) { state in
      handle(state)
    }
  }
}

Working with vaulted methods and CVV recapture

When rendering saved methods, iterate vaultedPaymentMethods, keep the highlight in your own view state, and call selectVaulted(_:) from your pay button. A card that needs CVV recapture raises the SDK’s own CVV screen on submit, and that screen finishes the payment, so there is no CVV field to render and no CVV state to read.

struct SavedMethods: View {
  @ObservedObject var session: PrimerSelectionSession
  @State private var highlighted: String?

  var body: some View {
    VStack(alignment: .leading, spacing: 8) {
      ForEach(session.vaultedPaymentMethods, id: \.id) { method in
        HStack {
          Text(method.paymentMethodType)
          Spacer()
          Button("Select") { highlighted = method.id }
          Button("Delete", role: .destructive) {
            Task { try? await session.delete(method) }
          }
        }
      }

      Button("Pay") {
        guard let method = session.vaultedPaymentMethods
          .first(where: { $0.id == highlighted }) else { return }
        session.selectVaulted(method)
      }
      .disabled(session.state.isVaultPaymentLoading)
    }
  }
}

Never mutate state directly — every property is internal(set). Change selection only through select(_:), selectVaulted(_:), delete(_:), showAll(), and cancel().

PrimerPaymentMethods

The slot-based view that renders the available payment methods.

PrimerVaultedPaymentMethods

Render and select saved (vaulted) payment methods.

PaymentMethodsDefaults

Default slot bodies used by the payment-method views.

PrimerCheckoutSession

The top-level session injected via .primerCheckoutSession(_:).

​Declaration

​Properties

​Methods

​select(_:)

​cancel()

​selectVaulted(_:)

​delete(_:)

​showAll()

​PrimerPaymentMethodSelectionState

​Properties

​CheckoutPaymentMethod

​Usage

​Reading state and selecting a method

​Working with vaulted methods and CVV recapture

​See also

PrimerPaymentMethods

PrimerVaultedPaymentMethods

PaymentMethodsDefaults

PrimerCheckoutSession

Declaration

Properties

Methods

select(_:)

cancel()

selectVaulted(_:)

delete(_:)

showAll()

PrimerPaymentMethodSelectionState

Properties

CheckoutPaymentMethod

Usage

Reading state and selecting a method

Working with vaulted methods and CVV recapture

See also