Handle the payment result

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

Every checkout ends in one of three outcomes: the payment succeeds, it fails, or the user dismisses the flow. This guide shows how to receive and react to that outcome in both SwiftUI and UIKit. The outcome is always delivered as a PrimerCheckoutState value:

Case	Associated value	Meaning
`.success`	`PaymentResult`	The payment completed.
`.failure`	`PrimerError`	The payment or checkout failed.
`.dismissed`	—	The user closed the checkout without completing a payment.

The same PrimerCheckoutState also has lifecycle cases (.initializing, .ready) that you do not need to handle when reacting to the final outcome. Always include a default case when switching, so future enum additions stay source-compatible.

SwiftUI

Using PrimerCheckout

The prebuilt PrimerCheckout view accepts an onCompletion closure that fires once with the final state.

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String
  @State private var paymentResult: PaymentResult?

  var body: some View {
    if let paymentResult {
      ConfirmationView(result: paymentResult)
    } else {
      PrimerCheckout(clientToken: clientToken) { state in
        switch state {
        case let .success(result):
          paymentResult = result
        case let .failure(error):
          print("Checkout failed: \(error.errorId) — \(error.diagnosticsId)")
        case .dismissed:
          break
        default:
          break
        }
      }
    }
  }
}

Using the .primerCheckoutSession modifier

When you embed the composable views (for example PrimerCardForm) inline in your own layout, hold a PrimerCheckoutSession as a @StateObject and receive the outcome through the onCompletion parameter of the .primerCheckoutSession(_:onCompletion:) modifier.

import SwiftUI
import PrimerSDK

struct InlineCheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession
  @State private var paymentResult: PaymentResult?

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

  var body: some View {
    Group {
      if let paymentResult {
        ConfirmationView(result: paymentResult)
      } else {
        ScrollView {
          PrimerCardForm()
        }
      }
    }
    .primerCheckoutSession(session) { state in
      switch state {
      case let .success(result):
        paymentResult = result
      case let .failure(error):
        print("Checkout failed: \(error.errorId) — \(error.diagnosticsId)")
      case .dismissed:
        break
      default:
        break
      }
    }
  }
}

.success and .dismissed are delivered at most once — the session latches the first state that ends it, so a later .dismissed produced by a view-lifecycle teardown is ignored..failure is different. Once checkout is ready, a failed payment attempt does not end the session: the SDK shows its error screen, the customer can retry, and onCompletion is called again with the next attempt’s outcome. Only a failure before the checkout becomes ready is terminal. Keep your checkout UI alive on .failure — otherwise a customer who retries after a decline and then succeeds never reaches your success handling.

Navigating on success

Use the PaymentResult to drive navigation. PaymentResult is Equatable but not Hashable, so it cannot be appended to a NavigationPath or used with navigationDestination(for:) directly. Instead, store the result in @State and present the confirmation screen with navigationDestination(isPresented:).

import SwiftUI
import PrimerSDK

struct CheckoutFlowView: View {
  let clientToken: String
  @State private var paymentResult: PaymentResult?

  private var showsConfirmation: Binding<Bool> {
    Binding(
      get: { paymentResult != nil },
      set: { if !$0 { paymentResult = nil } }
    )
  }

  var body: some View {
    NavigationStack {
      PrimerCheckout(clientToken: clientToken) { state in
        if case let .success(result) = state {
          paymentResult = result
        }
      }
      .navigationDestination(isPresented: showsConfirmation) {
        if let paymentResult {
          ConfirmationView(result: paymentResult)
        }
      }
    }
  }
}

UIKit

In UIKit, present the checkout with PrimerCheckoutPresenter and adopt PrimerCheckoutPresenterDelegate to receive the outcome. The presenter dismisses its own modal before calling the relevant delegate method.

import UIKit
import PrimerSDK

final class CheckoutViewController: UIViewController {
  let clientToken: String

  init(clientToken: String) {
    self.clientToken = clientToken
    super.init(nibName: nil, bundle: nil)
  }

  required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }

  func startCheckout() {
    PrimerCheckoutPresenter.shared.delegate = self
    PrimerCheckoutPresenter.presentCheckout(clientToken: clientToken, from: self)
  }
}

