Web Drop-in

Drop-in is a ready-made UI component from the PlexyPay Web SDK that:

shows available payment methods;

collects shopper payment details;

manages the payment flow on the frontend.

How it works

For a Drop-in integration with PlexyPay, you need to implement three main parts:

1. Payment server (backend)

Your backend calls the PlexyPay API to create a payment session (for example, via the /sessions endpoint) and returns the session object to the client.

2. Client website (frontend)

Your client application renders the PlexyPay Drop-in UI, created with the PlexyPay Web SDK.
Drop-in uses the session data from your backend to:

show available payment methods,

collect shopper payment details,

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

and present the result to the shopper.

3. Webhook server

Your webhook endpoint receives PlexyPay notifications containing the final outcome of each payment.
This is the source of truth for updating order status 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 on the client website.

2. Backend creates a PlexyPay payment session

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

3. Frontend initializes PlexyPay Drop-in

The client application creates an PlexyCheckout instance with the session data and configuration, then creates and mounts a Drop-in instance.

4. Drop-in handles the payment UI & actions

Drop-in:

displays the available payment methods,

collects the shopper’s payment details,

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

and shows the immediate payment result to the shopper using your event handlers.

5. Webhook confirms the payment outcome

Your webhook server receives a notification from PlexyPay that contains the final payment outcome.
You use this webhook to update the order state in your backend (for example, Paid, Refused, Cancelled) and to drive any post-payment business logic.

Limitations

WARNING

Make sure that your integration follows these limitations and best practices:

<iframe> usage: If you embed the checkout in an <iframe>, it must be hosted on the same domain as the parent window to support redirect-based payment flows.

WebViews in native apps: We do not recommend using WebViews to host the web checkout in native apps due to security and functionality limitations. Prefer native payment components or the system browser instead.

Server-side Rendering (SSR): If you use SSR, ensure that the PlexyCheckout instance and all Components are created and mounted only on the client side, not during server rendering.

Browser support: PlexyPay Web SDK supports recent versions of all major browsers. Very old or unsupported browsers may not render Drop-in correctly or may miss security updates.

CAUTION

3D Secure 2 & Content Security Policy (CSP)
A strict Content Security Policy (CSP) can block native 3D Secure 2 challenge flows, because loading the 3DS2 interface may require allowing additional third-party URLs.
If you cannot relax your CSP rules, configure your integration to use a redirect-based 3D Secure flow instead of the native challenge flow.

Quick Start

Install PlexyPay Web SDK (@plexy/plexy-web)

Install the npm package into your frontend application and include the styles.

Create a DOM container for Drop-in

Add a container with an id, for example <div id="dropin-container"></div>, on your checkout page.

Create a payment session on your server

Your backend calls the PlexyPay /sessions API and returns the session object to the frontend.

Initialize PlexyPay Checkout

Build globalConfiguration with session, amount, locale, countryCode, and event handlers, then create an instance of PlexyCheckout.

Create Drop-in and mount it

Create an instance of Dropin(checkout, dropinConfiguration) and mount it into #dropin-container.

Handle the payment result

Use onPaymentCompleted / onPaymentFailed with result.resultCode, and rely on PlexyPay webhooks to update your order.

Install PlexyPay Web SDK

Install the package

Import Drop-in with all payment methods

Import Drop-in with individual payment methods (tree-shaking)

CHECK

When importing individual payment methods, your bundle size is smaller and the page loads faster.

WARNING

Make sure the script version on the CDN matches the version of @plexy/plexy-web you use (for example, 6.25.1).

Create a DOM element for Drop-in

Add the container to your checkout page:

TIP

If you use React/Vue/Svelte, use a ref, not a query selector, and do not re-render the DOM node that Drop-in is mounted into.

PlexyPay Checkout & Drop-in: concepts

PlexyPay Checkout (PlexyCheckout)

Drop-in

Global configuration (PlexyPay Checkout)

Create a global configuration object that you will use to instantiate PlexyCheckout.

Required parameters

Parameter	Required	Description
`session`	✅	Payment session object created by your backend using PlexyPay `/sessions`. Contains `session.id` and `session.sessionData`.
`environment`	✅	Use `test`. When you are ready for live payments, switch to `live` (or a specific PlexyPay live environment if you segment by region).
`amount`	✅	Object with fields `value` (in minor units, for example cents for EUR) and `currency` (ISO code).
`countryCode`	✅	Shopper country code (ISO 3166-1 alpha-2). Used to filter available payment methods.
`locale`	✅	Drop-in UI locale (for example, `en-US`, `nl-NL`). Defaults to `shopperLocale` from `/sessions` or `en-US`.

