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

# showUniversalCheckout

```ts theme={"dark"}
showUniversalCheckout(
    clientToken: string,
    options: UniversalCheckoutOptions
): Promise<PrimerCheckout>
```

Showing Drop-in Checkout is the simplest way to integrate with Primer. With just a few lines of code, you can display a fully in-context checkout UI with all your payment methods.

Availing Drop-In Checkout is as easy as implementing one line of code.

```ts theme={"dark"}
import { Primer } from "@primer-io/checkout-web";

const checkout = await Primer.showUniversalCheckout(clientToken, {
  container: "#container",
  onCheckoutComplete(...args) {
    console.log("onCheckoutComplete", ...args);
  },
});
```

Note that there are more options which can be passed to Drop-In Checkout.
Please refer to the section below for more information.

## Parameters

<Expandable defaultOpen>
  <ResponseField name="clientToken" type="string" required>
    A string containing a client token as returned by the Primer API when you
    [create a client session](/checkout/client-session#create-a-client-session).
  </ResponseField>

  <ResponseField name="universalCheckoutOptions" type="object" required>
    When calling `showUniversalCheckout` you can provide Drop-In Checkout with some configuration options. These
    options range from callbacks notifying you of the current payment's status, to styling options for certain UI
    elements.

    <Expandable defaultOpen>
      <ResponseField name="container" type="string | Element" required>
        The container element in which the checkout should be rendered.
      </ResponseField>

      <ResponseField name="locale" type="string">
        This option forces the locale. By default, the locale will be set to the
        browser's locale.
      </ResponseField>

      <ResponseField name="merchantDomain" type="string">
        Optional domain override. **Required for Apple Pay when the checkout is rendered in a cross-origin iframe.**

        For example, if your main page is `example.com` and the iframe checkout is hosted at `iframecheckout.com`,
        you must set this to `example.com` to ensure Apple Pay functions properly.

        **Additional Requirements:**

        * The iframe element must include `allow="payment"` attribute
        * Only supported on Safari 17 or later
      </ResponseField>

      <ResponseField name="apiVersion" type="&#x22;legacy&#x22; | &#x22;2.4&#x22;" post={['Default: "2.4"']}>
        Specifies the API version to use when interacting with the Primer backend.

        * If not explicitly set, defaults to version `'2.4'`.
        * Set this to `'legacy'` if you encounter compatibility issues with the latest API version and wish to revert to the previous stable behavior.
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Payment lifecycle callbacks">
      <ResponseField name="onPaymentCreationStart" type="() => void">
        Notifies you before the checkout tokenizes a payment method and creates a
        payment.
      </ResponseField>

      <ResponseField name="onBeforePaymentCreate" type="(data: object, handler: object) => void">
        Called when a payment will be created.
        Use as an opportunity to update UI accordingly - for example, to display a "loading" component.
        The `handler` must be used to then abort or continue with payment creation.
        Primer will continue with payment creation if `onBeforePaymentCreate` is not implemented.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="data" type="object">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="paymentMethodType" type="string">
                The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types)
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="handler" type="object">
            Provides two methods to continue or abort the payment.

            <Warning>
              You MUST call one of the methods of the handler if `onBeforePaymentCreate` is implemented.
            </Warning>

            Choose to abort a payment.

            ```ts TS theme={"dark"}
            return handler.abortPaymentCreation();
            ```

            Choose to continue with payment creation

            ```ts TS theme={"dark"}
            return handler.continuePaymentCreation();
            ```

            You can also pass an idempotency key which will be sent with the payment request to prevent duplicate payments from being created.

            ```ts TS theme={"dark"}
            return handler.continuePaymentCreation({ idempotencyKey: 'my-unique-key' });
            ```
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="onCheckoutComplete" type="(data: object) => void">
        Called when a payment has been created.
        Move on to next step in your checkout flow, such as showing a success message, etc.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="data" type="object">
            <Expandable title="Properties" defaultOpen>
              <ResponseField name="payment" type="object">
                <Expandable title="Properties" defaultOpen>
                  <ResponseField name="id" type="string">
                    Primer's unique identifier for the payment.
                  </ResponseField>

                  <ResponseField name="orderId" type="string">
                    Your order identifier as provided in the client session.
                  </ResponseField>

                  <ResponseField name="paymentMethodData" type="object">
                    Optional payment method data - for some payment methods this object
                    will contain additional information on the payment.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="onCheckoutFail" type="(error: PrimerClientError, data: object, handler: object) => void">
        Called when the checkout flow has failed.
        This callback can also be used to display an error state within your own UI.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="error" type="PrimerClientError">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="code" type="ErrorCode">
                {" "}
              </ResponseField>

              <ResponseField name="message" type="string">
                {" "}
              </ResponseField>

              <ResponseField name="diagnosticsId" type="Nullable<string>">
                {" "}
              </ResponseField>

              <ResponseField name="data" type="object">
                {" "}
              </ResponseField>

              <ResponseField name="isFromDeveloper" type="boolean">
                {" "}
              </ResponseField>

              <ResponseField name="fromErrorCode" type="(code: ErrorCode, options: ErrorOptions) => PrimerClientError">
                {" "}
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="data" type="object">
            <Expandable title="Properties" defaultOpen>
              <ResponseField name="payment" type="object">
                When checkout fails, the payment might or might not have been created.
                If it was created, the payment object contains some information
                regarding it.

                <Expandable title="Properties" defaultOpen>
                  <ResponseField name="id" type="string">
                    Primer's unique identifier for the payment.
                  </ResponseField>

                  <ResponseField name="orderId" type="string">
                    Your order identifier as provided in the client session.
                  </ResponseField>

                  <ResponseField name="paymentMethodData" type="object">
                    Optional payment method data - for some payment methods this object
                    will contain additional information on the payment.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="handler" type="object">
            Show an error message.

            If `handler` is `undefined`, the SDK does not expect anything from you.

            If `handler` exists, you MUST call one of the functions of the handler.

            ```ts TS theme={"dark"}
            import { Primer } from "@primer-io/checkout-web";

            const checkout = await Primer.showUniversalCheckout(clientToken, {
              container: "#container",
              onCheckoutComplete(...args) {
                console.log("onCheckoutComplete", ...args);
              },
              onCheckoutFail(error, data, handler) {
                if (!handler) {
                  return;
                }

                // Show a default error message
                return handler.showErrorMessage();

                // Or show a custom error message
                // return handler.showErrorMessage('This is my custom message');
              },
            });
            ```

            <Expandable defaultOpen title="Properties">
              <ResponseField name="showErrorMessage" type="(customErrorMessage?: string) => void">
                <Expandable defaultOpen title="Parameters">
                  <ResponseField name="customErrorMessage?: string" type="string">
                    An optional custom error message.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Client session lifecycle callbacks">
      <ResponseField name="onBeforeClientSessionUpdate" type="() => void">
        Called when the client session is in the process of being updated. Use it to
        show a loading indicator on your UI.
      </ResponseField>

      <ResponseField name="onClientSessionUpdate" type="(clientSession: ClientSession) => void">
        Called when the client session has been updated by the checkout. Returns the
        updated client session which can be used to inform your UI. For example
        updating tax, shipping or discount amounts displayed to your customers.
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Event callbacks">
      <ResponseField name="onPaymentMethodAction" type="(action: string, data: object) => void">
        Notifies you when a specific payment method has been selected or unselected.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="action" type="'PAYMENT_METHOD_SELECTED' | 'PAYMENT_METHOD_UNSELECTED'">
            The action being performed on the payment method. Payment will be unselected
            when a popup is closed.
          </ResponseField>

          <ResponseField name="data" type="object">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="paymentMethodType" type="string">
                The type of the payment method Primer will use for payment creation, one of
                [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types)
              </ResponseField>

              <ResponseField name="payment" type="object | undefined">
                The payment object, available when a payment has already been created before the payment method is unselected.

                <Expandable title="Properties">
                  <ResponseField name="id" type="string">
                    The unique identifier of the payment.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Payment methods options">
      <ResponseField name="card" type="object">
        Customize the appearance and behavior of the card fields in the checkout form.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="cardholderName" type="object">
            Options for the cardholder name input field.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="required" type="boolean">
                Whether the cardholder name is required. Only works if the cardholder
                name is visible.
              </ResponseField>

              <ResponseField name="visible" type="boolean">
                Whether the cardholder name input field should be visible.
              </ResponseField>

              <ResponseField name="placeholder" type="string | (options: { locale: string }) => string">
                The placeholder text to display in the cardholder name input field. It
                can be either a string or a function that returns a string. The
                function receives an options object as first argument.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="cardNumber" type="object">
            Customize the placeholder of the card number field.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="placeholder" type="string | (options: { locale: string }) => string">
                The placeholder text to display in the cardholder number input field.
                It can be either a string or a function that returns a string. The
                function receives an options object as first argument.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="expiryDate" type="object">
            Customize the placeholder of the expiry date field.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="placeholder" type="string | (options: { locale: string }) => string">
                The placeholder text to display in the expiry date input field. It can
                be either a string or a function that returns a string. The function
                receives an options object as first argument.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="cvv" type="object">
            Customize the placeholder of the CVV field.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="placeholder" type="string | (options: { locale: string }) => string">
                The placeholder text to display in the CVV input field. It can be
                either a string or a function that returns a string. The function
                receives an options object as first argument.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="preferredFlow" type="&#x22;DEDICATED_SCENE&#x22; | &#x22;EMBEDDED_IN_HOME&#x22;">
            Specify the preferred flow for entering card details.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="redirect" type="object">
        Options for payment methods that rely on redirecting.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="returnUrl" type="string">
            The URL to return to after the redirect process has completed.
          </ResponseField>

          <ResponseField name="forceRedirect" type="boolean">
            Whether to always use a redirect flow, rather than a popup window, even if
            other options are available. Default value is `false`.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="paypal" type="object">
        Options for using PayPal as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="buttonColor" type="&#x22;gold&#x22; | &#x22;blue&#x22; | &#x22;silver&#x22; | &#x22;white&#x22; | &#x22;black&#x22;">
            The color of the PayPal button.
          </ResponseField>

          <ResponseField name="buttonShape" type="&#x22;pill&#x22; | &#x22;rect&#x22;">
            The shape of the PayPal button.
          </ResponseField>

          <ResponseField name="buttonSize" type="&#x22;small&#x22; | &#x22;medium&#x22; | &#x22;large&#x22; | &#x22;responsive&#x22;">
            The size of the PayPal button.
          </ResponseField>

          <ResponseField name="buttonHeight" type="number">
            The height of the PayPal button, in pixels.
          </ResponseField>

          <ResponseField name="buttonLabel" type="&#x22;checkout&#x22; | &#x22;credit&#x22; | &#x22;pay&#x22; | &#x22;buynow&#x22; | &#x22;paypal&#x22; | &#x22;installment&#x22;">
            The label displayed on the PayPal button.
          </ResponseField>

          <ResponseField name="buttonTagline" type="boolean">
            Whether to display the PayPal tagline beneath the button.
          </ResponseField>

          <ResponseField name="paymentFlow" type="&#x22;DEFAULT&#x22; | &#x22;PREFER_VAULT&#x22;">
            The payment flow to use for the PayPal button.
          </ResponseField>

          <ResponseField name="onClick" type="() => void">
            A function to be called when the PayPal button is clicked.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="googlePay" type="object">
        Options for using Google Pay as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="buttonType" type="&#x22;long&#x22; | &#x22;short&#x22; | &#x22;book&#x22; | &#x22;buy&#x22; | &#x22;checkout&#x22; | &#x22;donate&#x22; | &#x22;order&#x22; | &#x22;pay&#x22; | &#x22;plain&#x22; | &#x22;subscribe&#x22;">
            <GooglePayButtonType />
          </ResponseField>

          <ResponseField name="buttonColor" type="&#x22;default&#x22; | &#x22;black&#x22; | &#x22;white&#x22;">
            The color of the Google Pay button.
          </ResponseField>

          <ResponseField name="buttonSizeMode" type="&#x22;fill&#x22; | &#x22;static&#x22;">
            The size mode of the Google Pay button.
          </ResponseField>

          <ResponseField name="onClick" type="() => void">
            A function to be called when the Google Pay button is clicked.
          </ResponseField>

          <ResponseField name="captureBillingAddress" type="boolean">
            Whether to prompt the user to select a billing address.
          </ResponseField>

          <ResponseField name="existingPaymentMethodRequired" type="boolean">
            If set to `true`, this specifies that Google Pay can only be used for payments if the user's Google Pay wallet already contains allowed payment methods. When enabled, the SDK will check if [`IsReadyToPayResponse.paymentMethodPresent`](https://developers.google.com/pay/api/web/reference/response-objects#IsReadyToPayResponse) is also `true` before rendering the Google Pay button. Default value is `false`.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="applePay" type="object">
        Options for using Apple Pay as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="buttonType" type="&#x22;plain&#x22; | &#x22;buy&#x22; | &#x22;set-up&#x22; | &#x22;donate&#x22; | &#x22;check-out&#x22; | &#x22;book&#x22; | &#x22;subscribe&#x22;">
            The type of the Apple Pay button to display.
          </ResponseField>

          <ResponseField name="buttonStyle" type="&#x22;white&#x22; | &#x22;white-outline&#x22; | &#x22;black&#x22;">
            The style of the Apple Pay button.
          </ResponseField>

          <ResponseField name="captureBillingAddress" type="boolean" deprecated>
            Whether to display a prompt for the user to enter their billing address
            during the payment process.
          </ResponseField>

          <ResponseField name="billingOptions" type="object">
            Billing contact configuration options for Apple Pay.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="requiredBillingContactFields" type="(&#x22;postalAddress&#x22; | &#x22;phoneNumber&#x22; | &#x22;emailAddress&#x22;)[]" required>
                An array of string values that specify which required contact
                information fields should be collected during the checkout process.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="shippingOptions" type="object">
            Shipping contact configuration options for Apple Pay.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="requiredShippingContactFields" type="(&#x22;postalAddress&#x22; | &#x22;name&#x22; | &#x22;phoneNumber&#x22; | &#x22;emailAddress&#x22;)[]" required>
                An array of string values that specify which required contact
                information fields should be collected during the checkout process.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="adyenKlarna" type="object">
        Options for using Klarna via Adyen as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="buttonOptions" type="object">
            Options for Klarna button.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="text" type="string">
                Text to be displayed next to the Klarna logo. If provided, it will replace the default `Pay with` text.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="klarna" type="object">
        Options for using Klarna as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="paymentFlow" type="&#x22;DEFAULT&#x22; | &#x22;PREFER_VAULT&#x22;">
            The payment flow of the Klarna payment method.
          </ResponseField>

          <ResponseField name="recurringPaymentDescription" type="string">
            The description of the recurring payment.
          </ResponseField>

          <ResponseField name="allowedPaymentCategories" type="(&#x22;pay_now&#x22; | &#x22;pay_later&#x22; | &#x22;pay_over_time&#x22;)[]">
            An array of string values that specify the allowed payment categories.
          </ResponseField>

          <ResponseField name="buttonOptions" type="object">
            Options for Klarna button.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="text" type="string">
                Text to be displayed next to the Klarna logo. If provided, it will replace the default `Pay with` text.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="directDebit" type="object">
        Options for using direct debit as a payment method.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="customerCountryCode" type="string" required>
            The customer's two-letter country code.
          </ResponseField>

          <ResponseField name="companyName" type="string" required>
            The name of the company or organization accepting payments.
          </ResponseField>

          <ResponseField name="companyAddress" type="string" required>
            The address of the company or organization accepting payments.
          </ResponseField>

          <ResponseField name="customerName" type="string">
            The name of the customer making the payment.
          </ResponseField>

          <ResponseField name="customerEmail" type="string">
            The email address of the customer making the payment.
          </ResponseField>

          <ResponseField name="customerAddressLine1" type="string">
            The first line of the customer's address.
          </ResponseField>

          <ResponseField name="customerAddressLine2" type="string">
            The second line of the customer's address.
          </ResponseField>

          <ResponseField name="customerCity" type="string">
            The city of the customer's address.
          </ResponseField>

          <ResponseField name="customerPostalCode" type="string">
            The postal code of the customer's address.
          </ResponseField>

          <ResponseField name="iban" type="string">
            The International Bank Account Number (IBAN) of the customer's bank
            account.
          </ResponseField>

          <ResponseField name="submitButtonLabels" type="object">
            An object containing the text to display on the submit button for the
            Direct Debit form and mandate.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="form" type="string | (options: { locale: string }) => string">
                The label to display on the submit button for the Direct Debit form.
              </ResponseField>

              <ResponseField name="mandate" type="string | (options: { locale: string }) => string" required>
                The label to display on the submit button for the Direct Debit
                mandate.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="giftCard" type="object">
            Options for using gift cards as a payment method.

            <Expandable defaultOpen title="Properties">
              <ResponseField name="logoSrc" type="string" required>
                The source URL of the button logo.
              </ResponseField>

              <ResponseField name="background" type="string" required>
                The background color of the button.
              </ResponseField>

              <ResponseField name="logoAlt" type="string">
                An alternative text for the button logo.
              </ResponseField>

              <ResponseField name="text" type="string">
                The text to display on the button.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Vault options">
      <ResponseField name="vault" type="object">
        An interface for configuring the display of vaulted payment methods.

        <Expandable defaultOpen title="Properties">
          <ResponseField name="visible" type="boolean">
            Whether the vaulted payment methods are visible or not.

            If this is not necessary for your use case, we recommend setting this to `false` to skip the retrieval of the vault and speed up the loading of the checkout.

            Default value is `true`.
          </ResponseField>

          <ResponseField name="deletionDisabled" type="boolean">
            Whether deleting a vaulted payment method is disabled or enabled.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Customization options">
      <ResponseField name="style" type="CheckoutStyle">
        See the [CheckoutStyle](/sdk/web/v2.x.x/checkout-style/Overview) page.
      </ResponseField>

      <ResponseField name="form" type="object">
        <Expandable defaultOpen title="Properties">
          <ResponseField name="inputLabelsVisible" type="boolean">
            Choose whether to show the label above inputs.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="submitButton" type="object">
        Drop-In Checkout allows you to use your own submit button for submitting forms. By default, the built-in submit button will be favored.

        Note that when disabling the built-in submit button and using your own custom submit button, it is required to implement the [submit](/sdk/web/v2.x.x/primer-checkout/methods/submit) function in order to notify Drop-In Checkout of form submissions.

        When using your own custom submit button, it's important to use the following callbacks to ensure that your submit button is in the correct state and in sync with the checkout as your customers interact with it.

        ```ts TS theme={"dark"}
        const options = {
          /* Other options ... */

          submitButton: {
            useBuiltInButton: false, // Default to true

            // Callback for receiving the submit button's visible state in the current scene
            onVisible(isVisible, context: { currentSceneId }) {
              // Show or hide your custom submit button
            },

            // Callback for receiving the submit button's disabled state in the current scene
            onDisable(isDisabled, context: { currentSceneId }) {
              // Disable or enable your custom submit button
            },

            // Callback for receiving the submit button's loading state in the current scene
            onLoading(isLoading, context: { currentSceneId }) {
              // Show your submit button in a loading state
            },

            // Callback for receiving the submit button's content in the current scene
            onContentChange(content, context: { currentSceneId }) {
              // Set your submit button's content with either the content provided or your own custom content
            },
          },
        };
        ```

        <Expandable defaultOpen title="Properties">
          <ResponseField name="useBuiltInButton" type="boolean">
            Set whether to use built-in submit button or to display your own custom
            button.
          </ResponseField>

          <ResponseField name="amountVisible" type="boolean">
            Set whether the total order amount should be displayed in the submit button
            content.
          </ResponseField>
        </Expandable>

        <Expandable defaultOpen title="Callbacks">
          <ResponseField name="onVisible" type="(isVisible: boolean, context: object) => void">
            Show or hide your custom submit button.

            <Expandable defaultOpen title="context">
              <ResponseField name="currentSceneId" type="string">
                An identifier for the current scene.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="onDisable" type="(isDisabled: boolean, context: object) => void">
            Disable or enable your custom submit button.

            <Expandable defaultOpen title="context">
              <ResponseField name="currentSceneId" type="string">
                An identifier for the current scene.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="onLoading" type="(isLoading: boolean, context: object) => void">
            Put your submit button in a loading state.

            <Expandable defaultOpen title="context">
              <ResponseField name="currentSceneId" type="string">
                An identifier for the current scene.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="onContentChange" type="(content: string, context: object) => void">
            Set your submit button's content with either the content provided or your
            own custom content.

            <Expandable defaultOpen title="context">
              <ResponseField name="currentSceneId" type="string">
                An identifier for the current scene.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="processingIndicator" type="object">
        <Expandable defaultOpen title="Properties">
          <ResponseField name="visible" type="boolean">
            Choose whether a processing indicator overlay should be shown on form
            submission.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="errorMessage" type="object">
        <Expandable defaultOpen title="Properties">
          <ResponseField name="disabled" type="boolean">
            Choose whether to allow Universal Checkout to show error messages.
          </ResponseField>
        </Expandable>

        <Expandable defaultOpen title="Callbacks">
          <ResponseField name="onErrorMessageShow" type="(message: string) => void">
            A callback for when the error message should be displayed, you can choose to
            use the provided message for your own purposes.
          </ResponseField>

          <ResponseField name="onErrorMessageHide" type="() => void">
            A callback for when the error message should be hidden, update own UI
            accordingly.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="successScreen" type="false | object">
        When the checkout is successfully completed, Drop-In Checkout displays a success scene with a default success message "Your payment was successful!".

        Set the option `successScreen` to modify the default behavior of the success scene.

        Remove the success screen:

        ```ts TS theme={"dark"}
        const options = {
          /* Other options ... */
          successScreen: false,
        };
        ```

        Change the message of the default success screen:

        ```ts TS theme={"dark"}
        const options = {
          /* Other options ... */
          successScreen: {
            type: "CHECK",
            title: "This is a custom success message!",
          },
        };
        ```

        <Expandable defaultOpen title="Properties">
          <ResponseField name="type" type="'CHECK'">
            "CHECK" is the only type of success screen supported at the moment.
          </ResponseField>

          <ResponseField name="title" type="string">
            Your custom success message.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Manual payment handling">
      <ResponseField name="paymentHandling" type="&#x22;AUTO&#x22; | &#x22;MANUAL&#x22;">
        The `paymentHandling` option defines how the SDK should handle payment creation and resume.

        The default is `AUTO`, set `paymentHandling` to `MANUAL` to turn off automatic payment handling. This disables the callbacks `onBeforePayment` and `onCheckoutComplete`.

        Two callbacks must be implemented:

        * `onTokenizeSuccess()` to create payments with the `paymentMethodToken`.
        * `onResumeSuccess()` to resume payments with `resumeToken`.

        See the [Manual Payment Creation](/checkout/advanced/manual-payment-creation) guide for examples.

        <Note>
          The guide's examples are written for `PrimerCheckout`, but the same concepts apply to `PrimerHeadlessCheckout`.
        </Note>
      </ResponseField>

      <ResponseField name="onTokenizeSuccess" type="(data: PaymentMethodTokenData, handler: OnTokenizeSuccessHandler) => void">
        <Note>
          If you set `paymentHandling` to `MANUAL`, implementing this is mandatory.
        </Note>

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="data" type="PaymentMethodTokenData">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="token" type="string" required>
                The payment instrument token you can use to [create a payment request](/api-reference/v2.4/api-reference/payments-api/create-a-payment) from your backend.
              </ResponseField>

              <ResponseField name="analyticsId" type="string">
                An unique identifier for the payment instrument token.
              </ResponseField>

              <ResponseField name="paymentInstrumentData" type="PaymentInstrumentData">
                Additional information about the payment instrument.
                Depending on the payment method type, only some of the following properties are present on the object.

                <Expandable defaultOpen title="Properties">
                  <ResponseField name="paymentMethodConfigId" type="string">
                    The identifier for the payment method configuration.
                  </ResponseField>

                  <ResponseField name="paymentMethodType" type="string">
                    The type of the payment method used for the transaction, one of [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types).
                  </ResponseField>

                  <ResponseField name="sessionInfo" type="SessionInfo">
                    Information about the session associated with the transaction.
                  </ResponseField>

                  <ResponseField name="first6Digits" type="string">
                    The first six digits of the payment card.
                  </ResponseField>

                  <ResponseField name="last4Digits" type="string">
                    The last four digits of the payment card.
                  </ResponseField>

                  <ResponseField name="expirationMonth" type="string">
                    The expiration month of the payment card.
                  </ResponseField>

                  <ResponseField name="expirationYear" type="string">
                    The expiration year of the payment card.
                  </ResponseField>

                  <ResponseField name="cardholderName" type="string">
                    The name of the cardholder as it appears on the payment card.
                  </ResponseField>

                  <ResponseField name="network" type="string">
                    The network associated with the payment card (e.g., Visa, Mastercard).
                  </ResponseField>

                  <ResponseField name="isNetworkTokenized" type="string">
                    Indicates whether the payment card's network is tokenized.
                  </ResponseField>

                  <ResponseField name="binData" type="BinData">
                    Information about the Bank Identification Number (BIN) of the payment card.
                  </ResponseField>

                  <ResponseField name="threeDSecureAuthentication" type="ThreeDSAuthenticationData">
                    Data related to 3D Secure authentication for the transaction.

                    <Expandable defaultOpen title="Properties">
                      <ResponseField name="responseCode" type="ThreeDSecureStatus">
                        Indicates the outcome of the 3D Secure authentication process.\
                        Possible values:

                        * `AUTH_SUCCESS`: The authentication was successful.
                        * `AUTH_FAILED`: The authentication process failed.
                        * `SKIPPED`: The authentication was skipped.
                        * `CHALLENGE`: A challenge was issued during the authentication process.
                      </ResponseField>

                      <ResponseField name="reasonCode" type="string">
                        An optional code indicating the reason for the outcome of the 3D Secure authentication.
                      </ResponseField>

                      <ResponseField name="reasonText" type="string">
                        An optional text description providing further details about the reason for the authentication outcome.
                      </ResponseField>

                      <ResponseField name="protocolVersion" type="string">
                        Specifies the version of the 3D Secure protocol that was used.
                      </ResponseField>

                      <ResponseField name="challengeIssued" type="boolean">
                        Indicates whether a challenge was issued as part of the authentication process.

                        * `true`: A challenge was issued.
                        * `false`: No challenge was issued.
                      </ResponseField>
                    </Expandable>
                  </ResponseField>

                  <ResponseField name="paypalBillingAgreementId" type="string">
                    The identifier for a PayPal billing agreement, if applicable.
                  </ResponseField>

                  <ResponseField name="externalPayerInfo" type="ExternalPayerInfo">
                    External information about the payer associated with the transaction.
                  </ResponseField>

                  <ResponseField name="shippingAddress" type="ShippingAddress">
                    The shipping address for the transaction, if applicable.
                  </ResponseField>

                  <ResponseField name="klarnaCustomerToken" type="string">
                    The customer token associated with Klarna payment, if applicable.
                  </ResponseField>

                  <ResponseField name="sessionData" type="SessionData">
                    Additional data related to the session.
                  </ResponseField>
                </Expandable>
              </ResponseField>

              <ResponseField name="paymentInstrumentType" type="PaymentInstrumentType">
                The type of the payment instrument.

                Example of possible values (new values could be added as we add new payment methods):

                * `APPLE_PAY`
                * `CARD_OFF_SESSION_PAYMENT`
                * `GOOGLE_PAY`
                * `KLARNA_CUSTOMER_TOKEN`
                * `OFF_SESSION_PAYMENT`
                * `PAYMENT_CARD`
                * `PAYPAL_BILLING_AGREEMENT`
                * `PAYPAL_ORDER`
              </ResponseField>

              <ResponseField name="threeDSecureAuthentication" type="ThreeDSAuthenticationData">
                Data related to 3D Secure authentication for the transaction.

                <Expandable defaultOpen title="Properties">
                  <ResponseField name="responseCode" type="ThreeDSecureStatus">
                    Indicates the outcome of the 3D Secure authentication process.\
                    Possible values:

                    * `AUTH_SUCCESS`: The authentication was successful.
                    * `AUTH_FAILED`: The authentication process failed.
                    * `SKIPPED`: The authentication was skipped.
                    * `CHALLENGE`: A challenge was issued during the authentication process.
                  </ResponseField>

                  <ResponseField name="reasonCode" type="string">
                    An optional code indicating the reason for the outcome of the 3D Secure authentication.
                  </ResponseField>

                  <ResponseField name="reasonText" type="string">
                    An optional text description providing further details about the reason for the authentication outcome.
                  </ResponseField>

                  <ResponseField name="protocolVersion" type="string">
                    Specifies the version of the 3D Secure protocol that was used.
                  </ResponseField>

                  <ResponseField name="challengeIssued" type="boolean">
                    Indicates whether a challenge was issued as part of the authentication process.

                    * `true`: A challenge was issued.
                    * `false`: No challenge was issued.
                  </ResponseField>
                </Expandable>
              </ResponseField>

              <ResponseField name="tokenType" type="&#x22;SINGLE_USE&#x22; | &#x22;MULTI_USE&#x22;">
                Whether this payment method token can be used only once or multiple times.
              </ResponseField>

              <ResponseField name="vaultData" type="VaultData">
                <Expandable defaultOpen title="Properties">
                  <ResponseField name="customerId" type="string">
                    The `customerId` associated to the payment method, if vaulted.
                  </ResponseField>
                </Expandable>
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="handler" type="OnTokenizeSuccessHandler">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="handleSuccess" type="() => void">
                Display a success screen.
              </ResponseField>

              <ResponseField name="handleFailure" type="(errorMessage: string) => void">
                Display `errorMessage` as an error or failure message.
              </ResponseField>

              <ResponseField name="continueWithNewClientToken" type="(clientToken: string) => void">
                Continue the payment flow using the given `clientToken`.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>

        Called after a customer submitted their payment data and the payment details have been tokenized.
        You'll receive a `paymentMethodToken` in `onTokenizeSuccess()`.

        * [Create a payment request](/api-reference/v2.4/api-reference/payments-api/create-a-payment) passing the `paymentMethodToken` to your backend

        * If the payment is successful, call `handler.handleSuccess()` in order to display a success screen

        * If the payment is unsuccessful, call `handler.handleFailure(errorMessage)` to display an error or failure message

        * Payments API may return a new `clientToken` for additional steps (in the `requiredActions` on the response). In this case, call `handler.continueWithNewClientToken(clientToken)` to continue with the payment flow
      </ResponseField>

      <ResponseField name="onTokenizeError" type="(error: PrimerClientError) => void">
        Called after a customer submitted their payment data and the payment details could not be tokenized.
        Use the `PrimerClientError` data to display an error message.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="error" type="PrimerError">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="code" type="ErrorCode">
                {" "}
              </ResponseField>

              <ResponseField name="message" type="string">
                {" "}
              </ResponseField>

              <ResponseField name="diagnosticsId" type="Nullable<string>">
                {" "}
              </ResponseField>

              <ResponseField name="data" type="object">
                {" "}
              </ResponseField>

              <ResponseField name="isFromDeveloper" type="boolean">
                {" "}
              </ResponseField>

              <ResponseField name="fromErrorCode" type="(code: ErrorCode, options: ErrorOptions) => PrimerClientError">
                {" "}
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="onResumeSuccess" type="(data: ResumeToken, handler: OnResumeSuccessHandler) => void">
        Called when the resume token must be sent to your server to resume the payment flow, typically after the customer has completed some authorization step outside of the Primer SDK.

        <Note>
          If you set `paymentHandling` to `MANUAL`, handling `onResumeSuccess()` is required to fully support 3DS and the majority of payment methods.
        </Note>

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="data" type="ResumeToken">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="resumeToken" type="string">
                The resume token you can use to [resume the payment flow](/api-reference/v2.4/api-reference/payments-api/resume-a-payment) on your backend.
              </ResponseField>

              <ResponseField name="paymentId" type="string">
                An unique identifier of the payment on Primer.
              </ResponseField>
            </Expandable>
          </ResponseField>

          <ResponseField name="handler" type="OnResumeSuccessHandler">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="handleSuccess" type="() => void">
                Display a success screen.
              </ResponseField>

              <ResponseField name="handleFailure" type="(errorMessage: string) => void">
                Display `errorMessage` as an error or failure message.
              </ResponseField>

              <ResponseField name="continueWithNewClientToken" type="(clientToken: string) => void">
                Continue the payment flow using the given `clientToken`.
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>

        * You will receive a `resumeToken` via the `onResumeSuccess()` callback if applicable

        * Send a [resume payment request](/api-reference/v2.4/api-reference/payments-api/resume-a-payment) with the `resumeToken`

        * If the payment is successful, call `handler.handleSuccess()` in order to display a success screen

        * If the payment is unsuccessful, call `handler.handleFailure(errorMessage)` to display an error or failure message

        * The Payments API may again return a new `clientToken` for additional steps. In this case, call `handler.continueWithNewClientToken(clientToken)` again
      </ResponseField>

      <ResponseField name="onResumeError" type="(error: PrimerClientError) => void">
        Called when the payment cannot be resumed.
        Use the `PrimerClientError` data to display an error message.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="error" type="PrimerError">
            <Expandable defaultOpen title="Properties">
              <ResponseField name="code" type="ErrorCode">
                {" "}
              </ResponseField>

              <ResponseField name="message" type="string">
                {" "}
              </ResponseField>

              <ResponseField name="diagnosticsId" type="Nullable<string>">
                {" "}
              </ResponseField>

              <ResponseField name="data" type="object">
                {" "}
              </ResponseField>

              <ResponseField name="isFromDeveloper" type="boolean">
                {" "}
              </ResponseField>

              <ResponseField name="fromErrorCode" type="(code: ErrorCode, options: ErrorOptions) => PrimerClientError">
                {" "}
              </ResponseField>
            </Expandable>
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="onTokenizeShouldStart" type="(data: { paymentMethodType: PaymentMethodType }) => boolean">
        Called to determine if the payment method tokenization should start.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="data" type="{ paymentMethodType: PaymentMethodType }">
            An object containing a `paymentMethodType` property, one of [PaymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types).
          </ResponseField>
        </Expandable>

        Implement this if you need to abort the payment method tokenization according to your own logic. You should return `true` to continue or `false` to abort.
      </ResponseField>

      <ResponseField name="onTokenizeStart" type="() => void">
        Called just before the payment method tokenization starts. Implement this to perform any custom action, for example, displaying a custom loading indicator.
      </ResponseField>

      <ResponseField name="onTokenizeDidNotStart" type="(reason: &#x22;TOKENIZATION_DISABLED&#x22; | &#x22;TOKENIZATION_SHOULD_NOT_START&#x22;) => void">
        Called if the payment method tokenization did not start. Receives a `reason` as a string.

        <Expandable defaultOpen title="Parameters">
          <ResponseField name="reason" type="&#x22;TOKENIZATION_SHOULD_NOT_START&#x22; | &#x22;TOKENIZATION_DISABLED&#x22;">
            * `TOKENIZATION_SHOULD_NOT_START`: tokenization was interrupted returning `false` from `onTokenizeShouldStart`.

            * `TOKENIZATION_DISABLED`: tokenization was disabled using `setIsTokenizationEnabled` or `setPaymentCreationEnabled`.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>

    <Expandable defaultOpen title="Client session caching">
      <ResponseField name="clientSessionCachingEnabled" type="boolean" 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>
    </Expandable>
  </ResponseField>
</Expandable>

## Returns

<Expandable defaultOpen>
  <ResponseField name="" type="Promise<UniversalCheckout>">
    A promise that is resolved when Drop-In Checkout has been properly rendered on the page, or rejected if any error occurred during initialisation.

    The promise is resolved with an instance of [PrimerCheckout](/sdk/web/v2.x.x/primer-checkout/overview)
  </ResponseField>
</Expandable>