Create Session - Payviox Documentation

Create Session

curl --request POST \
  --url https://api.payviox.com/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 101,
  "currency": "<string>",
  "customer": "<string>",
  "order_id": "<string>",
  "items": [
    {
      "name": "Premium Plan",
      "quantity": 1,
      "price": 10000
    }
  ],
  "description": "<string>",
  "paymentMethodId": "<string>",
  "ip": "<string>",
  "metadata": {
    "user_id": "usr_123",
    "campaign": "summer_sale"
  }
}
'

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

POST

session

Create Session

curl --request POST \
  --url https://api.payviox.com/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 101,
  "currency": "<string>",
  "customer": "<string>",
  "order_id": "<string>",
  "items": [
    {
      "name": "Premium Plan",
      "quantity": 1,
      "price": 10000
    }
  ],
  "description": "<string>",
  "paymentMethodId": "<string>",
  "ip": "<string>",
  "metadata": {
    "user_id": "usr_123",
    "campaign": "summer_sale"
  }
}
'

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Overview

Creates a new payment session for your customer. The session ID can be used to redirect the customer to the payment page or to fetch available payment methods.

Payment sessions expire after 24 hours if no payment is initiated.

Authentication

This endpoint accepts both Public API Key (client-side) and Secret API Key (server-side). See Authentication for details.

Authorization: Bearer YOUR_API_KEY

Integration Modes

Client-side (SDK)
Server-side (API)

Use your Public API Key when creating sessions from the browser via the JavaScript SDK.

Client IP is automatically captured from the request
No need to provide the ip parameter
Ideal for: websites, single-page applications

const payviox = new Payviox('pk_live_xxxxxxxxxxxx');
await payviox.createSession({ ... });

Use your Secret API Key when creating sessions from your backend server.

You can optionally provide the client’s IP address via the ip parameter
If ip is provided, it will be validated when the user completes payment
If ip is not provided, no IP validation will occur
Ideal for: backend APIs, mobile app backends, server integrations

curl https://api.payviox.com/session \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -d '{ "ip": "203.0.113.42", ... }'

When you provide an ip parameter, the payment page will verify that the user’s IP matches. If there’s a mismatch, the payment will be rejected with a 403 IP mismatch error.

Example Requests

Client-side Example (Public API Key)

curl https://api.payviox.com/session \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "customer": "customer_abc123",
    "order_id": "order_12345",
    "description": "Premium subscription",
    "metadata": {"user_id": "usr_123", "plan": "premium"},
    "items": [
      {
        "name": "Premium Plan",
        "quantity": 1,
        "price": 10000
      }
    ]
  }'

Server-side Example (Secret API Key with IP)

When creating sessions from your backend, you can provide the client’s IP address for fraud prevention:

curl https://api.payviox.com/session \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "customer": "customer_abc123",
    "order_id": "order_12345",
    "description": "Premium subscription",
    "ip": "203.0.113.42",
    "metadata": {"user_id": "usr_123", "plan": "premium"},
    "items": [
      {
        "name": "Premium Plan",
        "quantity": 1,
        "price": 10000
      }
    ]
  }'

Without IP parameter: If you don’t provide the ip parameter in server-side requests, no IP validation will be performed at payment time. This is useful when you can’t reliably determine the client’s IP.

Direct Redirect (Skip Payment Page)

When you specify a paymentMethodId for a redirect-based payment provider (like Zen, Nicepay, PayPal, etc.), the API will automatically initiate the payment and return a redirect_url in the response. This allows you to bypass the Payviox payment page entirely and redirect the customer directly to the payment provider.

This feature is only available for redirect-based providers. For other providers (like Stripe Elements), the standard flow applies.

How it works

Create a session with a paymentMethodId for a redirect-based provider
The API creates the session and initiates the payment
You receive both session_id and redirect_url in the response
Redirect your customer directly to the redirect_url

Server-side Direct Redirect Example

app.post('/checkout', async (req, res) => {
  const clientIp = req.headers['x-forwarded-for'] || req.ip;
  
  const response = await fetch('https://api.payviox.com/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 10000,
      currency: 'USD',
      customer: req.body.customer,
      order_id: 'order_' + Date.now(),
      description: 'Premium subscription',
      paymentMethodId: 'zen_card', // Redirect-based provider
      ip: clientIp,
      items: req.body.items
    })
  });
  
  const data = await response.json();
  
  // If redirect_url is present, redirect directly to provider
  if (data.redirect_url) {
    return res.redirect(data.redirect_url);
  }
  
  // Otherwise, redirect to Payviox payment page
  res.redirect(`https://secure.payviox.com/${data.session_id}`);
});

