Payment Method Component

<primer-payment-method>

The PaymentMethod component renders the appropriate payment interface based on the specified payment method type. It automatically handles different payment method categories and only displays methods that are available in your checkout configuration.

Usage

<primer-checkout client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-payment-method type="PAYPAL"></primer-payment-method>
      <primer-payment-method type="GOOGLE_PAY" disabled></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

Properties

Name	Type	Description	Default
type	String	The payment method type identifier (e.g., "PAYMENT_CARD", "PAYPAL")	undefined
disabled	Boolean	When true, disables the payment method making it non-interactive	false

Key Concepts

Configuration-Based Rendering

The primer-payment-method component only renders payment methods that are:

1. Specified by the type attribute - You declare which payment method you want to display
2. Available in your checkout configuration - The method must be enabled in your Primer Checkout Builder settings
3. Returned by the server - The method must be returned in the available payment methods list

tip

If a payment method isn't available (not configured or not returned by the server), the component simply won't render anything rather than showing an error. This makes it safe to include multiple payment method components even if some methods might not be available in all contexts.

Dynamic Payment Method Discovery

The best way to work with payment methods is to listen for the primer:methods-update event, which provides the complete list of available payment methods for your checkout configuration. This approach lets you dynamically render only the methods that are actually available.

Event Handling

For comprehensive event handling patterns, error management, and event lifecycle details, see:

• Events Guide - Implementation patterns and best practices
• Events & Callbacks Reference - Complete event API documentation

Disabled State

The disabled attribute allows you to disable specific payment methods, making them unclickable and non-interactive. This is useful for:

• Temporarily disabling payment methods during checkout flow
• Preventing interaction while processing other payments
• Implementing conditional payment method availability

<!-- Disable specific payment methods -->
<primer-payment-method type="PAYPAL" disabled></primer-payment-method>
<primer-payment-method type="GOOGLE_PAY" disabled></primer-payment-method>
<primer-payment-method type="APPLE_PAY" disabled></primer-payment-method>

React Integration

In React applications, you can conditionally apply the disabled attribute:

// Conditional disabling in React
<primer-payment-method
  type="PAYPAL"
  {...(isProcessing && { disabled: true })}
/>

// Or with explicit boolean
<primer-payment-method
  type="GOOGLE_PAY"
  disabled={!isPaymentMethodAvailable}
/>

JavaScript Control

You can dynamically enable/disable payment methods using JavaScript:

const paymentMethod = document.querySelector(
  'primer-payment-method[type="PAYPAL"]',
);

// Disable the payment method
paymentMethod.setAttribute('disabled', '');

// Enable the payment method
paymentMethod.removeAttribute('disabled');

Examples

Dynamic Payment Method Rendering

This example shows how to dynamically render payment methods based on availability:

<primer-checkout id="checkout" client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments" id="payment-methods-container">
      <!-- Payment methods will be inserted here dynamically -->
    </div>
  </primer-main>
</primer-checkout>

<script>
  const checkout = document.getElementById('checkout');
  const container = document.getElementById('payment-methods-container');

  // Listen for available payment methods
  checkout.addEventListener('primer:methods-update', (event) => {
    const paymentMethods = event.detail;

    // Clear previous content
    container.innerHTML = '';

    // Render all available payment methods
    paymentMethods.toArray().forEach((method) => {
      const methodElement = document.createElement('primer-payment-method');
      methodElement.setAttribute('type', method.type);
      container.appendChild(methodElement);
    });
  });
</script>

Advanced Layout Patterns

For complex layout customizations, container styling, and positioning patterns, see the Layout Customizations Guide.

Custom Payment Method with Options Configuration

<primer-checkout id="checkout" client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

<script>
  const checkout = document.getElementById('checkout');

  // Configure card payment options
  checkout.options = {
    card: {
      cardholderName: {
        required: true,
      },
      allowedCardNetworks: ['visa', 'mastercard', 'amex'],
    },
  };
</script>

Disabling Payment Methods During Processing

<primer-checkout id="checkout" client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments" id="payment-methods">
      <primer-payment-method
        type="PAYMENT_CARD"
        id="card-payment"
      ></primer-payment-method>
      <primer-payment-method
        type="PAYPAL"
        id="paypal-payment"
      ></primer-payment-method>
      <primer-payment-method
        type="GOOGLE_PAY"
        id="googlepay-payment"
      ></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

<script>
  const checkout = document.getElementById('checkout');

  // Listen for payment state changes
  checkout.addEventListener('primer:state-change', (event) => {
    const state = event.detail;
    const paymentMethods = document.querySelectorAll('primer-payment-method');

    if (state.isProcessing) {
      // Disable all payment methods during processing
      paymentMethods.forEach((pm) => pm.setAttribute('disabled', ''));
    } else {
      // Re-enable payment methods when not processing
      paymentMethods.forEach((pm) => pm.removeAttribute('disabled'));
    }
  });
</script>

Available Payment Method Types

For a comprehensive list of all supported payment method types, see the Payment Methods Guide.

Configuring Payment Methods

Each payment method type can be configured through the options property of the primer-checkout component:

<primer-checkout id="checkout" client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-payment-method type="GOOGLE_PAY"></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

<script>
  document.getElementById('checkout').options = {
    // Card payment configuration
    card: {
      cardholderName: {
        required: true,
      },
    },

    // Google Pay configuration
    googlePay: {
      buttonTheme: 'dark',
      buttonType: 'buy',
    },
  };
</script>

Key Considerations

Summary

• Payment methods must be configured in your Primer Checkout Builder settings to be displayed
• If a payment method is specified but not available, the component won't render anything (no error)
• The component automatically determines which payment interface to render based on the payment method's type
• Always listen to the primer:methods-update event to get the current list of available payment methods
• The component must be used within a primer-checkout context to access payment methods
• The disabled attribute makes payment methods non-interactive but they remain visible
• Disabled payment methods prevent user interaction and form submission
• Visual feedback for disabled state is handled by individual button components