showVaultManager

showVaultManager(
  clientToken: string,
  options: VaultManagerOptions
): Promise<PrimerVaultManager>

Show the vault at the specified container, and get an instance of PrimerVaultManager, which is used to manage the customer’s payment methods stored in the Primer Vault.

Parameters

Hide Parameters

clientToken

string

A string containing a client token as returned by the Primer API when you create a client session.

options

object

An interface for configuring the behavior and appearance of the Vault Manager UI.

Hide Properties

container

string | Element

required

The container element in which the checkout should be rendered.

locale

string

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

apiVersion

"legacy" | "2.4"

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.

vaultOnly

boolean

Whether the Vault Manager should only show saved payment methods.

deletionDisabled

boolean

Whether deleting a vaulted payment method is disabled or enabled.

Hide Payment method option

card

object

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

Hide Properties

cardholderName

object

Options for the cardholder name input field.

Hide Properties

required

boolean

Whether the cardholder name is required. Only works if the cardholder name is visible.

visible

boolean

deprecated

Whether the cardholder name input field should be visible. This property is deprecated, set it on your Dashboard instead.

placeholder

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.

cardNumber

object

Customize the placeholder of the card number field.

Hide Properties

placeholder

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.

expiryDate

object

Customize the placeholder of the expiry date field.

Hide Properties

placeholder

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.

cvv

object

Customize the placeholder of the CVV field.

Hide Properties

placeholder

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.

paypal

object

Options for using PayPal as a payment method.

Hide Properties

buttonColor

"gold" | "blue" | "silver" | "white" | "black"

The color of the PayPal button.

buttonShape

"pill" | "rect"

The shape of the PayPal button.

buttonSize

"small" | "medium" | "large" | "responsive"

The size of the PayPal button.

buttonHeight

number

The height of the PayPal button, in pixels.

buttonLabel

The label displayed on the PayPal button.

buttonTagline

boolean

Whether to display the PayPal tagline beneath the button.

onClick

() => void

A function to be called when the PayPal button is clicked.

threeDSecure

object

Options for customizing the 3D Secure verification flow.

Hide Properties

order

object

required

The order details used for 3D Secure verification.

Hide Properties

amount

object

required

The amount of the transaction.

Hide Properties

value

number | string

required

The value of the transaction.

currency

string

required

The currency of the transaction.

string

required

The email address associated with the transaction.

billingAddress

object

The billing address for the transaction.

Hide Properties

firstName

string

The first name of the customer associated with the transaction.

lastName

string

The last name of the customer associated with the transaction.

addressLine1

string

The first line of the billing address for the transaction.

addressLine2

string

The second line of the billing address for the transaction.

addressLine3

string

The third line of the billing address for the transaction.

city

string

The city of the billing address for the transaction.

state

string

The state or province of the billing address for the transaction.

countryCode

string

The ISO 3166-1 alpha-2 code of the country of the billing address for the transaction.

postalCode

string

The postal code of the billing address for the transaction.

orderId

string

required

The unique identifier for the transaction.

testScenario

string

A string specifying a test scenario for use in testing 3D Secure.

Hide Callbacks

onChallengeStart

() => void

Called when the 3D Secure challenge is started.

onChallengeEnd

() => void

Called when the 3D Secure challenge is completed.

Hide Customization options

style

CheckoutStyle

See the CheckoutStyle page.

form

object

Hide Properties

inputLabelsVisible

boolean

Choose whether to show the label above inputs.

submitButton

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

Hide Properties

useBuiltInButton

boolean

Set whether to use built-in submit button or to display your own custom button.

amountVisible

boolean

Set whether the total order amount should be displayed in the submit button content.

Hide Callbacks

onVisible

(isVisible: boolean, context: object) => void

Show or hide your custom submit button.

Hide context

currentSceneId

string

An identifier for the current scene.

onDisable

(isDisabled: boolean, context: object) => void

Disable or enable your custom submit button.

Hide context

currentSceneId

string

An identifier for the current scene.

onLoading

(isLoading: boolean, context: object) => void

Put your submit button in a loading state.

Hide context

currentSceneId

string

An identifier for the current scene.

onContentChange

(content: string, context: object) => void

Set your submit button’s content with either the content provided or your own custom content.

Hide context

currentSceneId

string

An identifier for the current scene.

processingIndicator

object

Hide Properties

visible

boolean

Choose whether a processing indicator overlay should be shown on form submission.

errorMessage

object

Hide Properties

disabled

boolean

Choose whether to allow Universal Checkout to show error messages.

Hide Callbacks

onErrorMessageShow

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

onErrorMessageHide

() => void

A callback for when the error message should be hidden, update own UI accordingly.

Hide Lifecycle Callbacks

onTokenizeShouldStart

(data: Data) => boolean | Promise<boolean>

Called when the tokenization process is about to start. Return a boolean indicating whether or not to proceed with the process.

Hide Data

paymentMethodType

PaymentMethodType

Indicates which PaymentMethodType will be tokenized.

onTokenizeDidNotStart

(reason: string) => void

Called when the tokenization process is about to start, but is canceled for some reason.

onTokenizeStart

() => void

Called when the tokenization process starts.

onTokenizeSuccess

(data: PaymentMethodToken) => void

Called when the tokenization process is successful.

onTokenizeError

(message: PrimerClientError) => void

Called when the tokenization process fails.

Hide PrimerClientError

code

ErrorCode

One of ErrorCode.

message

string

A human-readable error message.

diagnosticsId

string | null

A unique identifier for the error instance, used for troubleshooting purposes.

data

unknown

Optional additional data associated with the error.

isFromDeveloper

boolean

Whether the error was generated by the developer.

Returns

Hide Promise<PrimerVaultManager>

An interface for managing the customer’s payment methods stored in the Primer Vault.

Hide PrimerVaultManager

teardown

() => void

Remove the Vault Manager UI from the DOM and unbind all event listeners.

submit

() => void

Submit the payment method selected by the customer in the Vault Manager UI.

Example

import { Primer } from "@primer-io/checkout-web";

const clientToken = "YOUR_CLIENT_TOKEN";

async function showVaultManager() {
  const primerVaultManager = await Primer.showVaultManager(clientToken, {
    container: "#my-element",
    // other options...
  });
}

Web SDK

​Parameters

​Returns

​Example

Parameters

Returns

Example