Element reference

One element carries the configuration and the single event: <payplug-session>. The other elements have no API. They show and hide themselves from the session status.

<payplug-session>

The root element. It renders nothing itself.

Back from a redirect (3DS, PayPal, Wero, Oney), it scrolls the page to the message that greets the return, a refusal for instance, or to its own top edge, when they are off screen. If your page has a fixed header, give its height with --payplug-scroll-margin-top on <payplug-session> (--payplug-scroll-margin-top: 64px): every scroll of the elements stops below it. --payplug-scroll-margin-bottom leaves room under what is scrolled into view, 20px by default: set it to the height of a fixed footer, for instance.

Back from a refused payment, the elements reopen the method that was refused, with its message. To land on the list of methods instead, add forceMethodsFold to your page’s address (?forceMethodsFold): the list shows folded, and the refusal is shown when the customer opens that method again. The parameter works once: the elements remove it from the address as soon as the page loads, so a reload lands as usual.

Attributes

Attribute	Effect
base-url	Which platform to connect to (sandbox or production URL).
elements-token	The token obtained when the session is created on your server. Changing it reconnects the element. An ended session does not come back with a new token.
locale	Language and amount formats (en, fr, fr-BE…). Defaults to the browser’s language. Reactive: see Languages & currency.
color-scheme	dark or light to force one mode, otherwise the system preference decides.
theme	URL of your theme’s stylesheet: see Styling.
partial-payment	Lets your customer pay in several tranches: see Feature flags.
individual-cancel	Lets one already-authorized tranche be cancelled: 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	Shows the cart by brand: see Feature flags.
terms-of	The family of your terms (sale, use or service): it names the heading of <payplug-terms>. Without it, no heading.
selected-method	Set by <payplug-payment-methods> when the customer picks a method, removed by the form’s back link. Do not set it yourself.
terms-pending	Set by <payplug-terms> while the terms are not accepted. Do not set it yourself.

Properties

All read-only.

Property	Type	Role
view	SessionView | null	The last session view received, null before the first.
locale	string	The resolved locale.
partialPayment, individualCancel, hideCartOnFinal, showOrderIdInCart, groupCartByBrand	boolean	The resolved feature flags.
termsPending	boolean	Whether the terms are still to be accepted.

Events

Event	Detail	Emitted
payplug:statuschange	{ status, session }	On every status change, the first state included. Bubbles up to the page.
payplug:methodchange	{ method, methodId, source }	When a payment method is chosen. source: payer or auto. Bubbles.
payplug:attemptstart	{ method, methodId, amount, plan? }	Just before a payment starts. Bubbles. preventDefault() blocks it.

The composable elements

They have no attribute and no property. Compose them inside the session: they manage themselves. “Verdict pending” means an authorization is in progress.

Element	Visible when	Shows
<payplug-payment-methods>	Session PENDING, no verdict pending, no method selected.	The list of eligible methods. Picking a row sets selected-method and shows the method’s form. A single offerable method opens directly. The success banner of a tranche shows here.
<payplug-cart>	Always, except on the final screens with the hide-cart-on-final flag	The session’s cart and the total.
<payplug-processing>	Session PENDING and a verdict pending.	The waiting screen.
<payplug-progress>	Session PENDING.	The authorized/remaining progress bar as soon as an amount is authorized, the tranches, and their cancellation with individual-cancel.
<payplug-abort>	Link: PENDING with at least one authorized tranche and no verdict pending. Screen: ABORTING, ABORTED.	The abandon link, its confirmation, and the “payment abandoned” screen.
<payplug-expired>	EXPIRING, EXPIRED.	The “session expired” screen, with the recap of the released tranches if there are any.
<payplug-awaiting>	AWAITING, AWAITED_REFUSED.	The wait for a financing under review, then the refusal. An acceptance ends in PAID and goes through the confirmation.
<payplug-confirmation>	PAID.	The recap of the charged tranches and, if the session carries a statementDescriptor, the label that will appear on the bank statement.
<payplug-session-expiry>	Session PENDING.	“This payment will expire in about N minutes”.
<payplug-terms>	The session declares terms and is not over.	A switch “I have read and accept the terms & conditions” that accepts every term in one gesture, and the list of documents, each readable on the page. Until it is on, no method opens. Once accepted, it becomes “Terms & conditions accepted”.

The payment method forms

One element per payment method, all built on the same base.

With <payplug-payment-methods>, the form shows when the payer picks it. You can also compose them directly, and they hide while a verdict is pending or on the final screens.

Element	The method’s body
<payplug-cards>	The card fields through Payplug hosted fields: the card details never reach your page.
<payplug-paypal>	The PayPal redirect notice. The return resumes the session where it was.
<payplug-wero>	The Wero redirect notice. The return resumes the session where it was.
<payplug-applepay>	The Apple Pay button, opening the system’s Apple Pay sheet.
<payplug-ancv>	The Chèque-Vacances Connect id entered on the page. The customer confirms in the ANCV app, which may grant less.
<payplug-oney>	The plan choice, the computed schedule and the legal mentions. The financing covers the whole order, never a part of it.