General Migration Guide

# Remove legacy package
npm uninstall @primer-io/checkout-web

# Install new package
npm install @primer-io/primer-js

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

import { loadPrimer } from '@primer-io/primer-js';

import type {
  CheckoutElement,
  PrimerCheckoutOptions,
  PrimerJS,
} from '@primer-io/primer-js';

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

const checkout = await PrimerSDK.showUniversalCheckout(clientToken, {
  container: '#checkout-container',
  onCheckoutComplete: (data) => { /* ... */ },
  onCheckoutFail: (error, data, handler) => { /* ... */ },
});

import { loadPrimer } from '@primer-io/primer-js';

// 1. Load the SDK (registers the <primer-checkout> web component)
loadPrimer();

// 2. Get or create the checkout element
const checkout = document.querySelector('primer-checkout');

// 3. Set the client token (component property — use setAttribute)
checkout.setAttribute('client-token', clientToken);

// 4. Set SDK options (object — assign directly)
checkout.options = {
  locale: 'en-GB',
};

// 5. Listen for payment events
checkout.addEventListener('primer:payment-success', (event) => {
  const { payment, paymentMethodType } = event.detail;
  window.location.href = `/confirmation?order=${payment.orderId}`;
});

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error } = event.detail;
  console.error('Payment failed:', error.message);
});

<primer-checkout client-token="your-client-token"></primer-checkout>

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;
  
  // Now you can call SDK methods
  await primer.refreshSession();
});

let primer;

checkout.addEventListener('primer:ready', (event) => {
  primer = event.detail;
});

// Later, when needed
async function handleSessionRefresh() {
  if (primer) {
    await primer.refreshSession();
  }
}

onCheckoutComplete: (data) => {
  console.log('Payment ID:', data.payment.id);
  console.log('Customer email:', data.customer.email);
}

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment, paymentMethodType, timestamp } = event.detail;
  
  // payment is a PaymentSummary — contains partial card data
  console.log('Last 4:', payment.last4Digits);
  console.log('Network:', payment.network);
  console.log('Method:', paymentMethodType);
  
  window.location.href = '/confirmation';
});

onCheckoutFail: (error, data, handler) => {
  handler.showErrorMessage('Your card was declined');
}

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error, payment, paymentMethodType, timestamp } = event.detail;
  
  // error has: code, message, diagnosticsId, data
  console.error('Failed:', error.message, error.diagnosticsId);
  
  // The SDK shows the error in the UI automatically.
  // Use this event for logging, analytics, or retry logic.
});

onBeforePaymentCreate: (data, handler) => {
  if (!termsAccepted) {
    handler.showErrorMessage('Please accept the terms');
    handler.abort();
  } else {
    handler.continuePaymentCreation();
  }
}

checkout.addEventListener('primer:payment-start', (event) => {
  const { paymentMethodType, continuePaymentCreation, abortPaymentCreation } = event.detail;
  
  // Prevent automatic continuation
  event.preventDefault();
  
  if (!document.getElementById('terms-checkbox').checked) {
    // Show your own error UI
    alert('Please accept the terms');
    abortPaymentCreation();
  } else {
    // Optionally pass an idempotency key
    continuePaymentCreation({ idempotencyKey: 'your-key' });
  }
});

onClientSessionUpdate: (session) => {
  console.log('Session updated:', session);
}

checkout.updateClientSession(newClientToken);

// Update the client token, then call refreshSession()
checkout.setAttribute('client-token', newClientToken);

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;
  await primer.refreshSession();
});

<primer-checkout client-token="your-client-token">
  <primer-main slot="main">
    <div slot="checkout-complete">
      <h2>Thank you for your order!</h2>
      <p>Your payment was processed successfully.</p>
    </div>
  </primer-main>
</primer-checkout>

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment } = event.detail;
  window.location.href = `/confirmation?order=${payment.orderId}`;
});

PrimerSDK.showUniversalCheckout(clientToken, {
  style: {
    input: {
      base: { fontSize: 16, color: '#000000' },
      invalid: { color: '#DC3545', borderColor: '#DC3545' }
    },
    button: {
      base: { backgroundColor: '#007BFF', color: '#FFFFFF' }
    }
  }
});

primer-checkout {
  --primer-color-brand: #007BFF;
  --primer-color-text-primary: #333333;
  --primer-typography-brand: 'Inter', sans-serif;
  --primer-radius-medium: 8px;
}

checkout.setAttribute('custom-styles', JSON.stringify({
  primerColorBrand: '#007BFF',
  primerColorTextPrimary: '#333333',
  primerTypographyBrand: 'Inter, sans-serif',
  primerRadiusMedium: '8px',
}));

checkout.style.setProperty('--primer-color-brand', '#007BFF');

card: {
  requireCvv: true,
  requireCardholderName: true,
}

card: {
  cardholderName: {
    required: true,
    visible: true,
    defaultValue: 'John Doe', // Optional: pre-fill the field
  }
}

applePay: {
  merchantId: 'merchant.com.example',
  merchantName: 'Example Store',
  captureBillingAddress: true,
}

