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 the checkout_url returned in the response 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
  • Not available for subscriptions, which require the Secret API Key
  • 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.

Customer email

If you already know your customer’s email, pass it as email. The payment page then does not ask the customer for it: Payviox uses it as the receipt email and on the Stripe Customer, and sends it to fraud screening when the payment method doesn’t carry one.
email must be a valid email address, otherwise the request is rejected with a 400. It is optional: without it, the payment page asks the customer for their email on card, Apple Pay, Google Pay and the other Stripe methods.customer is your own identifier and is never read as an email, even when it looks like one: pass the address in email.

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 the checkout_url from the response to let them try another payment method.

Subscriptions

Add a subscription object to turn the session into a subscription signup: the customer pays the first period on the payment page, then the subscription renews automatically every period. amount and items describe your price for one period; the customer is charged it plus the fees your account adds for the customer, as for a one-time payment (the renewal price is the subscription’s unit_amount). See the Subscriptions guide for the end-to-end flow (Stripe setup, webhooks, cancellation).
Subscription sessions require your Secret API Key. With a public key the request fails with 403 subscription_requires_secret_key, so the SDK’s createSession() can’t create one: create the session on your server, then open it in the browser with openSession().
object
Optional. Makes this session a subscription signup. Omit it (or send null) for a one-time payment.
Requirements
  • Secret API Key (sk_).
  • Stripe connected in your Payviox dashboard, with card (stripe_credit), Apple Pay (stripe_apple_pay) or Google Pay (stripe_google_pay) active. Only these methods are offered on the payment page of a subscription session; if you pass paymentMethodId, it must be one of them.
  • Renewal events enabled on your Stripe webhook endpoint https://api.payviox.com/payment/stripe/webhook: invoice.paid, invoice.payment_failed, invoice.payment_action_required, customer.subscription.updated, customer.subscription.deleted. See Stripe setup.
  • Amounts in USD cents, minimum 100 ($1.00) per period.
The response is the usual { "session_id": "...", "checkout_url": "..." } (201). The subscription itself (psub_...) only exists once the first payment succeeds: you receive it in the subscription block of the succeeded webhook.

Example Response

Every successful response (201) carries checkout_url, the payment page for this session. It points to https://secure.payviox.com/{session_id}, or to your own subdomain once a custom checkout domain is active. Send the customer to this URL rather than building it yourself: connecting or removing a custom domain then needs no change on your side. The URL is set when the session is created and is present in every 201 response, including those with redirect_url or payment_error: only sessions created after the domain becomes Active (or after you remove it) use the new address.

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 subscription object can’t be accepted. The message says what to fix.Invalid terms — unknown interval, or interval_count not an integer or above the 3-year limit:
No subscription-capable method — card, Apple Pay and Google Pay (Stripe) are all inactive on your account:
Stripe not configured — a subscription-capable method is active but your Stripe publishable or secret key is missing:
Incompatible paymentMethodId — the forced method can’t carry a subscription:
subscription_setup_incomplete — your Stripe webhook endpoint https://api.payviox.com/payment/stripe/webhook is missing (all events are then listed) or lacks events needed to track renewals. Add the events listed in missing_events in your Stripe dashboard (how). Payviox caches this check for up to an hour, so the error can persist briefly after you fix the endpoint.
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 the request contains a subscription object but is authenticated with a Public API Key. The recurring price must never be set from a browser.How to resolve: create the session from your backend with your Secret API Key, then open it with the SDK’s openSession().
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 the checkout_url from the response 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
  • For a subscription, renewals reuse it with a cycle suffix: {order_id}-2, {order_id}-3, …
  • Secret API Key only
  • interval: day, week, month or year
  • interval_count: integer from 1 up to 3 years (1095 days, 156 weeks, 36 months, 3 years); defaults to 1
  • amount is the price of one period (minimum 100 cents)

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

Optional customer email address. When provided, the payment page does not ask the customer for it: it becomes the Stripe receipt email and the Stripe Customer email, and is used for fraud screening when the payment method doesn't carry one. Must be a valid email address, otherwise the request is rejected with a 400. Stored on the subscription as customer_email.

Maximum string length: 255
subscription
object | null

Turns the session into a subscription signup: the customer pays the first period on the payment page, then the subscription renews automatically every period. amount is your price per period (the customer also pays the fees your account adds for the customer; see unit_amount on the Subscription). Requires your Secret API Key (sk_). Only card, Apple Pay and Google Pay (Stripe) are offered for a subscription. Send null or omit it for a one-time payment.

Example:

Response

Session created successfully

session_id
string

Unique identifier for the created session

checkout_url
string<uri>

Payment page for this session. https://secure.payviox.com/{session_id}, or the merchant's own subdomain once a custom checkout domain is active. Send the customer here rather than building the URL.