Show the elements

The browser loads a script and shows the elements where you placed them. You hand them the elementsToken obtained on your server, and the checkout runs itself from there.

A complete page

<!doctype html>
<html lang="en">
  <body>
    <payplug-session
      base-url="https://services.sandbox.payplug-elements.msem.tech"
      elements-token="the token your server retrieved"
    >
      <payplug-confirmation></payplug-confirmation>
      <payplug-expired></payplug-expired>
      <payplug-abort></payplug-abort>
      <payplug-processing></payplug-processing>
      <payplug-payment-methods></payplug-payment-methods>
      <payplug-progress></payplug-progress>
    </payplug-session>

    <script type="module" src="https://cdn.sandbox.payplug-elements.msem.tech/payplug-elements.js"></script>
  </body>
</html>

That is all you have to do for the integration. The split flow, the refusals, the abandon path, the waiting screen and the end of the session all come from the elements. Your page decides where things sit, and where to redirect your customer once the session ends.

1. Load the script

The script is served from the CDN:

<script type="module" src="https://cdn.sandbox.payplug-elements.msem.tech/payplug-elements.js"></script>

You have nothing else to include: the script then loads everything the elements need.

2. The root element

The elements live inside <payplug-session>, the root element that holds the context the other elements attach to:

<payplug-session
  base-url="https://services.sandbox.payplug-elements.msem.tech"
  elements-token="the token your server retrieved"
>
  <!-- your elements, in the wrappers you choose -->
</payplug-session>

Two attributes are the whole wiring: base-url (sandbox or production), and elements-token (obtained when the session is created on your server).

Attribute	Effect
base-url	Which platform to connect to (sandbox or production URL).
elements-token	Obtained when the session is created on your server.
locale	Language and amount formats: see Languages & currency
color-scheme	dark or light to force one mode, otherwise the system preference decides: see Styling.
theme	URL of your theme’s stylesheet: see Styling.
partial-payment	Lets your customer choose to pay the total in several tranches: see Feature flags.
individual-cancel	Lets your customer cancel one already-authorized tranche: see Feature flags.
hide-cart-on-final	Hides the cart on the final screens: see Feature flags.
show-order-id-in-cart	Names the order in the cart’s title: see Feature flags.
group-cart-by-brand	Groups the cart’s lines by brand: see Feature flags.
terms-of	The family of your terms (sale, use or service), which titles <payplug-terms>: see the reference.

If your page fetches the token itself

In an SPA, a page may obtain its token later, from the browser (fetch / XHR). The token can then be handed over afterwards, and nothing renders before the first state arrives.

document.querySelector("payplug-session").setAttribute("elements-token", token);

3. The elements you compose

Each element watches the session and shows or hides itself. You do not orchestrate their visibility. All of them are technically optional, and a complete checkout composes them all.

Element	Shows
<payplug-payment-methods>	The list of payment methods, and the interface of the one your customer picks.
<payplug-cards>, <payplug-paypal>, <payplug-wero>…	A single method’s interface. Show one only if you do not use payplug-payment-methods.
<payplug-processing>	The waiting screen while a verdict is pending.
<payplug-progress>	The authorized/remaining progress bar, the tranches, and the per-tranche cancel.
<payplug-abort>	The possibility to abort the session once money is held.
<payplug-expired>	The final screen for an expired session.
<payplug-confirmation>	The final payment confirmation screen, with the recap of what was charged.
<payplug-cart>	The order summary.

The full reference of their attributes, properties and events is in the element reference.

4. We respect your layout

• Display order and wrappers: these are ordinary block-level elements in light DOM. Compose them in your layout.
• Two-way isolation: your page’s styles do not affect the elements’ own, but you can add explicit rules: see Styling.
• Every Payplug Element must stay inside its <payplug-session>.

Hide an empty container

An element with nothing to show sets hidden on itself: it takes no room in your layout, and the gap around it does not double.

Your own wrapper elements, though, stay on screen once everything inside them is hidden. Hide them in CSS with :has(): the rule follows the elements live, with no script. With hide-cart-on-final, for instance, the container that holds the cart empties on the final screens:

<div class="layout">
  <div class="wrapper">
    <payplug-cart></payplug-cart>
    <payplug-progress></payplug-progress>
  </div>
  <div class="expiry-wrapper">
    <payplug-session-expiry></payplug-session-expiry>
  </div>
  <!-- … -->
</div>

/* The wrapper disappears once none of its elements shows… */
.wrapper:not(:has(> :not([hidden]))) {
  display: none;
}

/* …and its parent can adapt its own layout. */
.layout:not(:has(> .wrapper > :not([hidden]))) {
  grid-template-columns: 1fr;
  max-width: 45rem;
  margin: 0 auto;
}

/* A wrapper that holds a single element can name it. */
.expiry-wrapper:has(> payplug-session-expiry[hidden]) {
  display: none;
}

5. One event to drive your routing

The session emits payplug:statuschange on every status change. A page that opens over an already-settled session routes straight to its final screen.

session.addEventListener("payplug:statuschange", (event) => {
  const { status } = event.detail;
  if (status === "PAID") location.assign("/order/confirmed");
  if (status === "ABORTED" || status === "EXPIRED") location.assign("/cart");
});

The final screens carry no “back to the shop” button and that’s on purpose: it is up to you to decide where to send your customer once a terminal status is reached.

• The intermediate statuses are PENDING, CAPTURING, ABORTING, EXPIRING and AWAITING.
• The terminal statuses are PAID, ABORTED, EXPIRED and AWAITED_REFUSED.

Note

A word on AWAITING: it is financing under review, possibly for days, which will end in a terminal status, PAID or AWAITED_REFUSED. Neither your customer nor you have the decision yet: the elements show their own waiting screen. The final decision will be sent to your server through the webhook.

6. Events for your analytics

Three events tell your analytics tool what your customer does. All of them bubble up to the page:

• payplug:methodchange: a payment method was chosen. source is payer when the customer made the choice, or auto when the choice is automatic (a single method on offer, or the way back from a redirect).
• payplug:attemptstart: a payment is about to start. It is emitted just before the payment is sent, and your page can still block it (see below).
• payplug:statuschange: the event also carries the session property, to read the order and its payments when it ends.

document.addEventListener("payplug:methodchange", (event) => {
  analytics.track("payment_method_selected", event.detail); // { method, methodId, source }
});
document.addEventListener("payplug:attemptstart", (event) => {
  const { method, amount } = event.detail;
  analytics.track("payment_submitted", { method, amount: amount.amount, currency: amount.currency });
});
document.addEventListener("payplug:statuschange", (event) => {
  const { status, session } = event.detail;
  if (status === "PAID") analytics.track("purchase", { orderId: session.orderId, total: session.total.amount });
});

To block a payment, a basket that changed or an item out of stock for instance, call preventDefault() in your payplug:attemptstart listener. The payment does not start, and the form stays as it was, without any message from the elements: it is up to your page to tell your customer why. The check must give its answer at once: the event does not wait for a call to your server.

document.addEventListener("payplug:attemptstart", (event) => {
  if (!basketStillValid()) {
    event.preventDefault();
    showBasketMessage(); // your own message
  }
});