showVaultManager

TS

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

Whether the cardholder name input field should be visible.

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 · "checkout" | "credit" | "pay" | "buynow" | "paypal" | "installment"

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.

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

TS

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

TS

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...
  });
}