Create a payment session

Create a payment session with a POST to /payments/session, authenticated with your API key. The response gives you a hosted checkout URL to send your customer to.

POST https://api.xenonpay.net/api/payments/session

Request

Send JSON with your API key in the x-api-key header. Only amount is required.

{
  "amount": 500,
  "order_id": "merchant-order-123",
  "customer_name": "Asha Sharma",
  "customer_email": "[email protected]",
  "customer_phone": "+919876543210"
}

Field	Type	Required	Rules
`amount`	number	Yes	Whole rupees, from 500 through 99000 inclusive
`order_id`	string	No	Your own order reference
`customer_name`	string	No
`customer_email`	string	No
`customer_phone`	string	No

Success response

A successful call returns 201 Created. Send the customer to checkout_url, and store ref_id and session_token against your order.

{
  "ref_id": "XPABC123",
  "session_token": "48-character-hex-session-token",
  "checkout_url": "https://pay.xenonpay.net/checkout/48-character-hex-session-token",
  "amount": 500,
  "currency": "INR",
  "expires_at": "2026-08-24T10:10:00.000Z",
  "bank": {
    "upi_id": "merchant@upi",
    "qr_image_url": "https://example.com/qr.png"
  }
}

Field	Type	Notes
`ref_id`	string	XenonPay payment reference
`session_token`	string	Identifies this session; used in the checkout URL and status calls
`checkout_url`	string	Where you send the customer to pay
`amount`	number	Whole rupees
`currency`	string	Always `INR`
`expires_at`	string	ISO-8601; the session expires 10 minutes after creation
`bank.upi_id`	string or null	UPI ID the customer pays
`bank.qr_image_url`	string or null	QR image for the payment

Amount validation errors

Amounts must be whole rupees between ₹500 and ₹99,000. Each of these returns 422, except when no bank is available.

Condition	Status	Response
Missing, non-number, zero, or negative amount	422	`{"error":"amount must be a positive number (whole rupees)"}`
Decimal or paise amount	422	`{"error":"amount must be a whole number — paise are not accepted"}`
Below ₹500	422	`{"error":"Minimum payment amount is ₹500"}`
Above ₹99,000	422	`{"error":"Maximum payment amount is ₹99,000"}`
No active bank account available	503	`{"error":"No active bank accounts available"}`

For authentication errors, see the Authentication article.

Was this helpful?