Primer's Official Universal Checkout Web SDK
💳 Create great payment experiences with our highly customizable Universal Checkout
🧩 Connect and configure any new payment method without a single line of code
✅ Dynamically handle 3DS 2.0 across processors and be SCA ready
♻️ Store payment methods for one-click checkout, recurring and repeat payments
📱 Proprietary Apple & Google Pay integrations that work with any PSP
🔒 Always PCI compliant without redirecting customers
Don’t hesitate to reach out with any questions or feedback.
Navigate to our JIRA Service Desk to submit your inquiry. If you don’t have access, please contact your account administrator for assistance.
Not yet integrated with Primer and interested in learning more? Contact us.
🔑 Generate a client token by creating a client session in your backend
🧱 Prepare a container in which to render Universal Checkout
🎉 That's it!
This project uses Vitest for unit testing and specifically excludes component tests with jsdom. Only TypeScript/JavaScript-based unit tests are supported in the main test environment.
If component testing is needed, please use the Playwright e2e tests in the /playwright directory.
Our Web SDK is available on npm under the name @primer-io/checkout-web.
That package includes TypeScript definitions.
# With npm
npm install @primer-io/checkout-web
# With pnpm
pnpm add @primer-io/checkout-web
# With yarn
yarn add @primer-io/checkout-webThen import Primer in your application
import { Primer } from '@primer-io/checkout-web';
Primer.showUniversalCheckout(clientToken, {
// options...
});Include the Primer.min.js script on the page where you want the checkout to be rendered.
Ensure that you're providing the desired version in the script tag. In the case below, it's v2.0.0:
<link rel="stylesheet" href="https://sdk.primer.io/web/v2.0.0/Checkout.css" />
<script
src="https://sdk.primer.io/web/v2.0.0/Primer.min.js"
crossorigin="anonymous"
></script>Primer.min.js will add the Primer object to the global scope.
const { Primer } = window;
Primer.showUniversalCheckout(clientToken, {
// options...
});The simplest way to integrate with Primer is with our Drop-In Checkout. With just a few lines of code, you can display a fully in-context checkout UI with all your payment methods.
Where there is a need for more customization and control over the checkout experience, a headless version of Primer’s Universal Checkout is available. You can use Headless Universal Checkout with your own UI, giving you more flexibility and allowing you to move faster when making design changes, while still having Primer capture sensitive PCI card data or other form data.
Take a look at our Quick Start Guide for accepting your first payment with Drop-in Checkout.
Availing Drop-in Checkout is as easy as implementing one line of code:
import { Primer } from '@primer-io/checkout-web';
const checkout = await Primer.showUniversalCheckout(clientToken, options);Below is an example of a basic implementation of Universal Checkout:
const clientToken = '...'; // client token retrieved from your backend
const options = {
// container element which will contain the checkout
container: '#container',
onCheckoutComplete({ payment }) {
// Notifies you that a payment was created,
// so that you can move to next the step in your checkout flow.
// For example:
// - showing a success message
// - giving access to the service
// - fulfilling the order
},
};
const checkout = await Primer.showUniversalCheckout(clientToken, options);Note that more options can be passed to Drop-in Checkout. Please refer to the SDK Reference for more information.
Take a look at the Quick Start Guide for accepting your first payment with Headless Checkout.
Once you have a client token, you can initialize Primer’s Headless Checkout with Primer.createHeadless(clientToken).
You should then configure the onAvailablePaymentMethodsLoad listener. The listener will return the available payment methods for the client session.
Payment methods are added and configured through Primer's Dashboard. The listener will return the payment methods whose conditions match the current client session.
Below is an example of a basic implementation of Headless Universal Checkout:
const clientToken = '...'; // client token retrieved from your backend
async function onAvailablePaymentMethodsLoad(paymentMethods) {
for (const paymentMethod of paymentMethods) {
switch (paymentMethod.type) {
// configure your card form
case 'PAYMENT_CARD': {
// await configureCardForm();
break;
}
// render the payment method button
case 'PAYPAL': {
// configurePayPalButton();
break;
}
// render the payment method button
case 'APPLE_PAY': {
// configureApplePayButton();
break;
}
// render the payment method button
case 'GOOGLE_PAY': {
// configureGooglePayButton();
break;
}
// more payment methods to follow
}
}
}
function onCheckoutComplete({ payment }) {
console.log('onCheckoutComplete', payment);
}
function onCheckoutFail(error, { payment }, handler) {
console.error('onCheckoutFail', error, payment);
handler?.showErrorMessage('fail');
}
const { Primer } = window;
const headless = await Primer.createHeadless(clientToken);
await headless.configure({
onAvailablePaymentMethodsLoad,
onCheckoutComplete,
onCheckoutFail,
});
await headless.start();
console.log('Headless Universal Checkout is loaded!');Note that more options can be passed to Headless Checkout. Please refer to the SDK Reference for more information.
Primer enables you to create the UI that suits your needs, using the provided inputs and components we provide.
Handling payment methods is done by instantiating a payment method manager using createPaymentMethodManager(paymentMethodType: string, options). The instance of the manager depends on managerType.
You can learn more about the supported payment method managers in our SDK Reference.