Checkout Settings

Configure your checkout with the right parameters to create a seamless payment experience. This guide covers all the configurable options for Plexy checkout sessions and payments.

Amount and Currency

Every payment request requires an amount object specifying the value and currency.

Amount Format

Amounts are specified in the smallest currency unit (e.g., cents for USD, tiyn for KZT).

const payment = await plexy.sessions.create({
  amount: {
    value: 10000, // 100.00 KZT
    currency: 'KZT',
  },
  // ...
});

Currency	Minor Units	Example
KZT (Kazakhstani Tenge)	100	1000 = ₸10.00
USD (US Dollar)	100	1000 = $10.00
EUR (Euro)	100	1000 = €10.00

KZT amounts are submitted in tiyn (1/100 of a tenge), so value: 10000 equals exactly ₸100.00.

Supported Currencies

// Get list of supported currencies for your account
const config = await plexy.config.get();
console.log(config.supportedCurrencies);
// ['KZT', 'USD', 'EUR']

# Get list of supported currencies for your account
config = plexy.config.get()
print(config.supported_currencies)
# ['KZT', 'USD', 'EUR']

curl https://api.plexypay.com/v2/config \
  -H "x-api-key: Bearer YOUR_API_KEY"

Common supported currencies:

Code	Currency	Symbol
`KZT`	Kazakhstani Tenge	₸
`USD`	US Dollar	$
`EUR`	Euro	€

Country Codes

The country code affects which payment methods are available and how transactions are processed.

const session = await plexy.sessions.create({
  amount: { value: 10000, currency: 'KZT' },
  countryCode: 'KZ', // ISO 3166-1 alpha-2
  // ...
});

Shopper Information

Providing shopper details improves payment success rates and fraud detection.

Basic Shopper Data

const session = await plexy.sessions.create({
  amount: { value: 10000, currency: 'KZT' },

  // Unique identifier for returning customers (for tokenization)
  shopperReference: 'customer_12345',

  // Contact information
  shopperEmail: 'customer@example.com',
  shopperName: {
    firstName: 'John',
    lastName: 'Smith',
  },

  // Phone number (E.164 format recommended)
  telephoneNumber: '+77001234567',

  // Preferred locale for checkout UI
  shopperLocale: 'en-US',

  // ...
});

Return URLs

Configure where customers are redirected after payment.

const session = await plexy.sessions.create({
  amount: { value: 10000, currency: 'KZT' },

  // Required: Where to redirect after payment attempt
  returnUrl: 'https://your-site.com/checkout/complete',

  // Optional: Override for successful payments
  successUrl: 'https://your-site.com/order/confirmed',

  // Optional: Override for cancelled payments
  cancelUrl: 'https://your-site.com/checkout',

  // ...
});

Return URL Parameters

Plexy appends these query parameters to your return URL:

Parameter	Description
`resultCode`	Payment result (Authorised, Refused, etc.)
`sessionId`	The session ID
`reference`	Your merchant reference
`pspReference`	Plexy's payment reference

Example return URL:

https://your-site.com/checkout/complete?resultCode=Authorised&sessionId=ses_abc123&reference=order_12345&pspReference=8835511210681324

Payment Method Configuration

Control which payment methods are displayed.

const session = await plexy.sessions.create({
  amount: { value: 10000, currency: 'KZT' },

  // Only show specific payment methods
  allowedPaymentMethods: ['scheme', 'applepay'],

  // Or hide specific payment methods
  blockedPaymentMethods: ['applepay'],

  // ...
});

Available Payment Method Types

Type	Description
`scheme`	Credit/Debit cards
`applepay`	Apple Pay
`googlepay`	Google Pay

3D Secure Configuration

Control 3D Secure behavior.

const session = await plexy.sessions.create({
  amount: { value: 10000, currency: 'KZT' },

  authenticationData: {
    // Request 3D Secure exemption (if eligible)
    attemptAuthentication: 'always', // 'always', 'preferNo', 'preferYes'

    // Challenge preference
    challengeIndicator: 'requestChallenge', // 'noPreference', 'requestNoChallenge', 'requestChallenge'
  },

  // ...
});

Checkout Settings

Осы бетте