Web SDK methods: showUniversalCheckout

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.

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

Hide child attributes

clientToken

string

required

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

universalCheckoutOptions

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.

Hide child attributes

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.

merchantDomain

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

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.

Hide Payment lifecycle callbacks

onPaymentCreationStart

() => void

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

onBeforePaymentCreate

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

Hide Parameters

data

object

Hide Properties

paymentMethodType

string

The type of the payment method Primer will use for payment creation, one of PaymentMethodType

handler

object

Provides two methods to continue or abort the payment.

You MUST call one of the methods of the handler if onBeforePaymentCreate is implemented.

Choose to abort a payment.

return handler.abortPaymentCreation();

Choose to continue with payment creation

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.

return handler.continuePaymentCreation({ idempotencyKey: 'my-unique-key' });

onCheckoutComplete

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

Hide Parameters

data

object

Hide Properties

payment

object

Hide Properties

string

Primer’s unique identifier for the payment.

orderId

string

Your order identifier as provided in the client session.

paymentMethodData

object

Optional payment method data - for some payment methods this object will contain additional information on the payment.

onCheckoutFail

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

Hide Parameters

data

object

Hide Properties

payment

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.

Hide Properties

string

Primer’s unique identifier for the payment.

orderId

string

Your order identifier as provided in the client session.

paymentMethodData

object

Optional payment method data - for some payment methods this object will contain additional information on the payment.

handler

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.

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

Hide Properties

showErrorMessage

(customErrorMessage?: string) => void

Hide Parameters

customErrorMessage?: string

string

An optional custom error message.

Hide Client session lifecycle callbacks

onBeforeClientSessionUpdate

() => void

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

onClientSessionUpdate

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

Hide Event callbacks

onPaymentMethodAction

(action: string, data: object) => void

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

Hide Parameters

action

'PAYMENT_METHOD_SELECTED' | 'PAYMENT_METHOD_UNSELECTED'

The action being performed on the payment method. Payment will be unselected when a popup is closed.

data

object

Hide Properties

paymentMethodType

string

The type of the payment method Primer will use for payment creation, one of PaymentMethodType

payment

object | undefined

The payment object, available when a payment has already been created before the payment method is unselected.

Show Properties

string

The unique identifier of the payment.

Hide Payment methods options

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.

preferredFlow

"DEDICATED_SCENE" | "EMBEDDED_IN_HOME"

Specify the preferred flow for entering card details.

redirect

object

Options for payment methods that rely on redirecting.

Hide Properties

returnUrl

string

The URL to return to after the redirect process has completed.

forceRedirect

boolean

Whether to always use a redirect flow, rather than a popup window, even if other options are available. Default value is false.

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.

paymentFlow

"DEFAULT" | "PREFER_VAULT"

The payment flow to use for the PayPal button.

onClick

() => void

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

googlePay

object

Options for using Google Pay as a payment method.

Hide Properties

buttonType

buttonColor

"default" | "black" | "white"

The color of the Google Pay button.

buttonSizeMode

"fill" | "static"

The size mode of the Google Pay button.

onClick

() => void

A function to be called when the Google Pay button is clicked.

captureBillingAddress

boolean

Whether to prompt the user to select a billing address.

existingPaymentMethodRequired

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 is also true before rendering the Google Pay button. Default value is false.

applePay

object

Options for using Apple Pay as a payment method.

Hide Properties

buttonType

The type of the Apple Pay button to display.

buttonStyle

"white" | "white-outline" | "black"

The style of the Apple Pay button.

captureBillingAddress

boolean

deprecated

Whether to display a prompt for the user to enter their billing address during the payment process.

billingOptions

object

Billing contact configuration options for Apple Pay.

Hide Properties

requiredBillingContactFields

("postalAddress" | "phoneNumber" | "emailAddress")[]

required

An array of string values that specify which required contact information fields should be collected during the checkout process.

shippingOptions

