> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payviox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# createSession()

> SDK method createSession(sessionParameters, options). Takes amount, currency, customer, items, paymentMethodId, order_id. Options: redirect (boolean), iframeMode (boolean), iframeConfig. Returns session ID or void on redirect. Supports direct provider redirect

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

```typescript theme={null}
async createSession(
  sessionParameters: SessionParameters,
  parameters?: PayvioxParameters
): Promise<void | string>
```

## Parameters

<ParamField body="sessionParameters" type="SessionParameters" required>
  Object containing payment session details.

  <Expandable title="SessionParameters properties">
    <ParamField body="amount" type="number" required>
      Payment amount in the smallest currency unit (cents for USD).

      ```javascript theme={null}
      amount: 5000  // $50.00
      ```

      <Note>
        Minimum amount is typically 100 (\$1.00). Check your currency's requirements.
      </Note>
    </ParamField>

    <ParamField body="currency" type="string" required>
      Three-letter ISO currency code.

      ```javascript theme={null}
      currency: 'USD'  // or 'EUR', 'GBP', etc.
      ```
    </ParamField>

    <ParamField body="customer" type="string" required>
      Customer identifier. Can be an email, customer ID, or any unique identifier.

      ```javascript theme={null}
      customer: 'customer_abc123'
      // or
      customer: 'user@example.com'
      ```
    </ParamField>

    <ParamField body="description" type="string" required>
      Human-readable description of the payment.

      ```javascript theme={null}
      description: 'Premium subscription - Monthly'
      ```
    </ParamField>

    <ParamField body="paymentMethodId" type="string">
      Optional. Forces a specific payment method instead of letting the customer choose on the payment page. Use `'stripe_credit'` for card payments.

      ```javascript theme={null}
      paymentMethodId: 'stripe_credit'
      ```

      <Tip>
        Leave it out to show the customer every method available for their country and currency. Use `getPaymentsMethods()` to discover available payment method IDs.
      </Tip>
    </ParamField>

    <ParamField body="order_id" type="string" required>
      Unique identifier for this order. Must be unique across all your transactions.

      ```javascript theme={null}
      order_id: 'order_2024_001'
      // or generate dynamically
      order_id: 'order_' + Date.now()
      ```
    </ParamField>

    <ParamField body="items" type="array" required>
      Array of items being purchased.

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

      <Expandable title="Item properties">
        <ParamField body="name" type="string" required>
          Name or description of the item.
        </ParamField>

        <ParamField body="quantity" type="number" required>
          Quantity being purchased. Must be a positive integer.
        </ParamField>

        <ParamField body="price" type="number" required>
          Unit price in the smallest currency unit (cents).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="parameters" type="PayvioxParameters">
  Optional configuration for integration mode and behavior.

  <Expandable title="PayvioxParameters properties">
    <ParamField body="redirect" type="boolean" default="false">
      If `true`, automatically redirects to the payment page.

      ```javascript theme={null}
      { redirect: true }
      ```

      <Note>
        Cannot be used simultaneously with `iframeMode: true`.
      </Note>
    </ParamField>

    <ParamField body="iframeMode" type="boolean" default="false">
      If `true`, embeds the payment form in an iframe.

      ```javascript theme={null}
      { iframeMode: true }
      ```

      <Warning>
        Requires `iframeConfig` to be set when enabled.
      </Warning>
    </ParamField>

    <ParamField body="iframeConfig" type="object">
      Configuration for iframe mode. Required when `iframeMode` is `true`.

      <Expandable title="IframeConfig properties">
        <ParamField body="iframeTarget" type="HTMLElement" required>
          DOM element where the iframe will be inserted.

          ```javascript theme={null}
          iframeTarget: document.getElementById('payment-container')
          ```
        </ParamField>

        <ParamField body="width" type="string" default="100%">
          Width of the iframe. Any valid CSS width value.

          ```javascript theme={null}
          width: '500px'  // or '100%', '80vw', etc.
          ```
        </ParamField>

        <ParamField body="height" type="string" default="400px">
          Height of the iframe. Any valid CSS height value.

          ```javascript theme={null}
          height: '600px'  // or '100vh', '80%', etc.
          ```
        </ParamField>

        <ParamField body="withoutBorder" type="boolean" default="false">
          Remove iframe border for seamless integration.

          ```javascript theme={null}
          withoutBorder: true
          ```
        </ParamField>

        <ParamField body="transparentBackground" type="boolean" default="false">
          Make iframe background transparent.

          ```javascript theme={null}
          transparentBackground: true
          ```
        </ParamField>

        <ParamField body="style" type="string" default="">
          Additional CSS styles to apply to the iframe.

          ```javascript theme={null}
          style: 'border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);'
          ```
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Return value

<ResponseField name="return" type="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

  ```javascript theme={null}
  // With redirect
  await payviox.createSession(params, { redirect: true });
  // Page redirects immediately

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

## 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.

<Info>
  This feature works automatically when using `redirect: true` or `iframeMode: true` with a redirect-based provider.
</Info>

### How it works

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

### Example with Direct Redirect

```javascript theme={null}
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`)

<Tip>
  If you don't specify a `paymentMethodId`, or use a non-redirect provider, the standard flow applies (redirect to Payviox payment page).
</Tip>

### 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.

```javascript theme={null}
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

<CodeGroup>
  ```javascript Redirect Mode theme={null}
  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
  });
  ```

  ```javascript Iframe Mode theme={null}
  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: ''
    }
  });
  ```

  ```javascript Get Session ID theme={null}
  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);
  ```
</CodeGroup>

## Error handling

```javascript theme={null}
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);
  }
}
```