Web Drop-in

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 /v2/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.

Shopper locale

locale is the checkout interface language and regional formatting, for example ru-KZ, en-US, or kk-KZ. Do not use it as a currency field. Currency belongs only in amount.currency, for example KZT.

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 /v2/payments and /v2/payments/details call from your backend.

Your backend provides paymentMethodsResponse by calling POST /v2/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.

Hide Cardholder Name Field

Use the card payment-method configuration:

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:

Use a test CHECKOUT_API_KEY to run test transactions and a live APSE CHECKOUT_API_KEY for production. The browser SDK environment remains live-apse in both cases.

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.

Use CHECKOUT_API_KEY and NEXT_PUBLIC_CLIENT_KEY values from the same merchant account and mode. For test transactions, use the test API key; for production, use the live APSE API key. Do not send live-apse in the /v2/sessions request body; APSE is selected by the client SDK through environment: 'live-apse'.

`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 /v2/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 /v2/sessions or POST /v2/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 /v2/sessions or /v2/payments request to https://yoursite.com/redirect.

Drop-in#

Quick Start: Drop-in with Sessions Flow#

Drop-in with Advanced Flow#

Configuring Drop-in#

Hide Cardholder Name Field#

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

Hide Cardholder Name Field

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