object

Shipping contact configuration options for Apple Pay.

Hide Properties

requiredShippingContactFields

("postalAddress" | "name" | "phoneNumber" | "emailAddress")[]

required

An array of string values that specify which required contact information fields should be collected during the checkout process.

adyenKlarna

object

Options for using Klarna via Adyen as a payment method.

Hide Properties

buttonOptions

object

Options for Klarna button.

Hide Properties

text

string

Text to be displayed next to the Klarna logo. If provided, it will replace the default Pay with text.

klarna

object

Options for using Klarna as a payment method.

Hide Properties

paymentFlow

"DEFAULT" | "PREFER_VAULT"

The payment flow of the Klarna payment method.

recurringPaymentDescription

string

The description of the recurring payment.

allowedPaymentCategories

("pay_now" | "pay_later" | "pay_over_time")[]

An array of string values that specify the allowed payment categories.

buttonOptions

object

Options for Klarna button.

Hide Properties

text

string

Text to be displayed next to the Klarna logo. If provided, it will replace the default Pay with text.

directDebit

object

Options for using direct debit as a payment method.

Hide Properties

customerCountryCode

string

required

The customer’s two-letter country code.

companyName

string

required

The name of the company or organization accepting payments.

companyAddress

string

required

The address of the company or organization accepting payments.

customerName

string

The name of the customer making the payment.

customerEmail

string

The email address of the customer making the payment.

customerAddressLine1

string

The first line of the customer’s address.

customerAddressLine2

string

The second line of the customer’s address.

customerCity

string

The city of the customer’s address.

customerPostalCode

string

The postal code of the customer’s address.

iban

string

The International Bank Account Number (IBAN) of the customer’s bank account.

submitButtonLabels

object

An object containing the text to display on the submit button for the Direct Debit form and mandate.

Hide Properties

form

string | (options: { locale: string }) => string

The label to display on the submit button for the Direct Debit form.

mandate

string | (options: { locale: string }) => string

required

The label to display on the submit button for the Direct Debit mandate.

giftCard

object

Options for using gift cards as a payment method.

Hide Properties

logoSrc

string

required

The source URL of the button logo.

background

string

required

The background color of the button.

logoAlt

string

An alternative text for the button logo.

text

string

The text to display on the button.

Hide Vault options

vault

object

An interface for configuring the display of vaulted payment methods.

Hide Properties

visible

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.

deletionDisabled

boolean

Whether deleting a vaulted payment method is disabled or enabled.

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.

successScreen

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:

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

Hide Properties

type

'CHECK'

“CHECK” is the only type of success screen supported at the moment.

title

string

Your custom success message.

Hide Manual payment handling

paymentHandling

"AUTO" | "MANUAL"

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.

The guide’s examples are written for PrimerCheckout, but the same concepts apply to PrimerHeadlessCheckout.

onTokenizeSuccess

(data: PaymentMethodTokenData, handler: OnTokenizeSuccessHandler) => void

If you set paymentHandling to MANUAL, implementing this is mandatory.

Hide Parameters

data

PaymentMethodTokenData

Hide Properties

token

string

required

The payment instrument token you can use to create a payment request from your backend.

analyticsId

string

An unique identifier for the payment instrument token.

paymentInstrumentData

PaymentInstrumentData

Additional information about the payment instrument. Depending on the payment method type, only some of the following properties are present on the object.

Hide Properties

paymentMethodConfigId

string

The identifier for the payment method configuration.

paymentMethodType

string

The type of the payment method used for the transaction, one of PaymentMethodType.

sessionInfo

SessionInfo

Information about the session associated with the transaction.

first6Digits

string

The first six digits of the payment card.

last4Digits

string

The last four digits of the payment card.

expirationMonth

string

The expiration month of the payment card.

expirationYear

string

The expiration year of the payment card.

cardholderName

string

The name of the cardholder as it appears on the payment card.

network

string

