Skip to main content
POST
/
session
Create Session
curl --request POST \
  --url https://api.payviox.com/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 123,
  "currency": "<string>",
  "customer": {
    "email": "<string>",
    "name": "<string>",
    "phone": "<string>"
  },
  "order_id": "<string>",
  "items": [
    {
      "name": "<string>",
      "quantity": 123,
      "price": 123
    }
  ],
  "description": "<string>",
  "paymentMethodId": "<string>"
}'
{
  "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 requires API key authentication. See Authentication for details. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
amount
integer
required
The payment amount in cents (e.g., 10000 = $100.00)Minimum: 100 (equivalent to $1.00)
​
currency
string
required
Three-letter ISO currency code (e.g., USD, EUR, GBP)Note: Currently only USD is supported
​
customer
object
required
Customer information
​
order_id
string
required
Your unique order identifier. This will be included in webhooks.
​
items
array
required
Array of items being purchased
​
description
string
Optional description of the payment
​
paymentMethodId
string
Force a specific payment method (optional). When provided, only this payment method will be available.

​
Response

​
session_id
string
Unique identifier for the created session

​
Example Request

curl https://api.payviox.com/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe",
      "phone": "+1234567890"
    },
    "order_id": "order_12345",
    "description": "Premium subscription",
    "items": [
      {
        "name": "Premium Plan",
        "quantity": 1,
        "price": 10000
      }
    ]
  }'

​
Example Response

{
  "session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

​
Error Responses

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

​
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

  • 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