Get Started#
This is the documentation for API v2 and SDK integration. Looking for the
more stable legacy version? See the API v1
documentation.
Pick your server flow#
| Sessions Flow | Advanced Flow |
|---|
| Best for | Fastest path to live payments | Fully branded custom checkout |
| API calls required | One (POST /v2/sessions) | Three+ (/v2/paymentMethods → /v2/payments → /v2/payments/details) |
| Who handles 3DS + redirects | Plexy | You |
| Time to first payment | Minutes | Days |
| Good fit examples | SMB checkout, invoicing, subscription billing | Marketplaces, custom-branded flagship apps, multi-step checkouts |
Not sure which to pick?#
Start with the Sessions Flow — it covers most merchants and gets you to your first live payment fastest. Choose the Advanced Flow when you need a fully branded payment form or custom orchestration that the Sessions Flow can't accommodate.Continue with your flow#
Sessions Flow
Create a session, mount the checkout, handle the result via webhook.
Advanced Flow
Render payment methods, submit payments, handle 3DS yourself.Next steps#
Explore SDK guides for your platform
Browse the API reference for all endpoints
Pick how to render Plexy on the client#
Two ways to mount Plexy in your app.Drop-in is one pre-built component that renders the entire checkout — payment-method selection, forms, and 3DS prompts. Components are individual payment-method pieces (Card, Apple Pay, Google Pay, ...) that you place and style in your own UI. Both work with either the Sessions Flow or the Advanced Flow — this choice is about client-side rendering, not flow. | Drop-in | Components |
|---|
| Best for | Fastest client integration | Composable, custom layouts |
| What you render | One <Dropin /> mount — full checkout | Individual payment-method components you place yourself |
| Payment-method UI ownership | Plexy renders all methods (Card, Apple Pay, Google Pay, ...) | You pick and arrange each method component |
| Bundle size | Larger — includes all registered payment methods | Smaller — tree-shake to only the methods you use |
| Time to integrate | Minutes | Hours |
| Good fit examples | Standard single-page checkout, MVP, quick launch | Multi-step flows, custom layouts, selective payment methods |
Start with Drop-in — it's the fastest way to ship a working checkout. Move to Components when you need custom layout, selective payment methods, or want to minimize bundle size.
Drop-in
Mount one <Dropin /> and let Plexy render the full checkout.
Components
Compose individual payment-method components in your own UI.
Accept Payments#
Sessions Flow
Embedded checkout — server creates a session, client renders the Plexy
component
Advanced Flow
Direct API — your server calls the Payments API, you render the UISessions flow#
Advanced flow#
API Overview#
API Reference#
The Plexy API is a RESTful API that uses JSON for request and response bodies. It powers the merchant-facing endpoints used to create payments, manage checkout sessions, and look up available payment methods.Base URL#
| Environment | URL |
|---|
| Production | https://api.plexypay.com |
Plexy uses this same base URL for both test and live payments. API paths include the /v2 prefix, for example /v2/sessions. Use a test API key for simulated transactions and a live API key for production. Client SDK environments stay live/APSE; the API key determines the payment mode.Authentication#
All API requests must include your API key in the x-api-key header:See Authentication for details on obtaining and rotating keys.Use Content-Type: application/json for all requests
All timestamps are in ISO 8601 format
Amounts are specified in the smallest currency unit (e.g., 5000 = 50.00 KZT). See Currency Codes.
2xx status code with a JSON body. Example response from POST /v2/payments:{
"pspReference": "BNV58BSJF9WQ5K65",
"resultCode": "Authorised",
"amount": { "currency": "KZT", "value": 10000 },
"merchantReference": "order-1729012345",
"paymentMethod": { "type": "scheme", "brand": "visa" }
}
resultCode field tells you the outcome of the payment. See HTTP Status Codes and Refusal Reasons for the full list of values.Error responses return a 4xx or 5xx status code with an error body:{
"error": {
"code": "invalid_request",
"message": "Amount must be greater than 0",
"param": "amount"
}
}
Webhooks#
Plexy sends webhook events for important state changes. See the webhooks guide for setup instructions.API endpoints#
The merchant API exposes five operations grouped by resource:Payment Methods#
| Method | Endpoint | Description |
|---|
| POST | /v2/paymentMethods | Get a list of available payment methods |
Payments#
| Method | Endpoint | Description |
|---|
| POST | /v2/payments | Start a transaction |
| POST | /v2/payments/details | Submit details for a payment |
Sessions#
| Method | Endpoint | Description |
|---|
| POST | /v2/sessions | Create a payment session |
| GET | /v2/sessions/{sessionId} | Get the result of a payment session |
