Web Components

PlexyPay Web Components

PlexyPay Web Components let you render individual payment methods anywhere on your website.

INFO

Use PlexyPay Web Components when you want fine-grained control over layout and UX, and need to place each payment method in a custom position on your page.

Supported payment methods

PlexyPay Web Components support:

Cards (debit, credit, co-branded)

Digital wallets (for example, Apple Pay, Google Pay)

Local payment methods exposed in your region

To see the full list of supported payment methods for your account, inspect the
paymentMethodsResponse from the PlexyPay /sessions API.

Features

Low development effort per method
Integrate each payment method as a standalone Component with a shared checkout configuration.

Per-method UI customization
Style each Component individually (for example, card-specific branding, icons, or labels).

Flexible layout
Place Components anywhere on your page – not just in a single checkout container.

3D Secure 2 support
Use the 3D Secure 2 Component to handle native 3DS2 challenge flows where supported.

How it works

For a Components integration with PlexyPay, you implement three main parts:

1. Payment server (backend)

Your backend calls the PlexyPay API to:

create a payment session (for example via /sessions),

optionally fetch available payment methods,

process additional payment details, if required.

The server returns the session information to the client.

2. Client website (frontend)

Your frontend renders one or more PlexyPay Web Components (Card, Wallet, etc.).

Each Component:

uses the session data from your backend,

collects shopper payment details,

manages additional actions (3DS, QR, redirects),

calls your event handlers when the payment flow completes.

3. Webhook server

Your webhook endpoint receives PlexyPay notifications with the final outcome of each payment.

This is your source of truth for updating order and subscription state in your system.

Payment flow

The parts of your integration work together to complete the payment flow. The high-level flow is the same for all payment methods:

1. Shopper opens the checkout page

The shopper navigates to your checkout page where one or more Components will be rendered.

2. Backend creates a PlexyPay payment session

Your server uses shopper details (for example, country and currency) to call PlexyPay and create a payment session, then returns the session object to the client.

3. Frontend initializes PlexyPay Checkout

The client application creates an PlexyCheckout instance with the global configuration and the session data.

4. Frontend creates payment Components

For each available payment method, your frontend:

checks checkout.paymentMethodsResponse,

creates the corresponding Component instance (for example, Card),

mounts it into a dedicated DOM container.

5. Component handles the payment UI & actions

The Component:

collects the shopper’s payment details,

handles additional actions (for example, 3D Secure or QR flows),

and passes the immediate result to your event handlers.

6. Webhook confirms the final outcome

Your webhook server receives a PlexyPay notification with the final payment outcome (for example, Authorised, Refused).
You update your order status and execute post-payment logic based on this webhook.

Prepare your front end

Client website

Use a Component for each payment method you want to show, and use it to collect payment details from your shoppers.

Install PlexyPay Web SDK

Install via npm

TIP

Pin the major/minor version (6.25.x) to keep behavior stable across updates.

Import PlexyPay Web SDK into your application

Components are also exposed on the window global when you load PlexyPay Web SDK via script.

Create a DOM element for the Component

Create a container element on your checkout page where you want a specific Component to be rendered, and give it a descriptive id.

For example, for the Card Component:

WARNING

We strongly recommend not putting Components inside an iframe, because it can break redirect-based flows and 3DS2 challenges.

TIP

If you use React/Vue/Svelte, use refs (not raw selectors) and avoid re-rendering the DOM node that the Component is mounted into.

PlexyPay Checkout & Components: concepts

PlexyPay Checkout (PlexyCheckout)

Components

Global configuration (PlexyPay Checkout)

Create a global configuration object to initialize PlexyCheckout.

Required parameters

Parameter	Required	Description
`session`	✅	Payment session object from your `/sessions` backend call. Includes `session.id` and `session.sessionData`.
`environment`	✅	Use `test` during development. Switch to `live` when accepting real payments.
`amount`	✅	Object with `value` (in minor units, for example cents for EUR) and `currency` (ISO code).
`countryCode`	✅	Shopper’s country code (ISO 3166-1 alpha-2). Used to filter available payment methods.
`locale`	✅	Language used in the Component UI, for example `en-US`. Defaults to `shopperLocale` from `/sessions` or `en-US`.

Optional parameters

Parameter	Required	Description
`showPayButton`	❌	Shows or hides the Pay button for each Component. Defaults to `true`. If set to `false`, you must trigger `.submit()` yourself.
`secondaryAmount`	❌	Shows a second currency value on the Pay button. You must do the conversion and set `currency`, `value`, and `currencyDisplay`.
`paymentMethodsConfiguration`	❌	Global configuration for individual payment methods. Can be overridden by per-Component config.

Global event handlers (Components)

Core PlexyPay Component events

Handler	Required	Description
`onPaymentCompleted(result, component)`	✅	Called when the payment is completed. Use `result.resultCode` to understand the outcome.
`onPaymentFailed(result, component)`	✅	Called when a payment fails with result code `Cancelled`, `Error`, or `Refused`.
`onError(error, component)`	❌	Called when an error occurs in a Component (network issues, config errors, etc.).
`beforeSubmit(data, component, actions)`	❌	Lets you add extra data (for example `billingAddress`, `deliveryAddress`, `shopperEmail`, `shopperName`) before sending the payment request.
`onSubmit(state, component, actions)`	⚠️	Required if you need to update the amount after the Component is rendered and use additional endpoints.
`onActionHandled(data)`	❌	Called when an action is shown, for example 3D Secure 2 challenge, QR, or `await`.
`onAdditionalDetails(state, component, actions)`	⚠️	Required when a payment method needs extra details to be confirmed on your server (for example, native 3DS2 or native QR methods).
`onChange(state, component)`	❌	Called whenever the form state of the Component changes.

