Creates a new payment session and optionally redirects or embeds an iframe.
async createSession ( sessionParameters : SessionParameters , parameters ?: PayvioxParameters ): Promise < void | string >
Parameters sessionParameters
SessionParameters
required
Object containing payment session details. Show SessionParameters properties
Payment amount in the smallest currency unit (cents for USD). Minimum amount is typically 100 ($1.00). Check your currency’s requirements.
Three-letter ISO currency code. currency : 'USD' // or 'EUR', 'GBP', etc.
Customer identifier. Can be an email, customer ID, or any unique identifier. Human-readable description of the payment. description : 'Premium subscription - Monthly'
Payment method identifier. Use 'pm_card' for card payments. paymentMethodId : 'pm_card'
Use getPaymentsMethods() to discover available payment method IDs.
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 of items being purchased. items : [ { name: 'Product A' , quantity: 2 , price: 2500 // Prix unitaire en centimes }, { name: 'Product B' , quantity: 1 , price: 5000 } ]
Name or description of the item.
Quantity being purchased. Must be a positive integer.
Unit price in the smallest currency unit (cents).
Optional configuration for integration mode and behavior. Show PayvioxParameters properties
If true, automatically redirects to the payment page. Cannot be used simultaneously with iframeMode: true.
If true, embeds the payment form in an iframe. Requires iframeConfig to be set when enabled.
Configuration for iframe mode. Required when iframeMode is true. Show IframeConfig properties
DOM element where the iframe will be inserted. iframeTarget : document . getElementById ( 'payment-container' )
Width of the iframe. Any valid CSS width value. width : '500px' // or '100%', '80vw', etc.
Height of the iframe. Any valid CSS height value. height : '600px' // or '100vh', '80%', etc.
Remove iframe border for seamless integration. Make iframe background transparent. transparentBackground : true
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 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: '[email protected] ' , 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: '[email protected] ' , 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 Redirect Mode
Iframe Mode
Get Session ID
const payviox = new Payviox ( 'your_api_token' ); await payviox . createSession ({ amount: 5000 , currency: 'USD' , customer: '[email protected] ' , description: 'Premium Plan' , paymentMethodId: 'pm_card' , order_id: 'order_' + Date . now (), items: [ { name: 'Premium Plan' , quantity: 1 , price: 5000 } ] }, { redirect: true });
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 ); } }