Optional parameters

Parameter	Required	Description
`showPayButton`	❌	Shows or hides the Pay button for each method. Defaults to `true`. When `false`, you must call `.submit()` manually.
`secondaryAmount`	❌	Shows an additional currency on the Pay button. You perform the conversion yourself and set `currency`, `value`, `currencyDisplay`.
`paymentMethodsConfiguration`	❌	Global configuration for payment methods (can be overridden in Drop-in configuration).

Global event handlers

Core PlexyPay Drop-in events

Handler	Required	Description
`onPaymentCompleted(result, component)`	✅	Called when the payment flow completes (successful or not). Use `result.resultCode`.
`onPaymentFailed(result, component)`	✅	Called when a payment ends with `Cancelled`, `Error`, or `Refused`.
`onError(error, component)`	❌	Called when an internal Drop-in error occurs (network, cancellation, config issues, etc.).
`beforeSubmit(data, component, actions)`	❌	Lets you add extra fields to the payment request (for example `billingAddress`, `deliveryAddress`, `shopperEmail`, `shopperName`).
`onSubmit(state, component, actions)`	⚠️	Required only if you need to update the amount after Drop-in is rendered and you are using additional endpoints.
`onActionHandled(data)`	❌	Called when an action is shown (3-D Secure, QR, `await`).
`onAdditionalDetails(state, component, actions)`	⚠️	Required if the payment method needs additional details to be confirmed on your server (for example, native 3DS2 or native QR methods).
`onChange(state, component)`	❌	Called whenever the form state changes.

When to use

Use onPaymentCompleted / onPaymentFailed to display the result on the frontend and navigate to a “Thank you” or “Payment failed” page.

Use onError to log errors and show friendly messages to the shopper.

Use beforeSubmit if you need to enrich the payment request before it is sent.

Use onSubmit to support flows with dynamic amounts (for example, recalculating the cart before the final charge).

Use onAdditionalDetails when your integration requires an additional server-side confirmation step.

Use onChange if you want to validate or react to form changes in real time.

Error object format

Field	Description
`error.name`	Error type: `NETWORK_ERROR`, `CANCEL`, `IMPLEMENTATION_ERROR`, `ERROR`.
`error.message`	Technical message, useful for logs but usually not shown directly to shoppers.
`component`	The Drop-in/component instance where the error occurred.
`...`	Additional fields inherited from `Error()`.

NETWORK_ERROR — a network request made by Drop-in (to your backend or PlexyPay) failed.
CANCEL — the shopper cancelled the payment (for example, in Apple Pay UI).
IMPLEMENTATION_ERROR — your integration is misconfigured (invalid method or parameter).
ERROR — generic catch‑all error.

Example globalConfiguration

Create PlexyPay Checkout instance

TIP

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

Drop-in configuration

Create a separate configuration object for Drop-in:

Core Drop-in parameters

Parameter	Required	Description
`paymentMethodComponents`	⚠️ (if importing individual methods)	Array of payment method components, for example `[Card, GooglePay, ApplePay]`.
`paymentMethodsConfiguration`	❌	Per-payment-method configuration (overrides global configuration).
`openFirstPaymentMethod`	❌	Automatically opens the first payment method on page load. Defaults to `true`.
`openFirstStoredPaymentMethod`	❌	Opens the stored payment method on load if available (takes precedence over `openFirstPaymentMethod`).
`openPaymentMethod.type`	❌	Automatically selects the specified payment method type when Drop-in renders.
`showStoredPaymentMethods`	❌	Shows or hides stored payment methods. Defaults to `true`.
`showRemovePaymentMethodButton`	❌	Shows a button to remove a stored payment method. Requires `onDisableStoredPaymentMethod`.
`showPaymentMethods`	❌	Shows regular (non-stored) payment methods. Can be set to `false` if you only want stored methods.
`redirectFromTopWhenInIframe`	❌	If Drop-in is inside an `iframe`, set `true` to perform redirects on the top-level window.
`instantPaymentTypes`	❌	Moves specified payment methods (Apple Pay, Google Pay) to the top of the list.
`disableFinalAnimation`	❌	Disables the final animation after checkout finishes.
`showRadioButton`	❌	Adds a radio button to payment methods in the list.

Extra Drop-in event handlers

Handler	Description
`onReady()`	Called when Drop-in is initialized and ready to use.
`onSelect(component)`	Called when the shopper selects a payment method.
`onDisableStoredPaymentMethod(storedPaymentMethodId, resolve, reject)`	Called when a shopper removes a stored payment method. You must call your backend to `DELETE` the stored method and then call `resolve()` or `reject()`.

