> ## Documentation Index > Fetch the complete documentation index at: https://primer.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # configure This method is deprecated. Set the options on the [`createHeadless` method](https://primer.io/docs/sdk/web/v2.x.x/primer/methods/createHeadless) instead. ```ts TS theme={"dark"} configure(options: HeadlessUniversalCheckoutOptions): void ``` Configure the Headless Checkout instance with the provided options. ## Parameters **Parameters** **options** `object` Options for a Headless Universal Checkout, its properties can be defined to configure the checkout experience. **Properties** **onAvailablePaymentMethodsLoad** `(paymentMethods: PaymentMethodInfo[]) =\> void` *required* Called when the available payment methods have been loaded. Takes an array of objects as its argument. **Parameters** **paymentMethods** `PaymentMethodInfo[]` **Properties** **type** `PaymentMethodType` *required* The type of payment method, one of [PaymentMethodType](https://primer.io/docs/sdk/web/v2.x.x/constants/payment-method-types.md). **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"` 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. **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. **Parameters** **data** `object` **Properties** **paymentMethodType** `string` The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](https://primer.io/docs/sdk/web/v2.x.x/constants/payment-method-types.md) **handler** `object` Provides two methods to continue or abort the payment. > [!WARNING] > > You MUST call one of the methods of the handler if `onBeforePaymentCreate` is implemented. Choose to abort a payment. ```ts TS theme={"dark"} return handler.abortPaymentCreation(); ``` Choose to continue with payment creation ```ts TS theme={"dark"} 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 TS theme={"dark"} 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. **Parameters** **data** `object` **Properties** **payment** `object` **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. **Parameters** **error** `PrimerClientError` **Properties** **code** `ErrorCode` **message** `string` **diagnosticsId** `Nullable\` **data** `object` **isFromDeveloper** `boolean` **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. **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 TS theme={"dark"} 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(); }, }); ``` **Properties** **showErrorMessage** `() =\> void` Tells the SDK that the error has been properly handled by your application. This does not display any error message. **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. Payment will be unselected when a popup is closed. **data** `object` **Properties** **paymentMethodType** `string` The type of the payment method Primer will use for payment creation, one of [PaymentMethodType](https://primer.io/docs/sdk/web/v2.x.x/constants/payment-method-types.md) **payment** `object | undefined` The payment object, available when a payment has already been created before the payment method is unselected. **Properties** **id** `string` The unique identifier of the payment. **Payment methods options** **redirect** `object` Options for payment methods that rely on redirecting. **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. **Properties** **captureBillingAddress** `boolean` Whether to prompt the user to select a billing address. **applePay** `object` Options for using Apple Pay as a payment method. **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. **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. **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](https://primer.io/docs/sdk/web/v2.x.x/constants/card-networks.md). **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](https://primer.io/docs/checkout/advanced/manual-payment-creation.md) guide for examples. > [!NOTE] > > The guide's examples are written for `PrimerCheckout`, but the same concepts apply to `PrimerHeadlessCheckout`. **onTokenizeSuccess** `(data: PaymentMethodTokenData, handler: OnTokenizeSuccessHandler) =\> void` > [!NOTE] > > If you set `paymentHandling` to `MANUAL`, implementing this is mandatory. **Parameters** **data** `PaymentMethodTokenData` **Properties** **token** `string` *required* The payment instrument token you can use to [create a payment request](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md) 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. **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](https://primer.io/docs/sdk/web/v2.x.x/constants/payment-method-types.md). **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. **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. **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` **Properties** **customerId** `string` 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](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md) 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\` **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. > [!NOTE] > > If you set `paymentHandling` to `MANUAL`, handling `onResumeSuccess()` is required to fully support 3DS and the majority of payment methods. **Parameters** **data** `ResumeToken` **Properties** **resumeToken** `string` The resume token you can use to [resume the payment flow](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/resume-a-payment.md) 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](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/resume-a-payment.md) 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\` **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. **Parameters** **data** `\{ paymentMethodType: PaymentMethodType \}` An object containing a `paymentMethodType` property, one of [PaymentMethodType](https://primer.io/docs/sdk/web/v2.x.x/constants/payment-method-types.md). 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`. **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. **Client session caching** **clientSessionCachingEnabled** `boolean` > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.