createHeadless

TS

createHeadless(
	clientToken: string,
	options?: HeadlessUniversalCheckoutOptions,
): Promise<PrimerHeadlessCheckout>

Create an instance of PrimerHeadlessCheckout, which is used to interact with the Primer API in a headless environment.

Starting from the version 2.45.0, the options parameter should be used instead of the deprecated configure method. If both are used simultaneously, the SDK will throw an error.

Note: the configure method must be called before the start method.

• The start method must be called to begin the checkout process.

​

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

Options for a Headless Universal Checkout, its properties can be defined to configure the checkout experience.

Hide Properties

onAvailablePaymentMethodsLoad · (paymentMethods: PaymentMethodInfo[]) => void · required

Called when the available payment methods have been loaded. Takes an array of objects as its argument.

Hide Parameters

paymentMethods · PaymentMethodInfo[]

Hide Properties

type · PaymentMethodType · required

The type of payment method, one of PaymentMethodType.

managerType · "CARD" | "NATIVE" | "REDIRECT" · required

The type of payment manager to use.

locale · string

This option sets the locale for UI elements and redirect payment method URLs. By default, if locale is not set, all UI elements will be in English. However, redirect URLs for certain redirect payment methods will be determined based on the user’s locale. If you set this locale option, all UI elements as well as the URLs of redirect payment methods will use the locale specified in this option.

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.

TS

return handler.abortPaymentCreation();

Choose to continue with payment creation

TS

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.

TS

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

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

Hide Parameters

error · PrimerClientError

Hide Properties

code · ErrorCode

message · string

diagnosticsId · Nullable<string>

data · object

isFromDeveloper · boolean

fromErrorCode · (code: ErrorCode, options: ErrorOptions) => PrimerClientError

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

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

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.

TS

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

Primer.createHeadless(clientToken, {
  onCheckoutComplete(...args) {
    console.log("onCheckoutComplete", ...args);
  },
  onCheckoutFail(error, data, handler) {
    if (!handler) {
      return;
    }

    // Tells the SDK that it can proceed
    // Note: this does not show any error message
    return handler.showErrorMessage();
  },
});

Hide Properties

showErrorMessage · () => void

Tells the SDK that the error has been properly handled by your application. This does not display any error message.

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

id · string

The unique identifier of the payment.

Hide Payment methods options

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.

googlePay · object

Options for using Google Pay as a payment method.

Hide Properties

captureBillingAddress · boolean

Whether to prompt the user to select a billing address.

applePay · object

Options for using Apple Pay as a payment method.

Hide Properties

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.

allowedCardNetworks · CardNetwork[] · deprecated

Allowed card networks for credit card payments, one of CardNetwork.

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.

firstDigits · string

The first six or eight digits of the payment card within PCI guidelines.

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.

Hide Parameters

error · PrimerError

Hide Properties

code · ErrorCode

message · string

diagnosticsId · Nullable<string>

data · object

isFromDeveloper · boolean

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.

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.

Hide Parameters

error · PrimerError

Hide Properties

code · ErrorCode

message · string

diagnosticsId · Nullable<string>

data · object

isFromDeveloper · boolean

fromErrorCode · (code: ErrorCode, options: ErrorOptions) => PrimerClientError

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

Promise<PrimerHeadlessCheckout> · Promise<PrimerHeadlessCheckout>

A promise that resolves with an instance of PrimerHeadlessCheckout, which can be used to create and manage payments with your own UI components.

​

Example

See guide on initializing Headless Checkout for more details.

TS

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

const clientToken = "YOUR_CLIENT_TOKEN";
const paymentMethodType = "PAYMENT_CARD";

async function createHeadlessCheckout() {
  const primerHeadlessCheckout = await Primer.createHeadless(
    clientToken,
    options
  );
  // Use the instance to create a payment method manager
  const paymentMethodManager =
    await primerHeadlessCheckout.createPaymentMethodManager(paymentMethodType);
  // Start the checkout process
  primerHeadlessCheckout.start();
}