Example Drop-in configuration (individual methods)

Payment methods configuration (card example)

Override global configuration for a specific method

Create and mount Drop-in instance

Drop-in instance methods

Method	Description
`mount(selectorOrElement)`	Mounts Drop-in into the DOM (CSS selector string or `HTMLElement`).
`unmount()`	Unmounts Drop-in from the DOM (recommended if the amount changes or you reinitialize the flow).
`closeActivePaymentMethod()`	Closes the currently selected payment method (for example, to reset the form).
`update(newProps?)`	Updates properties and remounts Drop-in (for example, if configuration changes after initial mount).

Custom styling (theming PlexyPay Drop-in)

You can override CSS custom properties to match Drop-in styling with your brand.

override.css

Checkout code

TIP

For a list of available CSS variables, see the PlexyPay Web SDK stylesheet (form, button, label theming, etc.).

Handle redirect flows (3-D Secure, etc.)

Some payment methods (for example some 3-D Secure flows) redirect the shopper back to your website.

After returning to the returnUrl you specified when creating the session, the URL will contain query parameters:

sessionId — payment session identifier;

redirectResult — data required to finalize the redirect.

Example returnUrl:

https://your-company.example.com/?sessionId=CSD9CAC34EBAE225DD&redirectResult=X6XtfGC3!Y...

Redirect handling flow

Extract parameters from the query string

Read sessionId and redirectResult from the URL when the shopper returns to your site.

Create a PlexyPay Checkout instance

Instantiate PlexyCheckout with configuration that includes the extracted sessionId and other environment settings.

Submit redirectResult

Call checkout.submitDetails({ details: { redirectResult } }) to complete the payment flow.

Use onPaymentCompleted / onPaymentFailed

After submitDetails, Drop-in triggers onPaymentCompleted or onPaymentFailed. Use result.resultCode to show the final status.

Redirect handling example:

CAUTION

If the shopper never returns to your website, do not call submitDetails. In this case, the payment outcome is reported via PlexyPay webhook only.

Payment outcome & webhooks

After Drop-in finishes the payment flow:

On the frontend, onPaymentCompleted or onPaymentFailed is called.

On your backend, PlexyPay sends a webhook with the final payment outcome.

Informing the shopper

Use:

result.resultCode from onPaymentCompleted / onPaymentFailed to display a status on the frontend.

The PlexyPay webhook as the source of truth for updating the order state in your system.

CHECK

Recommended pattern:

Show an intermediate status on the frontend (for example, “Payment processing…”).

Set the final order status (Paid, Refused, Cancelled, etc.) based on the PlexyPay webhook.

How it works#

Payment flow#

Limitations#

Quick Start#

Install PlexyPay Web SDK#

Install the package#

Import Drop-in with all payment methods#

Import Drop-in with individual payment methods (tree-shaking)#

Create a DOM element for Drop-in#

PlexyPay Checkout & Drop-in: concepts#

Global configuration (PlexyPay Checkout)#

Required parameters#

Optional parameters#

Global event handlers#

Error object format#

Example globalConfiguration#

Create PlexyPay Checkout instance#

Drop-in configuration#

Core Drop-in parameters#

Extra Drop-in event handlers#

Example Drop-in configuration (individual methods)#

Payment methods configuration (card example)#

Override global configuration for a specific method#

Create and mount Drop-in instance#

Drop-in instance methods#

Custom styling (theming PlexyPay Drop-in)#

Handle redirect flows (3-D Secure, etc.)#

Redirect handling flow#

Payment outcome & webhooks#

Informing the shopper#

How it works

Payment flow

Limitations

Quick Start

Install PlexyPay Web SDK

Install the package

Import Drop-in with all payment methods

Import Drop-in with individual payment methods (tree-shaking)

Create a DOM element for Drop-in

PlexyPay Checkout & Drop-in: concepts

Global configuration (PlexyPay Checkout)

Required parameters

Optional parameters

Global event handlers

Error object format

Example globalConfiguration

Create PlexyPay Checkout instance

Drop-in configuration

Core Drop-in parameters

Extra Drop-in event handlers

Example Drop-in configuration (individual methods)

Payment methods configuration (card example)

Override global configuration for a specific method

Create and mount Drop-in instance

Drop-in instance methods

Custom styling (theming PlexyPay Drop-in)

Handle redirect flows (3-D Secure, etc.)

Redirect handling flow

Payment outcome & webhooks

Informing the shopper