EPD Elements

What this is and who needs it

EPD Elements gives your checkout a secure, ready-made card field: shoppers enter their card, the number goes straight into EPD’s vault, and it never touches your servers, which keeps your PCI compliance at its lightest tier, PCI SAQ A (a short self-check, not a full audit). Under the hood, it’s a tiny JavaScript SDK (epd.js) you drop into your own checkout form: you build and style the form, the SDK captures and tokenizes the card, and hands you a single-use card_token (cct_…) that your backend attaches to a customer with your secret key.

If you collect cards on a website or app and want to save them, charge subscriptions, or run saved-card checkout, this is the integration to use. No browser in the loop, such as phone/MOTO orders (mail-order/telephone-order, where an agent keys the card in by hand), a back-office tool, or a migration? See Inbound Card Capture for the server-to-server path.

Two keys, two jobs

EPD Elements uses a second key type alongside your secret key.

Create a publishable key in the dashboard under Settings → Developer & Integrations, on the Publishable Keys tab, using Create Publishable Key (separate from the API Keys tab, where your secret keys live).

The flow

The card_token is single-use and expires 15 minutes after creation.

1. Add the SDK

The SDK is one hosted file: drop in a single <script> tag. There is no npm package, bundler, or build step; the tag installs a callable global EPD(...).

<script src="https://js.epd.com/element/v1/epd.js"></script>
<!-- installs a global EPD(...) on window -->

2. Capture the card

Mount a single combined field (number + expiry + CVC), or three split fields you lay out yourself. Both return the same card_token.

<form id="checkout">
  <div id="card-field"></div>
  <button type="submit">Save card</button>
  <p id="error" role="alert"></p>
</form>

<script src="https://js.epd.com/element/v1/epd.js"></script>
<script type="module">
  // `EPD` is the global installed by the <script> tag above.
  const epd = await EPD('epd_test_pk_…');

  const card = epd.create('card', {
    style: { base: { fontSize: '16px', color: '#1a1a1a' } },
    placeholder: { cardNumber: '1234 1234 1234 1234' },
  });
  await card.mount('#card-field');

  // Drive your own UI from field state.
  const pay = document.querySelector('#checkout button');
  card.on('change', (state) => {
    pay.disabled = !state.complete;
  });

  document.querySelector('#checkout').addEventListener('submit', async (e) => {
    e.preventDefault();
    try {
      const { token } = await epd.createToken(card);
      // Send `token` (a cct_…) to YOUR backend.
      await fetch('/save-card', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ card_token: token }),
      });
    } catch (err) {
      document.querySelector('#error').textContent = err.message;
    }
  });
</script>

<form id="checkout">
  <div id="number"></div>
  <span id="brand-icon"></span>
  <div id="expiry"></div>
  <div id="cvc"></div>
  <button type="submit">Save card</button>
  <p id="error" role="alert"></p>
</form>

<script src="https://js.epd.com/element/v1/epd.js"></script>
<script type="module">
  const epd = await EPD('epd_test_pk_…');

  const number = epd.create('cardNumber', { placeholder: '1234 1234 1234 1234' });
  const expiration = epd.create('cardExpiration', { placeholder: 'MM/YY' });
  const cvc = epd.create('cardCvc', { placeholder: 'CVC' });

  await Promise.all([
    number.mount('#number'),
    expiration.mount('#expiry'),
    cvc.mount('#cvc'),
  ]);

  // The number field reports brand/last4 as the holder types.
  const brandIcon = document.querySelector('#brand-icon');
  number.on('change', (state) => {
    brandIcon.dataset.brand = state.brand; // 'visa', 'mastercard', …
  });

  document.querySelector('#checkout').addEventListener('submit', async (e) => {
    e.preventDefault();
    try {
      // Tokenize the trio together → opaque card_token, same as the combined field.
      const { token } = await epd.createToken({ number, expiration, cvc });
      await fetch('/save-card', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ card_token: token }),
      });
    } catch (err) {
      document.querySelector('#error').textContent = err.message;
    }
  });
</script>

3. Attach the card (your backend)

Send the card_token to Add Payment Method with your secret key:

curl -X POST https://api.epd.com/v1/customers/{customer_id}/payment_methods \
  -H "Authorization: Bearer epd_test_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "card_token": "cct_…", "set_as_default": true }'

The response is a standard payment method. From here it behaves exactly like a vaulted card: use it for orders and subscriptions.

SDK reference

EPD(publishableKey, options?)

Boots the SDK: loads your account config and prepares the secure field. Returns a Promise that resolves to an instance once the field is ready.

The instance also exposes epd.sandbox (boolean): true when booted with a test (epd_test_pk_…) key.

epd.create(type, options?)

Creates an element. type is one of:

Combined-card options ('card'):

Split-field options (shared by 'cardNumber', 'cardExpiration', 'cardCvc'):

Element methods

Every element, combined or split, shares the same instance API.

Events

Subscribe with element.on(event, listener). The listener receives the current field state plus a type field naming the event.

card.on('change', (state) => {
  payButton.disabled = !state.complete;
  brandIcon.dataset.brand = state.brand; // 'visa', 'mastercard', …
});

Field state

getState() and the change event both surface a PAN-free snapshot, never the full card number.

epd.createToken(input)

Tokenizes the entered card and returns a Promise<CardToken>. Pass either a combined card element or the split group { number, expiration, cvc }.

const { token, expiresIn, brand, last4 } = await epd.createToken(card);
// or: await epd.createToken({ number, expiration, cvc });

Throws an EpdError if the card is incomplete/invalid, the split group is incomplete, or the request fails.

Styling

The style option is a CSS-in-JS object keyed by variant, with pseudo-selectors and an optional fonts array. Only an allow-listed set of CSS properties is honored (a security boundary: anything else is ignored).

Each variant also accepts the pseudo-selectors :hover, :focus, and ::placeholder.

const card = epd.create('card', {
  style: {
    fonts: ['https://fonts.googleapis.com/css2?family=Inter&display=swap'],
    base: {
      fontFamily: "'Inter', sans-serif",
      fontSize: '16px',
      color: '#1a1a1a',
      '::placeholder': { color: '#9ca3af' },
    },
    invalid: { color: '#d92d20' },
    complete: { color: '#027a48' },
  },
});

Errors

createToken and mount reject with an EpdError carrying a stable, machine-readable code. Branch on code; show message to the shopper.

try {
  const { token } = await epd.createToken(card);
} catch (err) {
  if (err.code === 'card_invalid') {
    showFieldError('Please check the card details.');
  } else {
    showFieldError(err.message);
  }
}

Sandbox

A test publishable key (epd_test_pk_…) tokenizes against your sandbox; the SDK behaves identically. Only the key’s environment differs. Type a test card (e.g. 4111 1111 1111 1111 for a Visa success, or 4000 0000 0000 0002 to force a decline at charge time) into the field. The resulting card_token works against the sandbox Add Payment Method endpoint.

How it protects you

• The publishable key can only mint capture tokens: a leaked one cannot move money or read data.
• A card_token is single-use, expires in 15 minutes, and is bound to your merchant: it can’t be replayed or used by another merchant.
• Capture is rate-limited per merchant and per IP to blunt card-testing.
• The card field renders in a PCI-DSS Level 1 certified secure iframe; raw PAN/CVV never reach your servers, keeping you in PCI SAQ A scope.