Skip to main content

<primer-payment-method>

Renders the appropriate payment interface for a specified type. Only displays if the method is configured in your Dashboard and available for this checkout.

Quick Reference

Parent<primer-checkout>
Propertiestype, disabled
EmitsNone — subscribes to parent events (see Events)

Examples

Multiple Methods

<primer-checkout client-token="your-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"></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

Disabled

<primer-payment-method type="PAYPAL" disabled></primer-payment-method>

Dynamic Rendering

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail.toArray();
  const container = document.getElementById('payment-methods');
  
  methods.forEach(method => {
    const el = document.createElement('primer-payment-method');
    el.setAttribute('type', method.type);
    container.appendChild(el);
  });
});

Disable During Processing

checkout.addEventListener('primer:state-change', (event) => {
  document.querySelectorAll('primer-payment-method').forEach(pm => {
    event.detail.isProcessing 
      ? pm.setAttribute('disabled', '') 
      : pm.removeAttribute('disabled');
  });
});

Properties

PropertyAttributeTypeDefaultDescription
typetypestringPayment method identifier
disableddisabledbooleanfalseDisables interaction

Events

<primer-payment-method> does not emit its own events. Payment outcomes are reported by the parent <primer-checkout> component.

Relevant Parent Events

EventEmitted byHow it affects this component
primer:methods-update<primer-checkout>Determines whether this method renders — only methods in the collection are displayed
primer:state-change<primer-checkout>Provides isProcessing to disable the method during payment
primer:payment-success<primer-checkout>Indicates payment completed — includes paymentMethodType to identify which method was used
primer:payment-failure<primer-checkout>Indicates payment failed — includes paymentMethodType

Checking availability before rendering

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

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail.toArray();
  const available = methods.map(m => m.type);

  // Only render methods that are available for this checkout
  available.forEach(type => {
    const el = document.createElement('primer-payment-method');
    el.setAttribute('type', type);
    document.getElementById('methods').appendChild(el);
  });
});

Common Types

TypeDescription
PAYMENT_CARDCard form
APPLE_PAYApple Pay button
GOOGLE_PAYGoogle Pay button
PAYPALPayPal button
KLARNAKlarna
ADYEN_BLIKBLIK (Poland)
See Available Payment Methods for full list.

Rendering Behavior

Renders only when all conditions are met:
  1. type attribute is set
  2. Method is enabled in Primer Dashboard
  3. Method is returned by server for this checkout
If unavailable, renders nothing (no error).

Configuration

Configure via SDK options on <primer-checkout>:
checkout.options = {
  card: {
    cardholderName: { required: true }
  },
  googlePay: {
    buttonTheme: 'dark',
    buttonType: 'buy'
  }
};

CSS Properties

CSS properties vary by payment method type. Each renders different internal components.

Card Form (PAYMENT_CARD)

Uses Input Styling Tokens for input fields.

Native Payment Buttons (APPLE_PAY, GOOGLE_PAY, PAYPAL)

PropertyDescriptionDefault
--primer-space-smallGap between buttons8px
--primer-space-mediumButton container padding12px
Note: Apple Pay, Google Pay, and PayPal buttons use their native styling which cannot be customized via CSS properties. Button appearance is controlled through SDK options.

Alternative Payment Methods (KLARNA, ADYEN_BLIK, etc.)

PropertyDescriptionDefault
--primer-space-smallInternal spacing8px
--primer-space-mediumContainer padding12px
--primer-radius-smallBorder radius4px
--primer-color-border-outlined-defaultContainer borderrgba(33, 33, 33, 0.14)
--primer-color-background-outlined-defaultContainer backgroundwhite
--primer-color-text-primaryPrimary text color#212121
--primer-color-text-secondarySecondary text colorrgba(33, 33, 33, 0.62)
--primer-animation-durationTransition duration200ms

States

StateDescriptionVisual Change
HiddenMethod unavailableNot rendered
LoadingInitializing methodLoading indicator
ReadyReady for interactionStandard appearance
ProcessingPayment in progressLoading state, disabled
Disableddisabled attribute setMuted appearance, no interaction

Type-Specific States

Card Form (PAYMENT_CARD):
  • Inherits states from <primer-card-form>
Native Buttons (APPLE_PAY, GOOGLE_PAY, PAYPAL):
  • Loading, Ready, Processing states managed by native SDKs
Alternative Methods (KLARNA, BLIK, etc.):
  • May show additional states like category selection or code entry

Usage Guidelines

Do

  • Use primer:methods-update to discover available methods
  • Disable all methods during processing
  • Configure payment options on <primer-checkout>

Don’t

  • Don’t use alongside <primer-card-form> for PAYMENT_CARD (causes duplicate)
  • Don’t assume a method is available — check primer:methods-update

Content Guidelines

Section headings

DoDon’t
”Pay with card""PAYMENT_CARD” (internal type name)
“Other payment methods""APMs” (jargon)
Use sentence caseUse title case or all caps

Unavailable method messaging

DoDon’t
Render nothing (default behavior)“This payment method is unavailable”
Show only available methodsShow disabled/grayed-out unavailable methods