The network associated with the payment card (e.g., Visa, Mastercard).

isNetworkTokenized

string

Indicates whether the payment card’s network is tokenized.

binData

BinData

Information about the Bank Identification Number (BIN) of the payment card.

threeDSecureAuthentication

ThreeDSAuthenticationData

Data related to 3D Secure authentication for the transaction.

Hide Properties

responseCode

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.

reasonCode

string

An optional code indicating the reason for the outcome of the 3D Secure authentication.

reasonText

string

An optional text description providing further details about the reason for the authentication outcome.

protocolVersion

string

Specifies the version of the 3D Secure protocol that was used.

challengeIssued

boolean

Indicates whether a challenge was issued as part of the authentication process.

true: A challenge was issued.
false: No challenge was issued.

paypalBillingAgreementId

string

The identifier for a PayPal billing agreement, if applicable.

externalPayerInfo

ExternalPayerInfo

External information about the payer associated with the transaction.

shippingAddress

ShippingAddress

The shipping address for the transaction, if applicable.

klarnaCustomerToken

string

The customer token associated with Klarna payment, if applicable.

sessionData

SessionData

Additional data related to the session.

paymentInstrumentType

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

threeDSecureAuthentication

ThreeDSAuthenticationData

Data related to 3D Secure authentication for the transaction.

Hide Properties

responseCode

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.

reasonCode

string

An optional code indicating the reason for the outcome of the 3D Secure authentication.

reasonText

string

An optional text description providing further details about the reason for the authentication outcome.

protocolVersion

string

Specifies the version of the 3D Secure protocol that was used.

challengeIssued

boolean

Indicates whether a challenge was issued as part of the authentication process.

true: A challenge was issued.
false: No challenge was issued.

tokenType

"SINGLE_USE" | "MULTI_USE"

Whether this payment method token can be used only once or multiple times.

vaultData

VaultData

Hide Properties

customerId

string

The customerId associated to the payment method, if vaulted.

handler

OnTokenizeSuccessHandler

Hide Properties

handleSuccess

() => void

Display a success screen.

handleFailure

(errorMessage: string) => void

Display errorMessage as an error or failure message.

continueWithNewClientToken

(clientToken: string) => void

Continue the payment flow using the given clientToken.

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

onTokenizeError

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

onResumeSuccess

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

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

Hide Parameters

data

ResumeToken

Hide Properties

resumeToken

string

The resume token you can use to resume the payment flow on your backend.

paymentId

string

An unique identifier of the payment on Primer.

handler

OnResumeSuccessHandler

Hide Properties

handleSuccess

() => void

Display a success screen.

handleFailure

(errorMessage: string) => void

Display errorMessage as an error or failure message.

continueWithNewClientToken

(clientToken: string) => void

Continue the payment flow using the given clientToken.

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

onResumeError

(error: PrimerClientError) => void

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

onTokenizeShouldStart

(data: { paymentMethodType: PaymentMethodType }) => boolean

Called to determine if the payment method tokenization should start.

Hide Parameters

data

{ paymentMethodType: PaymentMethodType }

An object containing a paymentMethodType property, one of PaymentMethodType.

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.

onTokenizeStart

() => void

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

onTokenizeDidNotStart

(reason: "TOKENIZATION_DISABLED" | "TOKENIZATION_SHOULD_NOT_START") => void

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

Hide Parameters

reason

"TOKENIZATION_SHOULD_NOT_START" | "TOKENIZATION_DISABLED"

TOKENIZATION_SHOULD_NOT_START: tokenization was interrupted returning false from onTokenizeShouldStart.
TOKENIZATION_DISABLED: tokenization was disabled using setIsTokenizationEnabled or setPaymentCreationEnabled.

Hide Client session caching

clientSessionCachingEnabled

boolean

Default: false

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.

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.

Returns

Hide child attributes

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

Documentation Index

​Parameters

​Returns

Parameters

Returns