Error Message Container

Automatically displays payment failure errors.

<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>
Properties	None
Displays	Payment 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

Displays	Does Not Display
Payment failures (after submission)	Card validation errors
Declined transactions	SDK initialization errors
Processing errors	Network 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

Event	Emitted by	How 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

Property	Description	Default
--primer-color-red-100	Error background color	#ffecec
--primer-color-border-outlined-error	Error border color	#ff7279
--primer-color-text-negative	Error text color	#b4324b
--primer-color-icon-negative	Error icon color	#ff7279

Typography

Property	Description	Default
--primer-typography-body-medium-size	Message text size	14px
--primer-typography-body-medium-weight	Message text weight	400

Spacing & Shape

Property	Description	Default
--primer-space-small	Internal padding	8px
--primer-space-medium	Icon-to-text gap	12px
--primer-radius-medium	Border radius	8px

Animation

Property	Description	Default
--primer-animation-duration	Show/hide transition	200ms
--primer-animation-easing	Transition easing	cubic-bezier(0.44, 0, 0.4, 1)

---

States

State	Description	Visual Change
Hidden	No payment failure	Not visible (height: 0)
Visible	Payment failure occurred	Error banner with icon and message
Animating	Transitioning between states	Fade/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

Do	Don’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 language	Expose error codes to the user

Tone

Do	Don’t
Be reassuring: “Please try again”	Be blaming: “You entered the wrong details”
Suggest next steps	Leave the user with no guidance

---

See also

Error handling guide

Custom error patterns

primer-card-form

Card validation