createHeadless(
clientToken: string,
options?: HeadlessUniversalCheckoutOptions,
): Promise<PrimerHeadlessCheckout>
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.start
method must be called to begin the checkout process.Hide Parameters
Hide Properties
Hide Parameters
Hide Properties
'2.4'
.'legacy'
if you encounter compatibility issues with the latest API version and wish to revert to the previous stable behavior.Hide Payment lifecycle callbacks
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
Hide Properties
onBeforePaymentCreate
is implemented.return handler.abortPaymentCreation();
return handler.continuePaymentCreation();
Hide Parameters
Hide Properties
Hide Parameters
Hide Properties
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";
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
Hide Event callbacks
Hide Parameters
Hide Properties
Hide Payment methods options
Hide Properties
Hide Properties
Hide Properties
Hide Properties
Hide Manual payment handling
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
.PrimerCheckout
, but the same concepts apply to PrimerHeadlessCheckout
.paymentHandling
to MANUAL
, implementing this is mandatory.Hide Parameters
Hide Properties
Hide Properties
Hide Properties
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.true
: A challenge was issued.false
: No challenge was issued.APPLE_PAY
CARD_OFF_SESSION_PAYMENT
GOOGLE_PAY
KLARNA_CUSTOMER_TOKEN
OFF_SESSION_PAYMENT
PAYMENT_CARD
PAYPAL_BILLING_AGREEMENT
PAYPAL_ORDER
Hide Properties
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.true
: A challenge was issued.false
: No challenge was issued.paymentMethodToken
in onTokenizeSuccess()
.paymentMethodToken
to your backend
handler.handleSuccess()
in order to display a success screen
handler.handleFailure(errorMessage)
to display an error or failure message
clientToken
for additional steps (in the requiredActions
on the response). In this case, call handler.continueWithNewClientToken(clientToken)
to continue with the payment flow
PrimerClientError
data to display an error message.paymentHandling
to MANUAL
, handling onResumeSuccess()
is required to fully support 3DS and the majority of payment methods.Hide Parameters
Hide Properties
resumeToken
via the onResumeSuccess()
callback if applicable
resumeToken
handler.handleSuccess()
in order to display a success screen
handler.handleFailure(errorMessage)
to display an error or failure message
clientToken
for additional steps. In this case, call handler.continueWithNewClientToken(clientToken)
again
PrimerClientError
data to display an error message.Hide Parameters
paymentMethodType
property, one of PaymentMethodType.true
to continue or false
to abort.reason
as a string.Hide Parameters
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
Hide Client session caching
true
it’s recommended to reach out to Primer support for additional verification since there are edge cases where it’s not advised.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.Hide Returns
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();
}