Drop-in

Integrate the pre-built Plexy checkout UI in your web app

Original source: https://plexy.money/docs/sdks/web/drop-in.

Drop-in is the fastest way to integrate Plexy on the web: a single component renders the full checkout UI for the payment methods you choose.

Quick Start: Drop-in with Sessions Flow

The Sessions flow is the simplest way to accept payments. Your backend creates a session, your client renders Drop-in.

1. Create a session on your backend. Call POST /sessions on the Plexy Checkout API with the amount, country, and return URL. Return id and sessionData to your client. See Backend: API route handlers for a complete Next.js example.

2. Mount Drop-in:

The initialized ref is important: React 18's Strict Mode runs effects twice in development, which would mount Drop-in twice without the guard.

Drop-in with Advanced Flow

Use the Advanced flow when you need to control each /payments and /payments/details call from your backend.

Your backend provides paymentMethodsResponse by calling POST /paymentMethods. Inside each callback, forward the state to the matching API route — the route handlers shown in Backend: API route handlers take care of injecting merchantAccount and the API key.

Configuring Drop-in

DropinConfiguration accepts:

Each component class (Card, ApplePay, GooglePay) accepts its own configuration object under the matching key.

React (non-Next.js)

The same pattern works in any React app. Mount on the client, guard against Strict Mode double-invocation, and unmount on teardown:

Next.js App Router

Add these environment variables to .env.local:

The SDK is browser-only. Always mount it in a component marked 'use client', and create sessions inside a Server Action or Route Handler. Never import '@plexy/plexy-web' from server code.

Backend: API Route Handlers

Proxy every Plexy Checkout API call through your own backend so the API key never reaches the browser. All four handlers follow the same shape: accept the client's body, inject merchantAccount server-side, forward to Plexy with X-Api-Key, return the upstream JSON.

`app/api/sessions-setup/route.ts`

`app/api/payments/route.ts`

`app/api/payments/details/route.ts`

`app/api/payment-methods/route.ts`

Handling the Payment Result

Three callbacks on CoreConfiguration cover every outcome:

onPaymentCompleted(data, element) — the payment reached a terminal state. Inspect data.resultCode.

onPaymentFailed(data, element) — payment failed (refused, cancelled, expired, etc.).

onError(error) — an SDK or network error, not a payment outcome.

Common resultCode values: Authorised, Refused, Pending, Cancelled, Error, Received, ChallengeShopper, RedirectShopper.

Never treat the client-side resultCode as a source of truth for "payment completed". Confirm on the server via Plexy webhooks or a GET /sessions/{id} poll before fulfilling the order.

Redirect Flow

For 3DS challenges and payment methods that navigate away from your site, Plexy returns to the returnUrl you pass to POST /sessions or POST /payments. That URL should point at a page in your app that finalises the checkout.

Render a /redirect page on the client, read sessionId and redirectResult from the query string, and submit the details back to Plexy:

Set the matching returnUrl in your /sessions or /payments request to https://yoursite.com/redirect.

11-web-drop-in

Drop-in#

Quick Start: Drop-in with Sessions Flow#

Drop-in with Advanced Flow#

Configuring Drop-in#

React (non-Next.js)#

Next.js App Router#

Backend: API Route Handlers#

app/api/sessions-setup/route.ts#

app/api/payments/route.ts#

app/api/payments/details/route.ts#

app/api/payment-methods/route.ts#

Handling the Payment Result#

Redirect Flow#

Drop-in

Quick Start: Drop-in with Sessions Flow

Drop-in with Advanced Flow

Configuring Drop-in

React (non-Next.js)

Next.js App Router

Backend: API Route Handlers

`app/api/sessions-setup/route.ts`

`app/api/payments/route.ts`

`app/api/payments/details/route.ts`

`app/api/payment-methods/route.ts`

Handling the Payment Result

Redirect Flow