Primer's Official Universal Checkout Web SDK

💪 Features of the 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

📚 Documentation

• Documentation
• SDK reference
• API reference
• Changelogs

💡 Support

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.

📋 Prerequisites

🔑 Generate a client token by creating a client session in your backend

🧱 Prepare a container in which to render Universal Checkout

🎉 That's it!

🧱 Installation

With npm (recommended)

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

Then import Primer in your application

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

Primer.showUniversalCheckout(clientToken, {
  // options...
});

With our CDN

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...
});

🎉 Ways of integrating the SDK

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.

Drop-In Checkout

🚀 Quick start

Take a look at our Quick Start Guide for accepting your first payment with Drop-in Checkout.

👩‍💻 Usage

🔍 Rendering the 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.

Headless Universal Checkout

🚀 Quick start

Take a look at the Quick Start Guide for accepting your first payment with Headless Checkout.

👩‍💻 Usage

🔍 Initialize 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.

🚀 Create your UI

Primer enables you to create the UI that suits your needs, using the provided inputs and components we provide.

Handle payment methods

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.