1234
showUniversalCheckout(    clientToken: string,    options: UniversalCheckoutOptions): Promise<PrimerCheckout>
ts
copy

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.

12345678
import { Primer } from '@primer-io/checkout-web'
const checkout = await Primer.showUniversalCheckout(clientToken, {    container: '#container',    onCheckoutComplete(...args) {        console.log('onCheckoutComplete', ...args)    },})
ts
copy

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

Parameters

clientToken
stringRequired

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

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.

container
string | ElementRequired
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.
Payment lifecycle callbacks
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.

Parameters
checkoutPaymentMethodData
PrimerCheckoutPaymentMethodData
Parameters

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

The name of the payment method Primer will use for payment creation.
handler
PrimerPaymentCreationHandler

Provides two methods to continue or abort the payment.
You MUST call one of the methods of the handler if onBeforePaymentCreate is implemented.

Parameters
abortPaymentCreation
(errorMessage: string | null) => void
Choose to abort a payment.
Choose to continue with payment creation
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, giving access to the service, fulfilling the order, etc.

Parameters
checkoutData
PrimerCheckoutData
Properties
payment
IPrimerCheckoutDataPayment
Properties
id
string
Primer's unique identifier for the payment.
orderId
string
Your order identifier as provided in the client session.
paymentFailureReason
PrimerPaymentErrorCode

Can be either payment-failed which is an error from the PSP side, or cancelled-by-customer which means the failure initiated on the customer side. I.e. cancelling a 3DS flow.

Custom information, that depends on the payment method.
Variations
Properties
expiresAt
StringRequired
couponCode
StringRequired
retailerName
StringRequired
Properties
expiresAt
StringRequired
qrCodeUrl
String?
qrCodeBase64
StringRequired
Properties
expiresAt
StringRequired
entity
StringRequired
reference
StringRequired
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.

Parameters
error
PrimerClientError
Properties
code
ErrorCode
message
string
diagnosticsId
Nullable<string>
data
object
fromErrorCode
(code: ErrorCode, options: ErrorOptions) => PrimerClientError
data
object
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.
Properties
id
string
Primer's unique identifier for the payment.
orderId
string
Your order identifier as provided in the client session.
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.

12345678910111213141516171819
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');    },})
ts
copy
Properties
showErrorMessage
(customErrorMessage?: string) => void
Parameters
An optional custom error message.
Client session lifecycle callbacks
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.
Event callbacks
onPaymentMethodAction
(action: string, data: object) => void

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

Parameters
action
"PAYMENT_METHOD_SELECTED" | "PAYMENT_METHOD_UNSELECTED"
The action being performed on the payment method.
data
object
Properties
The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](/sdk/web/2.x.x/constants/paymentMethodTypes)
Payment methods options
card
object
Customize the appearance and behavior of the card fields in the checkout form.
Properties
Options for the cardholder name input field.
Properties
required
boolean
Whether the cardholder name is required. Only works if the cardholder name is visible.
visible
booleanDeprecated
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.
Customize the placeholder of the card number field.
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.
Customize the placeholder of the expiry date field.
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.
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.
Properties
returnUrl
string
The URL to return to after the redirect process has completed.
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.
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.
The height of the PayPal button, in pixels.
buttonLabel
"checkout" | "credit" | "pay" | "buynow" | "paypal" | "installment"
The label displayed on the PayPal button.
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.
Properties
buttonType
"long" | "short" | "book" | "buy" | "checkout" | "donate" | "order" | "pay" | "plain" | "subscribe"
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.
Whether to prompt the user to select a billing address.
applePay
object
Options for using Apple Pay as a payment method.
Properties
buttonType
"plain" | "buy" | "set-up" | "donate" | "check-out" | "book" | "subscribe"
The type of the Apple Pay button to display.
buttonStyle
"white" | "white-outline" | "black"
The style of the Apple Pay button.
Whether to display a prompt for the user to enter their billing address during the payment process.
klarna
object
Options for using Klarna as a payment method.
Properties
paymentFlow
"DEFAULT" | "PREFER_VAULT"
The payment flow of the Klarna payment method.
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.
Options for using direct debit as a payment method.
Properties
customerCountryCode
stringRequired
The customer's two-letter country code.
companyName
stringRequired
The name of the company or organization accepting payments.
companyAddress
stringRequired
The address of the company or organization accepting payments.
The name of the customer making the payment.
The email address of the customer making the payment.
The first line of the customer's address.
The second line of the customer's address.
The city of the customer's address.
The postal code of the customer's address.
iban
string
The International Bank Account Number (IBAN) of the customer's bank account.
An object containing the text to display on the submit button for the Direct Debit form and mandate.
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 }) => stringRequired
The label to display on the submit button for the Direct Debit mandate.
giftCard
object
Options for using gift cards as a payment method.
Properties
logoSrc
stringRequired
The source URL of the button logo.
background
stringRequired
The background color of the button.
logoAlt
string
An alternative text for the button logo.
text
string
The text to display on the button.
Vault options
vault
object
An interface for configuring the display of vaulted payment methods.
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.

