Component reference

The elements expose a deliberately small API: one root carries the configuration and the single event; the composable components have no API of their own — they render and hide themselves from the session status. This page is the exhaustive surface.

<payplug-session>

The required root and context provider. Renders nothing itself.

Attributes

Attribute	Type	Effect
base-url	URL	Where this platform answers. With elements-token, it is the whole wiring: the element builds its own NetworkSessionClient, and the page needs no script. Ignored when a sessionClient was injected.
elements-token	the session’s payer token	The session your server created. Both attributes are needed before anything is fetched; change it and the element rewires (a refreshed token). A session already proved dead is not revived by a new one — render the page again.
locale	e.g. en, fr, fr-BE	UI language and amount formats — the 24 official EU languages plus Catalan. Defaults to the browser language (navigator.language); unknown locales fall back to their base language, then to English. Reactive.
color-scheme	dark | light	Forces a scheme; absent → follows the OS preference.
theme	URL	Loads your token-override stylesheet as a <link>; removing the attribute removes the override.
partial-payment	boolean	Enables the total/partial amount chooser (split flow).
individual-cancel	boolean	Enables the per-tranche cancel action in <payplug-progress>.
hide-cart-on-final	boolean	Hides <payplug-cart> on the final screens (paid / abandoned / expired); the order total is then repatriated into the final screen.
selected-method	method instance id	UI state of the two-view flow (list ⇄ form): set by <payplug-payment-methods> when a row is selected (the config’s instance id — its id, or the method name), cleared by the forms’ back links. Only meaningful when the methods list is composed.
terms-pending	boolean	UI state written by <payplug-terms>: present while the terms are not yet accepted. The methods list then refuses to open a method and says why above its rows; a form refuses its submission. Never set it yourself.

Properties

Property	Type	Role
sessionClient	SessionClient	The one required wiring. Injecting it subscribes the session and feeds every child component (see show the elements).
view	SessionView | null	The latest received view (null until the first one). Read-only.
locale	string	The resolved locale attribute (defaults to the browser language). Read-only.
partialPayment, individualCancel, hideCartOnFinal	boolean	The resolved feature flags. Read-only.
termsPending	boolean	Whether the merchant’s terms are still to be accepted (the terms-pending attribute). Read-only.

Methods

Action proxies to the client — the components call them; your page normally never needs to. They reject with the port’s SessionActionError on a domain refusal.

Method	Action
startAttempt({ method, amount })	Dispatch a tranche (amount in minor units).
voidAuthorization(attemptId)	Cancel one authorized tranche.
abort()	Abandon the whole payment (voids every authorization).

Events

Event	Detail	Fired
payplug:statuschange	{ status: SessionView["status"] } (StatusChangeDetail)	On every status change, the first delivered state included. Bubbles.

The composable components

None of them takes attributes or exposes properties — except <payplug-terms>, described under the table: compose them inside the session and they manage themselves. “Verdict pending” below means the view carries an AUTHORIZING attempt.

Component	Visible when	Notes
<payplug-payment-methods>	Session PENDING, no verdict pending, and no method selected.	The methods list (one row per eligible method with a registered form) — selecting a row sets selected-method and injects that method’s form component. A list of ONE offerable method opens it straight away, and that form shows no way back — a one-row menu is a step, not a choice; the post-tranche success banner shows here when the loop returns to the list. When it is composed, manually composed method forms never show.
<payplug-cart>	Always.	Order title + localized total. Stays during the waiting window (with the progress).
<payplug-processing>	Session PENDING and a verdict is pending.	The single waiting screen (“Authorization in progress…”, role="status").
<payplug-progress>	Session PENDING (it stays during a pending verdict).	The meter appears once something is authorized; in-flight tranches are never listed; per-tranche cancel behind individual-cancel.
<payplug-abort>	Link: PENDING, ≥ 1 authorized tranche, no verdict pending. Screen: ABORTING / ABORTED.	The confirmation dialog makes “Continue the payment” the safe, primary action.
<payplug-expired>	EXPIRING / EXPIRED.	The released-tranches recap and hold reassurance only show when tranches were actually released.
<payplug-awaiting>	AWAITING / AWAITED_REFUSED.	The deferred-financing wait (an Oney file under review): clock mark, the e-mail promise, and the financing tranche recapped in a chip. On refusal the same screen flips to the cross — nothing was ever taken. Acceptance never shows here: the session ends PAID and the confirmation owns it.
<payplug-confirmation>	PAID.	Recap of the charged tranches; when the session carries a statementDescriptor, a reassurance line announces the label the customer will see on their bank statement.
<payplug-session-expiry>	Session PENDING.	Optional notice: “This payment will expire in about N minutes”, re-rendered exactly at each display change (deliberately not a countdown). Compose it wherever it fits; leave it out for no notice.
<payplug-terms>	The session declares terms and has not ended.	Your terms, your wording shown as-is, each opening with a document mark: clicking it reads that document on the payment page, in a modal titled with your own label, with a download action and a cross to leave (a ⌘/Ctrl-click still opens it in a tab, which is also the way out when a page refuses to be framed). One switch carries the sentence “I have read and accept the terms & conditions” and accepts every declared term in one gesture — each document is listed under it, opened by its own mark, with no box of its own: a condition of the sale is not a question. Until they are accepted, the methods list refuses to open a method (and says why); the acceptance is recorded the moment it is given (POST /elements/session/accept-terms), with its instant: the switch gives way to “Terms & conditions accepted at 14:32”, on any device. Never pre-set. Not composed → nothing is asked, nothing is recorded.

