Skip to main content
POST
Create Session

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.
Recommended flow: call this endpoint from your backend with your secret key (so the amount is computed server-side and you can pass ip), return the session_id to your frontend, and let the SDK’s openSession() take the customer to the payment page. If there’s no browser in your flow, send the customer to https://secure.payviox.com/{session_id} yourself. See Choose your integration method.
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.

Integration Modes

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

Example Requests

Client-side Example (Public API Key)

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

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

Server-side Direct Redirect Example

Redirect-based Providers

The following providers support direct redirect:
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:
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

Error Responses

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

Open the session with the SDK

Recommended: hand the session ID to openSession() in the browser

Redirect without the SDK

Send the customer to https://secure.payviox.com/{session_id} yourself

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

  • Minimum amount: 100 cents ($1.00)
  • Must be a positive integer
  • Total amount must equal the sum of all items (price × quantity)
  • 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
  • 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:
description
string

Optional description of the payment

paymentMethodId
string

Force a specific payment method (optional)

ip
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:

Response

Session created successfully

session_id
string

Unique identifier for the created session