Skip to main content

<primer-error-message-container>

Displays payment failure errors automatically. Subscribes to SDK state and shows/hides error messages without custom code.

Quick Reference

Parent<primer-checkout>
PropertiesNone
DisplaysPayment failures only

Examples

Basic Usage

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-card-form></primer-card-form>
      <primer-error-message-container></primer-error-message-container>
    </div>
  </primer-main>
</primer-checkout>

With Custom Layout

<primer-checkout client-token="your-token">
  <div slot="main">
    <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
    <primer-error-message-container></primer-error-message-container>
  </div>
</primer-checkout>

What It Displays

DisplaysDoes Not Display
Payment failures (after submission)Card validation errors
Declined transactionsSDK initialization errors
Processing errorsNetwork errors during load

Events

<primer-error-message-container> does not emit its own events. It subscribes to parent state internally to show and hide error messages.

Relevant Parent Events

EventEmitted byHow the container uses it
primer:state-change<primer-checkout>Reads paymentFailure from the payload — shows the error message when populated, hides when cleared
primer:payment-failure<primer-checkout>Triggers the same display — the container reacts to the resulting state change

Behavior

  • Shows when paymentFailure state is populated
  • Hides when payment succeeds or user retries
  • Includes ARIA attributes for accessibility

CSS Properties

Colors

PropertyDescriptionDefault
--primer-color-red-100Error background color#ffecec
--primer-color-border-outlined-errorError border color#ff7279
--primer-color-text-negativeError text color#b4324b
--primer-color-icon-negativeError icon color#ff7279

Typography

PropertyDescriptionDefault
--primer-typography-body-medium-sizeMessage text size14px
--primer-typography-body-medium-weightMessage text weight400

Spacing & Shape

PropertyDescriptionDefault
--primer-space-smallInternal padding8px
--primer-space-mediumIcon-to-text gap12px
--primer-radius-mediumBorder radius8px

Animation

PropertyDescriptionDefault
--primer-animation-durationShow/hide transition200ms
--primer-animation-easingTransition easingcubic-bezier(0.44, 0, 0.4, 1)

States

StateDescriptionVisual Change
HiddenNo payment failureNot visible (height: 0)
VisiblePayment failure occurredError banner with icon and message
AnimatingTransitioning between statesFade/slide animation

Usage Guidelines

Do

  • Include in any custom layout for error display
  • Place near the payment form for visibility

Don’t

  • Don’t use for validation errors (handled by input components)
  • Don’t use if implementing custom error handling via events

Alternative: Custom Error Handling

For full control, handle errors via events instead:
checkout.addEventListener('primer:state-change', (event) => {
  const { paymentFailure } = event.detail;
  if (paymentFailure) {
    document.getElementById('my-error').textContent = paymentFailure.message;
  }
});

Content Guidelines

Error messages

DoDon’t
”Your payment could not be processed. Please try again.""Error 4001: DECLINED"
"This payment method was declined. Try a different method.""Transaction failed”
Use plain languageExpose error codes to the user

Tone

DoDon’t
Be reassuring: “Please try again”Be blaming: “You entered the wrong details”
Suggest next stepsLeave the user with no guidance