extension CheckoutViewController: PrimerCheckoutPresenterDelegate {
  func primerCheckoutPresenterDidCompleteWithSuccess(_ result: PaymentResult) {
    let confirmation = ConfirmationViewController(result: result)
    navigationController?.pushViewController(confirmation, animated: true)
  }

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

  func primerCheckoutPresenterDidDismiss() {
    // User closed the checkout without completing a payment.
  }
}

Set the delegate before calling presentCheckout. If no delegate is set when checkout completes, the outcome is logged and otherwise dropped.

The delegate maps one-to-one onto the SwiftUI PrimerCheckoutState cases:

Delegate method	Equivalent state
`primerCheckoutPresenterDidCompleteWithSuccess(_:)`	`.success(PaymentResult)`
`primerCheckoutPresenterDidFailWithError(_:)`	`.failure(PrimerError)`
`primerCheckoutPresenterDidDismiss()`	`.dismissed`

Reading the PaymentResult

On success you receive a PaymentResult. Read its properties to build your confirmation UI, send analytics, or reconcile against your backend.

Property	Type	Description
`paymentId`	`String`	The Primer payment ID.
`status`	`PaymentStatus`	The payment status: `.pending`, `.success`, or `.failed`.
`token`	`String?`	The payment method token, when available.
`redirectUrl`	`String?`	A redirect URL, when the flow requires one.
`errorMessage`	`String?`	A human-readable error message, when present.
`amount`	`Int?`	The amount in minor units (for example, cents for USD).
`currencyCode`	`String?`	The ISO 4217 currency code (for example, `"USD"`).
`paymentMethodType`	`String?`	The payment method type used (for example, `"PAYMENT_CARD"`).

import SwiftUI
import PrimerSDK

struct ConfirmationView: View {
  let result: PaymentResult

  var body: some View {
    VStack(spacing: 12) {
      Text("Payment confirmed")
        .font(.title2.bold())
      Text("Payment ID: \(result.paymentId)")
      if let amount = result.amount, let currency = result.currencyCode {
        Text("Charged: \(amount) \(currency)")
      }
    }
  }
}

status is usually .success for a .success(PaymentResult) outcome. Payment methods that settle later, such as bank transfers and vouchers, report .pending until the processor confirms the payment. Primer Checkout creates the payment for you, PrimerSettings(paymentHandling: .manual) is not supported.

Handling the PrimerError

On failure you receive a PrimerError. The SDK already surfaces failures inside the checkout UI, so you typically use the error for logging, analytics, and support workflows rather than for displaying a message yourself.

Property	Type	Description
`errorId`	`String`	A stable, machine-readable identifier for the error category.
`diagnosticsId`	`String`	A unique ID for this specific occurrence — include it in support requests.
`errorDescription`	`String?`	A formatted description combining the error ID, message, and diagnostics ID.
`recoverySuggestion`	`String?`	A suggested recovery action, when one is available.

func report(_ error: PrimerError) {
  analytics.track("checkout_failed", properties: [
    "error_id": error.errorId,
    "diagnostics_id": error.diagnosticsId
  ])

  if let suggestion = error.recoverySuggestion {
    print("Recovery: \(suggestion)")
  }
}

Always log diagnosticsId. Primer support uses it to trace the exact failed request when you raise an issue.

PrimerCheckoutState

The full state enum and the PaymentResult model.

PrimerError

Error categories, IDs, and diagnostics.

PrimerCheckoutPresenter

The UIKit entry point and delegate callbacks.

PrimerCheckout

The prebuilt SwiftUI checkout view.

​SwiftUI

​Using PrimerCheckout

​Using the .primerCheckoutSession modifier

​Navigating on success

​UIKit

​Reading the PaymentResult

​Handling the PrimerError

​See also

PrimerCheckoutState

PrimerError

PrimerCheckoutPresenter

PrimerCheckout

SwiftUI

Using PrimerCheckout

Using the .primerCheckoutSession modifier

Navigating on success

UIKit

Reading the PaymentResult

Handling the PrimerError

See also