Advanced Flow

The Advanced flow gives you complete control over the payment experience. You build your own payment form, collect payment details, and handle the full payment lifecycle through three API calls.

Info

The Advanced flow requires more development effort but provides maximum
flexibility. If you're just getting started, consider the Sessions
flow first.

How Advanced Flow Works

Get Available Payment Methods

Call /v2/paymentMethods to get payment methods available for your shopper.

Collect Payment Details

Render payment inputs in your own UI and collect the required payment data.

Make a Payment

Submit the payment details to /v2/payments to initiate the payment.

Handle Additional Actions

If required, handle 3D Secure or redirects by calling
/v2/payments/details.

Step 1: Get Payment Methods

First, request available payment methods for the transaction. The response depends on your account configuration, the shopper's country, and the payment amount.

Shopper locale

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

Response:

{
  "paymentMethods": [
    {
      "type": "scheme",
      "name": "Credit Card",
      "brands": ["visa", "mc", "amex"]
    },
    {
      "type": "applepay",
      "name": "Apple Pay",
      "configuration": {
        "merchantId": "merchant.com.plexy.example",
        "merchantName": "Your Store"
      }
    }
  ]
}

Step 2: Collect Payment Details

Build your payment form to collect the required data. For card payments, you must use client-side encryption to protect sensitive card data.

Card Encryption (Client-Side)

Warning

Never send raw card numbers to your server. Always encrypt card data
client-side using the Plexy encryption library.

Secure Input Fields (Recommended)

For easier PCI compliance, use Plexy's secure input fields:

Step 3: Make a Payment

Submit the payment to the /v2/payments endpoint from your server.

Response (Successful):

{
  "resultCode": "Authorised",
  "pspReference": "8835511210681324",
  "merchantReference": "order_12345"
}

Response (3D Secure Required):

{
  "resultCode": "IdentifyShopper",
  "action": {
    "type": "threeDS2",
    "subtype": "fingerprint",
    "token": "eyJ0aHJlZURTTWV0aG9kTm90...",
    "paymentMethodType": "scheme"
  }
}

Step 4: Handle Additional Actions

If the payment requires additional action (3D Secure, redirect), handle it client-side and submit the result.

Handling 3D Secure

Handling Redirects

For payment methods that require a redirect (e.g., bank transfers):

Server-Side: Submit Additional Details

Response:

{
  "resultCode": "Authorised",
  "pspReference": "8835511210681324",
  "merchantReference": "order_12345"
}

Complete Integration Example

Here's a complete server-side example combining all the steps. Your server proxies each client request to the corresponding Plexy API endpoint:

Step 1 — Get payment methods:

Step 3 — Make a payment:

Step 4 — Submit additional details:

Alternative Payment Methods

Different payment methods require different data. Here are examples for common methods:

Apple Pay

Google Pay

Error Handling

Implement robust error handling for production. The Plexy API returns standard HTTP error responses — check the HTTP status code and the errorCode field in the response body:

400 — Invalid request data (missing or malformed fields)

401 — Invalid or missing API key

422 — Request was valid but could not be processed (e.g., amount too low)

500 — Server-side error; retry with exponential back-off

Map these to appropriate messages in your application and always log the full response body for debugging.

Next Steps

Understand result codes to handle all payment outcomes

Implement 3D Secure for card authentication

Set up webhooks for asynchronous notifications

Configure checkout settings in the Dashboard

Advanced Flow

How Advanced Flow Works#

Step 1: Get Payment Methods#

Step 2: Collect Payment Details#

Card Encryption (Client-Side)#

Secure Input Fields (Recommended)#

Step 3: Make a Payment#

Step 4: Handle Additional Actions#

Handling 3D Secure#

Handling Redirects#

Server-Side: Submit Additional Details#

Complete Integration Example#

Alternative Payment Methods#

Apple Pay#

Google Pay#

Error Handling#

Next Steps#

How Advanced Flow Works

Step 1: Get Payment Methods

Step 2: Collect Payment Details

Card Encryption (Client-Side)

Secure Input Fields (Recommended)

Step 3: Make a Payment

Step 4: Handle Additional Actions

Handling 3D Secure

Handling Redirects

Server-Side: Submit Additional Details

Complete Integration Example

Alternative Payment Methods

Apple Pay

Google Pay

Error Handling

Next Steps