Skip to main content
A card field is an iframe mounted into a container you provide. It can fail to mount (a thrown error, before the iframe even loads) or fail to render inside a mounted container (a CSP block, after the iframe starts loading).
TL;DR: mount()/create() throws, or the container stays empty → mount only after the container exists, never re-mount a destroyed element, and check CSP for a silent frame-src block.

​
When this happens

  • mount() is called before the container element exists in the DOM.
  • mount() is called on an element that was already destroy()-ed.
  • The same element type (card, cardNumber, and so on) is created twice on one Elements instance without destroying the first.
  • The page’s Content Security Policy blocks the CDN host in frame-src, so the field’s iframe never loads.
  • The iframe doesn’t finish loading within 5 seconds (CSP block, slow network, or the CDN host being unreachable).

​
What you see

​
What to do

1

Mount only after the container exists

Make sure the target element is in the DOM before calling card.mount("#card-field") — for example, after your form template has rendered, not before.
2

Never re-mount a destroyed element

Once you call destroy(), create a new element with elements.create() instead of calling mount() again on the old one.
3

One instance per field type

If you need to switch layouts (combined card vs. split fields), create a separate Elements instance and destroy the old one — don’t try to create a duplicate type on the same instance.
4

Check CSP for a silent block

If the container renders but stays empty with no thrown error, check script-src and frame-src for your CDN host. See Content Security Policy.
5

Treat a required error as a load-failure signal

There’s no separate “load error” event — a change event with error.code: "required" on first load means the iframe didn’t finish loading in time. It usually resolves itself once the network/CSP issue clears; there’s no merchant-side retry needed beyond what you’d already do for a CSP fix.

​
Prevent it

  • In single-page apps, let the SDK’s automatic cleanup handle route changes: if the container is removed from the DOM, the element destroys itself — you only need to call destroy() yourself when you conditionally unmount a form without removing its container.
  • Roll out CSP changes as Content-Security-Policy-Report-Only first, so a missing frame-src directive shows up in violation reports before it silently breaks card fields in production.

​
Test it

See Test your integration for sandbox test cards and scenarios.

Card fields and events

Element types, methods, and the full field-error-code list.

Content Security Policy

The script-src/frame-src directives card fields need.
Last modified on September 15, 2026