> ## 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.

# start

Create a session and start Headless Universal Checkout with its `clientToken` and your custom settings.
Once the session is configured on the SDK the completion handler will be called.

```swift SWIFT theme={"dark"}
func start(
    withClientToken clientToken: String,
    settings: PrimerSettings? = nil,
    delegate: PrimerHeadlessUniversalCheckoutDelegate? = nil,
    uiDelegate: PrimerHeadlessUniversalCheckoutUIDelegate? = nil,
    completion: @escaping (_ paymentMethods: [PrimerHeadlessUniversalCheckout.PaymentMethod]?, _ err: Error?) -> Void
)
```

## Parameters

<Expandable title="Parameters" defaultOpen>
  <ResponseField name="clientToken" type="String" required>
    Client token as returned by the [create client session](/checkout/client-session#create-a-client-session) call
  </ResponseField>

  <ResponseField name="settings" type="PrimerSettings" post={["Optional"]}>
    <Expandable title="Properties" defaultOpen>
      <ResponseField name="paymentHandling" type="enum PrimerPaymentHandling">
        Use this to set you payment handling flow. Defaults to `.auto`.

        <Expandable title="Cases" defaultOpen>
          <ResponseField name="auto" type="default">
            Primer SDK will create the payment and handle the flow.
          </ResponseField>

          <ResponseField name="manual">
            If you use the manual flow, make sure you add the `primerDidTokenizePaymentMethod(_:decisionHandler:)` delegate function of `PrimerDelegate`, create a payment on your backend and call the `decisionHandler` of the delegate function once you receive your backend's response.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="localeData" type="PrimerLocaleData">
        Forces some payment methods' locale.

        <Expandable title="Properties" defaultOpen>
          <ResponseField name="languageCode" type="String" required>
            Forces the language code (e.g. `en`). Defaults on your app's language code if available.
          </ResponseField>

          <ResponseField name="regionCode" type="String">
            Forces the language code (e.g. `US`). Defaults on your app's region code if available.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="paymentMethodOptions" type="PrimerPaymentMethodOptions">
        <Expandable title="Properties" defaultOpen>
          <ResponseField name="urlScheme" type="String">
            ⚠️ Required for some payment methods (e.g. PayPal). <br /><br />This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.
          </ResponseField>

          <ResponseField name="applePayOptions" type="PrimerApplePayOptions">
            ⚠️ Required when using Apple Pay in your integration.

            <Expandable title="Properties" defaultOpen>
              <ResponseField name="merchantIdentifier" type="String" required>
                Set it to the merchant identifier as it is shown in your Apple Pay
                certificate.
              </ResponseField>

              <ResponseField name="merchantName" type="String" deprecated>
                Set it to the merchant name that you want to be shown on the Apple Pay screen. Deprecated, use [ClientSession](/api-reference/v2.4/api-reference/client-session-api/create-a-client-session) instead.
              </ResponseField>

              <ResponseField name="isCaptureBillingAddressEnabled" type="Bool">
                Defaults to `false`. Set to `true` to let Apple Pay capture the customer's billing address.

                Use BillingOptions to configure required billing fields.
              </ResponseField>

              <ResponseField name="showApplePayForUnsupportedDevice" type="Bool">
                If in some cases you don't want to present ApplePay option if the device is not supporting it set this to `false`. The default value is `true`.

                Default value is `true`. Set to `false` if you do not want to present
                Apple Pay option on unsupported devices.
              </ResponseField>

              <ResponseField name="checkProvidedNetworks" type="Bool">
                Flag introduced to enable the initiation of the ApplePay flow even when no cards are present in the Wallet. To enable the feature, set this to `false`. The default value `true`.

                Default value is `true`. This flag supports the old behavior where Apple
                Pay flow might not present if there are no cards in the Wallet.
              </ResponseField>

              <ResponseField name="shippingOptions" type="ShippingOptions">
                Configure shipping options for Apple Pay.

                <Expandable title="Properties" defaultOpen>
                  <ResponseField name="shippingContactFields" type="Array of RequiredContactField">
                    Specify which contact fields are required for shipping.
                  </ResponseField>

                  <ResponseField name="requireShippingMethod" type="Bool">
                    Indicate if a shipping method is required.
                  </ResponseField>
                </Expandable>
              </ResponseField>

              <ResponseField name="billingOptions" type="BillingOptions">
                Configure billing options for Apple Pay.

                <Expandable title="Properties" defaultOpen>
                  <ResponseField name="requiredBillingContactFields" type="Array of RequiredContactField">
                    Specify which contact fields are required for billing.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="klarnaOptions" type="PrimerKlarnaOptions">
            ⚠️ Required when using Klarna in your integration.

            <Expandable title="Properties" defaultOpen>
              <ResponseField name="recurringPaymentDescription" type="String" required>
                Set the payment description that will be shown on the Klarna screen.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="threeDsOptions" type="PrimerThreeDsOptions">
            <Expandable title="Properties" defaultOpen>
              <ResponseField name="threeDsAppRequestorUrl" type="String">
                Set the [iOS Universal Link](https://developer.apple.com/ios/universal-links/) that's used to call your app after an **out-of-band (OOB)** authentication.
                Supported in 3D Secure protocol versions 2.2.0 and after.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="stripeOptions" type="PrimerStripeOptions">
            ⚠️ Required when using Stripe ACH in your integration.

            <Expandable title="Properties" defaultOpen>
              <ResponseField name="publishableKey" type="String?">
                Set the [Stripe publishable key](https://docs.stripe.com/keys#obtain-api-keys/).
              </ResponseField>

              <ResponseField name="mandateData" type="MandateData?">
                One of:

                <Expandable title="Options" defaultOpen>
                  <ResponseField name="fullMandate(text:)" type="MandateData">
                    The full `text` that you would like to be displayed to the user before
                    they accept/decline the mandate.
                  </ResponseField>

                  <ResponseField name="templateMandate(merchantName:)" type="MandateData">
                    A `merchantName` that will be used as part of our predefined mandate template.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="uiOptions" type="PrimerUIOptions">
        Set the `uiOptions` for custom UI options of the Primer SDK.

        <Expandable title="Properties" defaultOpen>
          <ResponseField name="isInitScreenEnabled" type="Bool">
            Set to `false` to hide the loading screen before the Universal Checkout or the Vault Manager. Defaults to `true`.
          </ResponseField>

          <ResponseField name="isSuccessScreenEnabled" type="Bool">
            Set to `false` to hide the screen after a successful payment, or tokenization on the vault flow. Defaults to `true`.
          </ResponseField>

          <ResponseField name="isErrorScreenEnabled" type="Bool">
            Set to `false` to hide the error screen when an error occurs. Defaults to `true`.
          </ResponseField>

          <ResponseField name="dismissalMechanism" type="enum DismissalMechanism">
            Set the mechanism for dismissing Universal Checkout. Options are:

            * `gestures`: The dialog can be dismissed by tapping outside or by swiping down.
            * `closeButton`: A close button is provided, allowing users to dismiss the dialog manually.
          </ResponseField>

          <ResponseField name="theme" type="PrimerTheme">
            Set a custom theme for Primer SDK.
          </ResponseField>

          <ResponseField name="appearanceMode" type="enum PrimerAppearanceMode">
            Control the SDK's appearance mode independently of the system setting. This allows apps to force light or dark mode regardless of the device's appearance setting.

            <Expandable title="Cases" defaultOpen>
              <ResponseField name="system" type="default">
                Follow the system's appearance setting (default behavior).
              </ResponseField>

              <ResponseField name="light">
                Force light mode appearance regardless of system setting.
              </ResponseField>

              <ResponseField name="dark">
                Force dark mode appearance regardless of system setting.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="cardFormUIOptions" type="PrimerCardFormUIOptions?">
            Configure the card form UI options.

            <Expandable title="Properties" defaultOpen>
              <ResponseField name="payButtonAddNewCard" type="Bool">
                When set to true, the Drop-In's card form pay button will show "Add new card"; otherwise it will show "Pay \$x.xx".
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="debugOptions" type="PrimerDebugOptions">
        <Expandable title="Properties" defaultOpen>
          <ResponseField name="is3DSSanityCheckEnabled" type="Bool" required />
        </Expandable>
      </ResponseField>

      <ResponseField name="clientSessionCachingEnabled" type="Bool" post={["Default: false"]}>
        <Warning>
          Before enabling the flag to true it's recommended to reach out to Primer
          support for additional verification since there are edge cases where it's not
          advised.
        </Warning>

        Indicates whether client session caching is enabled.

        When set to `true`, responses from the server will be cached on the client side, allowing for faster subsequent
        access to the same data within the cache duration. When set to `false`, every request to the server will be
        processed without utilizing any client-side cache, ensuring that the client always receives the most up-to-date data.
      </ResponseField>

      <ResponseField name="apiVersion" type="PrimerApiVersion" post={["Default: PrimerApiVersion.V2_4"]}>
        Indicates the API version to use when interacting with the Primer backend. Options are:

        * `PrimerApiVersion.V2_4` - will use ApiVersion 2.4

        Note that this is optional, if a value is not supplied, ApiVersion `V2.4` will be used by default.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="delegate" type="PrimerHeadlessUniversalCheckoutDelegate" post={["Optional"]}>
    Set the delegate to receive updates of the checkout lifecycle.
  </ResponseField>

  <ResponseField name="uiDelegate" type="PrimerHeadlessUniversalCheckoutUIDelegate" post={["Optional"]}>
    Set the UI delegate to receive UI updates.
  </ResponseField>

  <ResponseField name="completion" type="(_ paymentMethods: [PrimerHeadlessUniversalCheckout.PaymentMethod]?, _ err: Error?) -> Void" post={["Optional"]}>
    The completion handler will be called once the session has been configured on the SDK, and it will provide you with available payment methods for the session
  </ResponseField>
</Expandable>