How to use them

Use onPaymentCompleted / onPaymentFailed to drive UI transitions (“Thank you” vs “Payment failed”) and logging.

Use onError for error logging and to show safe, user-friendly error messages.

Use beforeSubmit if you want to inject additional shopper data into the payment request.

Use onSubmit for dynamic amount scenarios (recalculating cart totals right before payment).

Use onAdditionalDetails if the PSP requires a second server-side step to complete the payment (for example, native 3DS2).

Use onChange to monitor validation state, enable/disable your own Pay buttons, or pre-validate inputs.

Error object format

Field	Description
`error.name`	Error type: `NETWORK_ERROR`, `CANCEL`, `IMPLEMENTATION_ERROR`, `ERROR`.
`error.message`	Technical message (not meant to be shown directly to shoppers).
`component`	Component instance that triggered the error (for example, your card Component).
`...`	Additional properties inherited from `Error()`.

Example globalConfiguration

Create an instance of PlexyPay Checkout

TIP

In reactive frameworks (React, Vue, etc.), initialize PlexyCheckout once, when you are ready to render payment methods. Avoid re-initializing it on every re-render.

Create your Component configuration

Some payment methods require additional configuration; others support optional customization only.

Example: Card Component configuration

Configuration for a specific payment method overrides the global configuration where overlapping.

Override global configuration

Check available payment methods & create Components

Use the paymentMethodsResponse property of the PlexyCheckout instance to inspect which payment methods are available:

If a specific payment method is available, create and mount its Component:

The exact Component you use depends on the payment method (for example, Card, wallet-specific Components, etc.).

Component instance methods

Once created, a Component instance exposes the following methods:

Method	Description
`mount(selectorOrElement)`	Mounts the Component into the DOM (CSS selector or `HTMLElement`).
`unmount()`	Unmounts the Component from the DOM. Recommended if the amount or configuration changes.
`update(newProps?)`	Updates properties and remounts the Component (for example, after changing part of the configuration).

Handle the payment

Once you create and mount a Component, the shopper interacts with its UI to complete the payment. The configured Component handles the entire flow, except when a redirect is required.

Handle redirects

Some payment methods (for example, some 3D Secure flows) redirect the shopper back to your website. When the shopper returns, you must handle the result.

After the shopper is redirected back to your returnUrl, the URL includes:

sessionId — the payment session identifier;

redirectResult — the data required to finalize the payment.

Example returnUrl:

// The return URL has query parameters related to the payment session.
https://your-company.example.com/?sessionId=CSD9CAC34EBAE225DD&redirectResult=X6XtfGC3!Y...

Redirect handling function

Your redirect handler needs to:

Extract sessionId and redirectResult from the query string.

Create an PlexyCheckout instance using the extracted sessionId.

Submit the redirectResult to complete the flow.

If the shopper never returns to your website, do not call submitDetails, because attempting it will not change the outcome. In that case, rely on the webhook to learn the final result.

After you submit redirectResult, the Component triggers onPaymentCompleted(result, component). Use result.resultCode to inform the shopper.

To keep your order state accurate, always update it based on the webhook that PlexyPay sends to your server.

Payment outcome & webhooks

After a Component finishes the payment flow:

on the frontend, onPaymentCompleted or onPaymentFailed is fired;

on the backend, PlexyPay sends a webhook with the final payment result.

Informing the shopper

Use:

result.resultCode from onPaymentCompleted / onPaymentFailed to present status to the shopper;

PlexyPay webhooks as the authoritative source for order state in your backend (for example, Paid, Refused, Cancelled).

CHECK

Recommended pattern:

Show an immediate status based on the Component events.

Finalize order state (and trigger fulfilment) based on the webhook from PlexyPay.

Web Components

Supported payment methods#

Features#

How it works#

Payment flow#

Prepare your front end#

Client website#

Install PlexyPay Web SDK#

Import PlexyPay Web SDK into your application#

Create a DOM element for the Component#

PlexyPay Checkout & Components: concepts#

Global configuration (PlexyPay Checkout)#

Required parameters#

Optional parameters#

Global event handlers (Components)#

Error object format#

Example globalConfiguration#

Create an instance of PlexyPay Checkout#

Create your Component configuration#

Example: Card Component configuration#

Override global configuration#

Check available payment methods & create Components#

Component instance methods#

Handle the payment#

Handle redirects#

Redirect handling function#

Payment outcome & webhooks#

Informing the shopper#

Supported payment methods

Features

How it works

Payment flow

Prepare your front end

Client website

Install PlexyPay Web SDK

Import PlexyPay Web SDK into your application

Create a DOM element for the Component

PlexyPay Checkout & Components: concepts

Global configuration (PlexyPay Checkout)

Required parameters

Optional parameters

Global event handlers (Components)

Error object format

Example globalConfiguration

Create an instance of PlexyPay Checkout

Create your Component configuration

Example: Card Component configuration

Override global configuration

Check available payment methods & create Components

Component instance methods

Handle the payment

Handle redirects

Redirect handling function

Payment outcome & webhooks

Informing the shopper