Skip to main content

​
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

1

Create payment session

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

Redirect to Payviox

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

Customer completes payment

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

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: 'pm_card',
      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)

ParameterTypeRequiredDescription
amountnumber✅ RequiredPayment amount in the smallest currency unit (cents for USD). Example: 5000 = 50.00.Minimumistypically100(50.00. Minimum is typically 100 (1.00).
currencystring✅ RequiredThree-letter ISO currency code. Example: 'USD', 'EUR', 'GBP'
customerstring✅ RequiredCustomer identifier. Can be an email, customer ID, or any unique identifier. Example: 'customer_abc123' or 'user@example.com'
descriptionstring✅ RequiredHuman-readable description of the payment. Example: 'Premium subscription - Monthly'
paymentMethodIdstring✅ RequiredPayment method identifier. Use 'pm_card' for card payments. Get available methods with getPaymentsMethods().
order_idstring✅ RequiredUnique identifier for this order. Must be unique across all your transactions. Example: 'order_2024_001' or 'order_' + Date.now()
itemsarray✅ RequiredArray of items being purchased. Each item must contain: name (string), quantity (number), price (number in cents).

​
Integration options (PayvioxParameters)

ParameterTypeRequiredDefaultDescription
redirectboolean⚪ OptionalfalseIf true, automatically redirects to the payment page. Cannot be used with iframeMode: true.
iframeModeboolean⚪ OptionalfalseIf true, embeds the payment form in an iframe. Requires iframeConfig to be set. Cannot be used with redirect: true.
iframeConfigobject⚪ 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:
PropertyTypeRequiredDescription
namestring✅ RequiredName or description of the item
quantitynumber✅ RequiredQuantity being purchased. Must be a positive integer.
pricenumber✅ RequiredUnit 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

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)
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