configure

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

This option forces the locale for certain UI elements. By default, the locale will be set to the browser’s locale.

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.

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

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.

return handler.abortPaymentCreation();

return handler.continuePaymentCreation();

Called when a payment has been created. Move on to next step in your checkout flow, such as showing a success message, etc.

Called when the checkout flow has failed.

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

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

Options for using Google Pay as a payment method.

Options for using Apple Pay as a payment method.

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

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.

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

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.

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.

• 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

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

Called to determine if the payment method tokenization should start.

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.

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

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

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

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.

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.