createSession()

Creates a new payment session and optionally redirects or embeds an iframe.

Subscriptions can’t be created with createSession(). The SDK uses your public key, and a session with a subscription object requires your secret key: the call fails with An error occured (subscription_requires_secret_key). Create subscription sessions on your server with POST /session, then open them with openSession(). See the Subscriptions guide.

async createSession(
  sessionParameters: SessionParameters,
  parameters?: PayvioxParameters
): Promise<void | string>

Parameters

SessionParameters

required

Object containing payment session details.

Show SessionParameters properties

number

required

Payment amount in the smallest currency unit (cents for USD).

amount: 5000  // $50.00

Minimum amount is typically 100 ($1.00). Check your currency’s requirements.

string

required

Three-letter ISO currency code.

currency: 'USD'  // or 'EUR', 'GBP', etc.

string

required

Customer identifier. Can be an email, customer ID, or any unique identifier.

customer: 'customer_abc123'
// or
customer: 'user@example.com'

string

required

Human-readable description of the payment.

description: 'Premium subscription - Monthly'

string

Optional. Forces a specific payment method instead of letting the customer choose on the payment page. Use 'stripe_credit' for card payments.

paymentMethodId: 'stripe_credit'

Leave it out to show the customer every method available for their country and currency. Use getPaymentsMethods() to discover available payment method IDs.

string

required

Unique identifier for this order. Must be unique across all your transactions.

order_id: 'order_2024_001'
// or generate dynamically
order_id: 'order_' + Date.now()

array

required

Array of items being purchased.

items: [
  {
    name: 'Product A',
    quantity: 2,
    price: 2500  // Prix unitaire en centimes
  },
  {
    name: 'Product B',
    quantity: 1,
    price: 5000
  }
]

Show Item properties

string

required

Name or description of the item.

number

required

Quantity being purchased. Must be a positive integer.

number

required

Unit price in the smallest currency unit (cents).

PayvioxParameters

Optional configuration for integration mode and behavior.

Show PayvioxParameters properties

boolean

default:"false"

If true, automatically redirects to the payment page.

{ redirect: true }

Cannot be used simultaneously with iframeMode: true.

boolean

default:"false"

If true, embeds the payment form in an iframe.

{ iframeMode: true }

Requires iframeConfig to be set when enabled.

object

Configuration for iframe mode. Required when iframeMode is true.

Show IframeConfig properties

HTMLElement

required

DOM element where the iframe will be inserted.

iframeTarget: document.getElementById('payment-container')

string

default:"100%"

Width of the iframe. Any valid CSS width value.

width: '500px'  // or '100%', '80vw', etc.

string

default:"400px"

Height of the iframe. Any valid CSS height value.

height: '600px'  // or '100vh', '80%', etc.

boolean

default:"false"

Remove iframe border for seamless integration.

withoutBorder: true

boolean

default:"false"

Make iframe background transparent.

transparentBackground: true

string

default:""

Additional CSS styles to apply to the iframe.

style: 'border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);'

Return value

Promise<void | string>

Returns a Promise that resolves to:

void when using redirect: true (page redirects before returning)
string (session ID) in all other cases

// With redirect
await payviox.createSession(params, { redirect: true });
// Page redirects immediately

// Without redirect
const sessionId = await payviox.createSession(params);
console.log('Session ID:', sessionId);

Direct Redirect (Skip Payment Page)

When you specify a paymentMethodId for a redirect-based payment provider (like Zen, Nicepay, PayPal, etc.), the SDK will automatically redirect the customer directly to the payment provider, bypassing the Payviox payment page entirely.

This feature works automatically when using redirect: true or iframeMode: true with a redirect-based provider.

How it works

You call createSession() with a paymentMethodId for a redirect-based provider
The API creates the session and initiates the payment in one call
The SDK receives a redirect_url in the response
The customer is redirected directly to the provider’s payment page

Example with Direct Redirect

const payviox = new Payviox('your_api_token');

