showUniversalCheckout

The container element in which the checkout should be rendered.

This option forces the locale. By default, the locale will be set to the browser’s locale.

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.

Notifies you before the checkout tokenizes a payment method and creates a payment.

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.

return handler.abortPaymentCreation();

return handler.continuePaymentCreation();

Called when a payment has been created. Move on to next step in your checkout flow, such as showing a success message, etc.

Called when the checkout flow has failed. This callback can also be used to display an error state within your own UI.

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');
  },
});

Called when the client session is in the process of being updated. Use it to show a loading indicator on your UI.

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.

Notifies you when a specific payment method has been selected or unselected.

Customize the appearance and behavior of the card fields in the checkout form.

Options for payment methods that rely on redirecting.

Options for using PayPal as a payment method.

Options for using Google Pay as a payment method.

Options for using Apple Pay as a payment method.

Options for using Klarna via Adyen as a payment method.

Options for using Klarna as a payment method.

Options for using direct debit as a payment method.

An interface for configuring the display of vaulted payment methods.

See the CheckoutStyle page.

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

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
    },
  },
};

When the checkout is succefully complete, 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:

const options = {
  /* Other options ... */
  successScreen: false,
};

Change the message of the default success screen:

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

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 guide for examples.

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

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.

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.

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

• Send a resume payment request 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

Called when the payment cannot be resumed. Use the PrimerClientError data to display an error message.

Called to determine if the payment method tokenization should start.

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.

Called just before the payment method tokenization starts. Implement this to perform any custom action, for example, displaying a custom loading indicator.

Called if the payment method tokenization did not start. Receives a reason as a string.

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.