<payplug-terms> takes one attribute: terms-of (sale, use or service) names the document family in the heading and in the refusal message — “Terms of Sale”, “Terms of Use”… Leave it out and there is NO heading, and the refusal names the documents generically: we do not name a family you did not name. It fires payplug:termschange ({ satisfied, flags }, TermsChangeDetail) on every change.

The method forms

One component per payment method, all built on the same chrome and all behaving identically — no method is special:

• Visibility: in a managed session (a <payplug-payment-methods> is composed) the form is injected by the list while its method is selected — a manually composed form never shows there. Without the list, compose the form directly (single-form flow). Every form hides while a verdict is pending, and clears on the final screens.
• Shared chrome: the permanent way back to the list (“‹ Changer de moyen de paiement”), the embedded <payplug-amount-picker> and the exact-amount submit, the post-tranche success banner (single-form flow — the managed loop shows it on the list instead), the non-destructive refusal banner with its third outcome (“Choisir un autre moyen de paiement”), and the domain-error line.
• PSP redirects: when the PSP’s acknowledgement carries a redirect, the form follows it — a navigate changes location, a post submits a hidden form (the 3-D Secure ACS wants a POST). True of every method, not just the card.
• Partial authorization: when less than the requested amount is granted, the banner says so and offers to accept the hold — paying the rest another way — or to refuse it, which voids it and makes the full amount payable again. The decision is session state: it survives a page refresh.

Component	Method body
<payplug-cards>	The card fields, which are the PSP’s own hosted fields: the card number reaches neither your page nor ours. Set partialAuth: true on the card config to let the issuer grant less than requested.
<payplug-paypal>	The PayPal redirect notice; the amount is frozen before leaving, then a REAL navigation to the PSP page — the return leg resumes the session (an approval banners on the list, a decline reopens this form with the refusal).
<payplug-wero>	Same redirect behaviour as PayPal, with the Wero wording (instant account-to-account payment, confirmed in the banking app).
<payplug-applepay>	A hosted method — behaves like card (amount chooser + submit, no fields to fill); the real OS Apple Pay sheet is the provider’s.
<payplug-ancv>	Chèques-Vacances: the Chèque-Vacances Connect id is entered on the page, the customer confirms IN the ANCV app, and the verdict lands out of band — no redirect. It always requests the full remaining, and the app may grant less.
<payplug-oney>	A redirected BNPL method (pay in installments): a 3× / 4× plan selector with per-plan fee rates and APR (TAEG), and a live schedule (per-installment amounts, fees, total cost) recomputed before the customer commits, plus the legal credit mention. Financing covers the whole order: offered only while the full total remains to pay, and never partially.

Advanced: <payplug-amount-picker>

Embedded by <payplug-cards> — you don’t place it yourself, but it is exported and reusable if you build a custom method form on the same session.

Member	Type	Role
method (attribute + property)	string	The embedding payment method; selects the title copy (“Amount to pay by card”…).
amount	number | null	The amount the customer chose, in minor units (null while unparseable).
valid	boolean	Whether that amount is submittable (full → positive remaining; partial → within [1 major unit, remaining]).
reset()		Returns to the default “pay the full remaining” mode (called after a tranche lands).
payplug:amountchange (event)	{ amount, valid, mode } (AmountChangeDetail)	Fired on every user change. Bubbles.

Module exports

Loading payplug-elements.js registers every element (idempotent). For bundler-based integrations the module also exports:

Export	Role
defineElements()	Re-registers the elements (idempotent — already called on load).
PayplugSession, PayplugCards, …	The element classes (one per tag), for instanceof checks and typed queries.
StatusChangeDetail, AmountChangeDetail, ElementProps	The event/detail types.
translate, translateNodes, ensureLocale, SUPPORTED_LANGUAGES	The i18n runtime, if your custom code needs the same catalogs.
formatMoney	Locale-aware money formatting (Intl, digits per currency).
PayplugElement, authorizing, h	The base class, the “verdict pending” helper and the DOM builder — for writing your own session-driven components.

HTMLElementTagNameMap is augmented for every payplug-* tag: document.createElement and typed helpers return the concrete classes.