Sessions Flow

The Sessions flow is the fastest way to start accepting payments. With a single API call to create a session, Plexy handles payment method rendering, 3D Secure authentication, redirects, and result processing.

How Sessions Work

Create a Session

Your server makes a single API call to /v2/sessions with payment details.

Initialize Checkout

Use the session ID to mount the Plexy checkout component on your page.

Customer Completes Payment

The customer enters their payment details in the embedded UI. Plexy handles
all payment method logic, 3D Secure challenges, and redirects.

Handle the Result

Receive the payment result via webhooks and update your order status.

Server-Side: Create a Session

Create a payment session by calling the /v2/sessions endpoint with the payment amount, currency, and return URL.

APSE region

For production, use a live APSE x-api-key for /v2/sessions. For test transactions, use the test API key from the same merchant account and keep the client SDK environment live/APSE. Do not add live-apse to the request body; the APSE region is selected in the client SDK configuration. The SDK clientKey must belong to the same merchant account and mode as the backend x-api-key.

Response:

{
  "id": "ses_abc123xyz",
  "sessionData": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-12-31T23:59:59Z",
  "status": "active",
  "amount": {
    "value": 10000,
    "currency": "KZT"
  },
  "reference": "order_12345"
}

Client-Side: Mount the Checkout

After creating a session, use the session data to initialize the Plexy checkout component on your frontend.

JavaScript

React

HTML

Customizing the Checkout Appearance

You can customize the checkout appearance using style options:

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.

Webhook Integration

Warning

Always verify payment status via webhooks. Do not rely solely on client-side
callbacks, as they can be manipulated.

See the Webhooks documentation for full setup, signature verification, and event reference.

Handling the Return URL

When the customer completes the payment, they are redirected to your returnUrl. The URL includes query parameters with the payment result.

Info

The resultCode in the return URL is for display purposes only. Always verify
the payment status via webhooks or by calling the API from your server.

Session States

State	Description
`active`	Session is valid and ready for payment
`completed`	Payment was successfully processed
`expired`	Session has passed its `expiresAt` time
`cancelled`	Customer cancelled the payment

Error Handling

Handle errors gracefully in your checkout implementation:

Next Steps

Configure checkout settings for your account

Understand result codes to handle all payment outcomes

Set up webhooks for production

Sessions Flow

How Sessions Work#

Server-Side: Create a Session#

Client-Side: Mount the Checkout#

Customizing the Checkout Appearance#

Webhook Integration#

Handling the Return URL#

Session States#

Error Handling#

Next Steps#