Redirect integration

Overview

Redirect mode redirects your customers to a Payviox-hosted payment page where they complete their payment. This is the simplest and most secure integration method.

Redirect mode is recommended for:

Quick integrations
Maximum PCI compliance
When you don’t need custom payment UI

How it works

Create payment session

Your application creates a payment session with customer and order details.

Redirect to Payviox

Customer is redirected to the secure Payviox payment page using the session ID.

Customer completes payment

Customer enters their payment information on the Payviox-hosted page.

Return to your site

After payment, customer is redirected back to your specified URL with the payment result.

Implementation

Example with automatic redirect

payment.js

const payviox = new Payviox('your_api_token');

async function processPayment() {
  try {
    // Create session with automatic redirect
    await payviox.createSession({
      amount: 5000, // 50.00 USD in cents
      currency: 'USD',
      customer: 'customer_abc123',
      description: 'Monthly subscription',
      paymentMethodId: 'stripe_credit',
      order_id: 'order_2024_001',
      items: [
        {
          name: 'Pro Plan - Monthly',
          quantity: 1,
          price: 5000
        }
      ]
    }, {
      redirect: true // Enable automatic redirect
    });
    
    // The following code will not execute as the user is redirected
  } catch (error) {
    console.error('Payment error:', error);
    // Handle error before redirect
  }
}

Session parameters

The createSession() method accepts two parameter objects:

Payment session details (SessionParameters)

Parameter	Type	Required	Description
`amount`	`number`	✅ Required	Payment amount in the smallest currency unit (cents for USD). Example: `5000` = $50.00. Minimum is typically 100 ($ 1.00).
`currency`	`string`	✅ Required	Three-letter ISO currency code. Example: `'USD'`, `'EUR'`, `'GBP'`
`customer`	`string`	✅ Required	Customer identifier. Can be an email, customer ID, or any unique identifier. Example: `'customer_abc123'` or `'user@example.com'`
`description`	`string`	✅ Required	Human-readable description of the payment. Example: `'Premium subscription - Monthly'`
`paymentMethodId`	`string`	Optional	Forces a specific payment method. Use `'stripe_credit'` for card payments, or omit it to let the customer choose on the payment page. Get available methods with `getPaymentsMethods()`.
`order_id`	`string`	✅ Required	Unique identifier for this order. Must be unique across all your transactions. Example: `'order_2024_001'` or `'order_' + Date.now()`
`items`	`array`	✅ Required	Array of items being purchased. Each item must contain: `name` (string), `quantity` (number), `price` (number in cents).

Integration options (PayvioxParameters)

Parameter	Type	Required	Default	Description
`redirect`	`boolean`	⚪ Optional	`false`	If `true`, automatically redirects to the payment page. Cannot be used with `iframeMode: true`.
`iframeMode`	`boolean`	⚪ Optional	`false`	If `true`, embeds the payment form in an iframe. Requires `iframeConfig` to be set. Cannot be used with `redirect: true`.
`iframeConfig`	`object`	⚪ Optional	-	Configuration for iframe mode. Required when `iframeMode` is `true`. See iframe integration documentation for details.

Item object structure

Each item in the items array must have:

Property	Type	Required	Description
`name`	`string`	✅ Required	Name or description of the item
`quantity`	`number`	✅ Required	Quantity being purchased. Must be a positive integer.
`price`	`number`	✅ Required	Unit price in the smallest currency unit (cents).

Return value

The createSession() method returns a Promise that resolves to:

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

// With redirect - returns void (page redirects immediately)
await payviox.createSession(params, { redirect: true });

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

Best practices

Validate payment parameters

Always validate payment parameters on your server before creating sessions:

// Client-side: Basic validation
if (amount < 100) {
  throw new Error('Minimum amount is $1.00');
}

// Server-side: Complete validation and session creation
// (Recommended for security)

Handle network errors gracefully

Implement retry logic for transient failures:

async function createSessionWithRetry(params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await payviox.createSession(params, { redirect: true });
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Next steps

Iframe integration

Embed payments in your page

Error handling

Handle errors gracefully

Testing

Test your integration

SDK - Getting Started

SDK - Integration

SDK - API Reference

Overview

How it works

Implementation

Example with automatic redirect

Session parameters

Payment session details (SessionParameters)

Integration options (PayvioxParameters)

Item object structure

Return value

Best practices

Next steps

Iframe integration

Error handling

Testing

​Overview

​How it works

​Implementation

​Example with automatic redirect

​Session parameters

​Payment session details (SessionParameters)

​Integration options (PayvioxParameters)

​Item object structure

​Return value

​Best practices

​Next steps

Iframe integration

Error handling

Testing

Overview

How it works

Implementation

Example with automatic redirect

Session parameters

Payment session details (SessionParameters)

Integration options (PayvioxParameters)

Item object structure

Return value

Best practices

Next steps