// This will redirect DIRECTLY to Zen's payment page (not Payviox)
await payviox.createSession({
  amount: 5000,
  currency: 'USD',
  customer: 'user@example.com',
  description: 'Premium Plan',
  paymentMethodId: 'zen_card', // Redirect-based provider
  order_id: 'order_' + Date.now(),
  items: [
    { name: 'Premium Plan', quantity: 1, price: 5000 }
  ]
}, {
  redirect: true  // Will redirect to provider directly
});

Supported Providers

Direct redirect works with these providers:

Zen (zen_card, zen_blik, etc.)
Nicepay (nicepay_va, nicepay_ewallet, etc.)
PayPal (paypal)
Payssion (various local payment methods)
Pallapay (crypto payments)
Crypto.com (cryptocom)

If you don’t specify a paymentMethodId, or use a non-redirect provider, the standard flow applies (redirect to Payviox payment page).

Handling Errors

If the payment initiation fails, the SDK will fall back to the standard Payviox payment page where the customer can try again or choose another payment method.

try {
  const sessionId = await payviox.createSession({
    amount: 5000,
    currency: 'USD',
    customer: 'user@example.com',
    description: 'Premium Plan',
    paymentMethodId: 'zen_card',
    order_id: 'order_' + Date.now(),
    items: [{ name: 'Premium Plan', quantity: 1, price: 5000 }]
  }, { redirect: true });
  
  // If redirect didn't happen, you have the session_id
  console.log('Session ID:', sessionId);
} catch (error) {
  console.error('Error:', error.message);
}

Examples

const payviox = new Payviox('your_api_token');

await payviox.createSession({
  amount: 5000,
  currency: 'USD',
  customer: 'user@example.com',
  description: 'Premium Plan',
  paymentMethodId: 'stripe_credit',
  order_id: 'order_' + Date.now(),
  items: [
    { name: 'Premium Plan', quantity: 1, price: 5000 }
  ]
}, {
  redirect: true
});

const payviox = new Payviox('your_api_token');

const sessionId = await payviox.createSession({
  amount: 5000,
  currency: 'USD',
  customer: 'user@example.com',
  description: 'Premium Plan',
  paymentMethodId: 'stripe_credit',
  order_id: 'order_' + Date.now(),
  items: [
    { name: 'Premium Plan', quantity: 1, price: 5000 }
  ]
}, {
  iframeMode: true,
  iframeConfig: {
    iframeTarget: document.getElementById('payment-frame'),
    width: '100%',
    height: '600px',
    withoutBorder: true,
    transparentBackground: false,
    style: ''
  }
});

const payviox = new Payviox('your_api_token');

// Create session without automatic redirect
const sessionId = await payviox.createSession({
  amount: 5000,
  currency: 'USD',
  customer: 'user@example.com',
  description: 'Premium Plan',
  paymentMethodId: 'stripe_credit',
  order_id: 'order_' + Date.now(),
  items: [
    { name: 'Premium Plan', quantity: 1, price: 5000 }
  ]
});

// Perform additional actions
console.log('Session created:', sessionId);

// Redirect manually when ready
payviox.openSession(sessionId);

Error handling

try {
  const sessionId = await payviox.createSession(sessionParams);
  console.log('Success:', sessionId);
} catch (error) {
  if (error.message.includes('Unauthorized')) {
    console.error('Invalid API token');
  } else if (error.message.includes('Bad request')) {
    console.error('Invalid parameters:', error.message);
  } else {
    console.error('Payment error:', error.message);
  }
}

SDK - Getting Started

SDK - Integration

SDK - API Reference

Parameters

Return value

Direct Redirect (Skip Payment Page)

How it works

Example with Direct Redirect

Supported Providers

Handling Errors

Examples

Error handling

​Parameters

​Return value

​Direct Redirect (Skip Payment Page)

​How it works

​Example with Direct Redirect

​Supported Providers

​Handling Errors

​Examples

​Error handling

Parameters

Return value

Direct Redirect (Skip Payment Page)

How it works

Example with Direct Redirect

Supported Providers

Handling Errors

Examples

Error handling