Redirect-based Providers

The following providers support direct redirect:

Provider	Payment Methods
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`

Use the Get Payment Methods endpoint to discover which payment methods are available for your account.

Handling Payment Errors

If the payment initiation fails (e.g., provider API error), the response will include payment_error along with the session_id. You can then fall back to the standard flow:

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "payment_error": {
    "success": false,
    "message": "Payment creation failed",
    "error_type": "http_error"
  }
}

When payment_error is present, the session is still created. You can redirect the customer to https://secure.payviox.com/{session_id} to let them try another payment method.

Example Response

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Error Responses

400 — Validation Error

Returned when request body fields are missing or invalid. The response contains an object where each key is a field name and the value is an array of error messages.Common causes:

Required fields missing (amount, currency, customer, order_id, items)
Amount does not match the sum of item prices
Invalid item structure (missing name, quantity, or price)

{
  "amount": ["The amount field is required."],
  "currency": ["The currency field is required."]
}

400 — Payment Method Not Found

Returned when the paymentMethodId parameter references a payment method that does not exist or is not enabled for your business.How to resolve: Use the Get Payment Methods endpoint to list available methods.

{
  "error": "Payment method not found"
}

401 — Unauthorized

Returned when the API key is missing or invalid.How to resolve: Ensure you are sending a valid API key in the Authorization: Bearer header.

{
  "error": "Unauthorized"
}

429 — Rate Limit Exceeded

Returned when too many requests are sent in a short period of time, either per customer or per IP address.The response includes a retry_after field (in seconds) and a Retry-After HTTP header indicating when you can retry.How to resolve: Wait for the duration indicated by retry_after before retrying. Implement exponential backoff in your integration.

{
  "error": "rate_limit_exceeded",
  "message": "Too many session requests",
  "type": "ip",
  "retry_after": 60
}

The IP mismatch error (403) occurs at payment time, not during session creation. If you provided an ip parameter when creating the session, the payment page will verify that the user’s IP matches. This is a fraud prevention measure.

Next Steps

After creating a session:

Redirect Customer

Redirect the customer to the payment page using the session ID

Get Payment Methods

Fetch available payment methods for the session

Dashboard

Monitor your payments in real-time

API Playground

Test API calls directly from your browser

Validation Rules

Amount Validation

Minimum amount: 100 cents ($1.00)
Must be a positive integer
Total amount must equal the sum of all items (price × quantity)

Items Validation

At least one item is required
Each item must have a name, quantity, and price
Quantity must be at least 1
Price must be at least 1 cent

Order ID

Must be unique per business
Used for tracking and webhooks
Recommended to use your internal order/transaction ID

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

amount

integer

required

Payment amount in cents (e.g., 10000 = $100.00)

Required range: x >= 100

currency

string

required

Three-letter ISO currency code (e.g., USD)

Maximum string length: 3

customer

string

required

Customer identifier (email, customer ID, or unique identifier)

order_id

string

required

Your unique order identifier

items

object[]

required

Array of items being purchased

Example:

[
  {
    "name": "Premium Plan",
    "quantity": 1,
    "price": 10000
  }
]

description

string

Optional description of the payment

paymentMethodId

string

Force a specific payment method (optional)

string

Server-side only. The end-user's IP address

metadata

object

Custom key-value pairs to attach to this session. These will be returned in webhook notifications.

Example:

{
  "user_id": "usr_123",
  "campaign": "summer_sale"
}

Response

Session created successfully

session_id

string

Unique identifier for the created session

Authentication Get Payment Methods

​Overview

​Authentication

​Integration Modes

​Example Requests

​Client-side Example (Public API Key)

​Server-side Example (Secret API Key with IP)

​Direct Redirect (Skip Payment Page)

​How it works

​Server-side Direct Redirect Example

​Redirect-based Providers

​Handling Payment Errors

​Example Response

​Error Responses

​Next Steps

Redirect Customer

Get Payment Methods

Dashboard

API Playground

​Validation Rules

Authorizations

Body

Response

Overview

Authentication

Integration Modes

Example Requests

Client-side Example (Public API Key)

Server-side Example (Secret API Key with IP)

Direct Redirect (Skip Payment Page)

How it works

Server-side Direct Redirect Example

Redirect-based Providers

Handling Payment Errors

Example Response

Error Responses

Next Steps

Validation Rules