applePay: {
  buttonOptions: {
    type: 'buy',
    buttonStyle: 'black',
  },
  billingOptions: {
    requiredBillingContactFields: ['postalAddress'],
  },
  shippingOptions: {
    requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'],
    requireShippingMethod: true,
  },
}

googlePay: {
  merchantId: 'merchant-id-from-google',
  merchantName: 'Example Store',
  buttonType: 'buy',
  buttonColor: 'black',
}

googlePay: {
  buttonType: 'buy',
  buttonColor: 'black',
  buttonSizeMode: 'fill',
  buttonRadius: 4,
  buttonLocale: 'en',
  captureBillingAddress: true,
  captureShippingAddress: true,
  emailRequired: true,
  requireShippingMethod: true,
  shippingAddressParameters: {
    allowedCountryCodes: ['US', 'CA'],
    phoneNumberRequired: true,
  },
}

klarna: {
  locale: 'en-GB',
}

klarna: {
  paymentFlow: 'DEFAULT',           // 'DEFAULT' or 'PREFER_VAULT'
  allowedPaymentCategories: ['pay_now', 'pay_later', 'pay_over_time'],
  recurringPaymentDescription: '...', // Required for recurring payments
  buttonOptions: {
    text: 'Pay with Klarna',
  },
}

checkout.options = {
  locale: 'en-GB',
  klarna: {
    paymentFlow: 'DEFAULT',
  },
};

paypal: {
  buttonColor: 'blue',
  buttonShape: 'rect',
  buttonHeight: 45,
  buttonLabel: 'pay',
  buttonTagline: false,
  paymentFlow: 'PREFER_VAULT',
}

paypal: {
  style: {
    color: 'gold',    // Default is 'gold', not 'blue'
    shape: 'rect',
    height: 45,
    label: 'pay',
    tagline: false,
    layout: 'vertical',
    borderRadius: 4,
  },
  vault: true,  // Replaces paymentFlow: 'PREFER_VAULT'
}

vault: {
  visible: true,
  deletionDisabled: false,
}

vault: {
  enabled: true,       // Required — must be true to use vault
  headless: false,     // New: hide default UI for custom implementations
  showEmptyState: true, // New: show message when no saved methods
}

checkout.addEventListener('primer:ready', async (event) => {
  const primer = event.detail;

  // Create CVV input for re-capture
  const cvvInput = await primer.vault.createCvvInput({
    cardNetwork: 'VISA',         // Card network, not paymentMethodId
    container: '#cvv-container',
    placeholder: 'CVV',
  });

  // Start payment with a saved method
  await primer.vault.startPayment(paymentMethodId);

  // Or with CVV for cards requiring re-capture
  await primer.vault.startPayment(paymentMethodId, { cvv: '123' });

  // Delete a saved method
  await primer.vault.delete(paymentMethodId);
});

checkout.addEventListener('primer:vault-methods-update', (event) => {
  const { vaultedPayments, cvvRecapture, timestamp } = event.detail;
  
  // vaultedPayments is already an array
  console.log(`${vaultedPayments.length} saved methods`);
  
  vaultedPayments.forEach(method => {
    console.log(method.paymentInstrumentData?.last4Digits);
  });
  
  if (cvvRecapture) {
    // CVV re-entry is required for vaulted card payments
  }
});

checkout.options = {
  vault: {
    enabled: true,
    headless: true,
  },
};

checkout.addEventListener('primer:vault-methods-update', async (event) => {
  const { vaultedPayments, cvvRecapture } = event.detail;

  // Render your custom vault UI
  vaultedPayments.forEach(method => {
    if (method.paymentInstrumentType === 'PAYMENT_CARD') {
      const { network, last4Digits } = method.paymentInstrumentData;
      // Render: Visa •••• 4242
    }
  });

  // Create CVV input if re-capture is required
  if (cvvRecapture) {
    const primer = /* get from primer:ready */;
    const cvvInput = await primer.vault.createCvvInput({
      cardNetwork: vaultedPayments[0].paymentInstrumentData.network,
      container: '#cvv-container',
    });
  }
});

document.getElementById('my-button').addEventListener('click', () => {
  checkout.submit();
});

document.getElementById('my-button').addEventListener('click', () => {
  document.dispatchEvent(new CustomEvent('primer:card-submit', {
    bubbles: true,
    composed: true,
  }));
});

document.getElementById('vault-pay-button').addEventListener('click', () => {
  document.dispatchEvent(new CustomEvent('primer:vault-submit', {
    bubbles: true,
    composed: true,
  }));
});

checkout.addEventListener('primer:state-change', (event) => {
  const { isProcessing, isLoading } = event.detail;
  document.getElementById('my-button').disabled = isProcessing || isLoading;
});

checkout.addEventListener('primer:card-success', () => {
  // Card form is valid — enable submit
});

checkout.addEventListener('primer:card-error', (event) => {
  // Card form has validation errors
  console.log('Errors:', event.detail.errors);
});