Whether deleting a vaulted payment method is disabled or enabled.
Customization options
style
CheckoutStyle

See the CheckoutStyle page.

form
object
Properties
Choose whether to show the label above inputs.

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.

123456789101112131415161718192021222324252627
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        },    },}
ts
copy
Properties
Set whether to use built-in submit button or to display your own custom button.
Set whether the total order amount should be displayed in the submit button content.
Callbacks
onVisible
(isVisible: boolean, context: object) => void
Show or hide your custom submit button.
context
An identifier for the current scene.
onDisable
(isDisabled: boolean, context: object) => void
Disable or enable your custom submit button.
context
An identifier for the current scene.
onLoading
(isLoading: boolean, context: object) => void
Put your submit button in a loading state.
context
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.
context
An identifier for the current scene.
Properties
visible
boolean
Choose whether a processing indicator overlay should be shown on form submission.
Properties
disabled
boolean
Choose whether to allow Universal Checkout to show error messages.
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.
A callback for when the error message should be hidden, update own UI accordingly.
successScreen
false | object

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:

1234
const options = {    /* Other options ... */    successScreen: false,}
ts
copy

Change the message of the default success screen:

1234567
const options = {    /* Other options ... */    successScreen: {        type: 'CHECK',        title: 'This is a custom success message!',    },}
ts
copy
Properties
type
"CHECK"
"CHECK" is the only type of success screen supported at the moment.
title
string
Your custom success message.
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.

Parameters
data
PaymentMethodTokenData
Properties
token
stringRequired

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

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.

Properties
The identifier for the payment method configuration.

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

sessionInfo
SessionInfo
Information about the session associated with the transaction.
The first six digits of the payment card.
The last four digits of the payment card.
The expiration month of the payment card.
The expiration year of the payment card.
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).
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.

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.
An optional code indicating the reason for the outcome of the 3D Secure authentication.
An optional text description providing further details about the reason for the authentication outcome.
Specifies the version of the 3D Secure protocol that was used.

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

  • true: A challenge was issued.
  • false: No challenge was issued.
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.
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.

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.
An optional code indicating the reason for the outcome of the 3D Secure authentication.
An optional text description providing further details about the reason for the authentication outcome.
Specifies the version of the 3D Secure protocol that was used.

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
Properties

The customerId associated to the payment method, if vaulted.

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

Parameters
error
PrimerError
Properties
code
ErrorCode
message
string
diagnosticsId
Nullable<string>
data
object
fromErrorCode
(code: ErrorCode, options: ErrorOptions) => PrimerClientError
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.

Parameters
data
ResumeToken
Properties

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

Parameters
error
PrimerError
Properties
code
ErrorCode
message
string
diagnosticsId
Nullable<string>
data
object
fromErrorCode
(code: ErrorCode, options: ErrorOptions) => PrimerClientError
onTokenizeShouldStart
(data: { paymentMethodType: PaymentMethodType }) => boolean

Called to determine if the payment method tokenization should start.

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.

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.

Returns

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