Create Payment Session

Create a payment session to initiate a transaction. The response includes a session_url — redirect the user there immediately to complete payment on the hosted Spayon page.

Endpoint

Production

POST https://api.spayon.io/api/product/session
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json

Sandbox

POST http://staging-spayon-api.eu-north-1.elasticbeanstalk.com/api/product/session
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json

Request Body

There are two ways to create a session depending on whether you are using a product pre-configured in the admin panel.

Option 1 — Using a Marketplace Product

Use this when the product already exists in your admin panel. Provide product_id instead of price/currency.

{
  "product_id": 1,
  "callback_url": "https://example.com/api/payment-callback",
  "return_url": "https://example.com/thank-you",
  "cancel_url": "https://example.com/payment-cancelled",
  "email": "user@example.com",
  "user_name": "john_doe",
  "full_name": "John Doe",
  "order_id": "ORDER_123456",
  "defaultPaymentMethod": "visamaster",
  "availablePaymentMethods": ["visamaster", "mir"],
  "language": "en"
}

Option 2 — Custom Product Details

Use this when the product is not in the admin panel. Provide product_name, price, and currency directly.

{
  "product_name": "Custom Product",
  "price": 1000,
  "currency": "amd",
  "callback_url": "https://example.com/api/payment-callback",
  "return_url": "https://example.com/thank-you",
  "cancel_url": "https://example.com/payment-cancelled",
  "email": "user@example.com",
  "user_name": "john_doe",
  "full_name": "John Doe",
  "order_id": "ORDER_123456",
  "defaultPaymentMethod": "visamaster",
  "availablePaymentMethods": ["visamaster", "mir"],
  "language": "en"
}

Field Reference

Field	Type	Required	Description
product_id	integer	Conditional	Product ID from the admin panel. Use instead of product_name/price/currency.
product_name	string	Conditional	Product name. Required when not using product_id.
price	number	Conditional	Exact price amount. Required when not using product_id.
currency	string	Conditional	AMD, RUB, USD, EUR, or GBP. Required when not using product_id.
callback_url	string	Yes	URL to receive POST payment notifications. Must be publicly accessible.
return_url	string	Yes	URL the user is redirected to after payment completes (regardless of status).
cancel_url	string	No	URL the user is redirected to when clicking the back button on the payment page.
email	string	No	Customer email address.
user_name	string	No	Customer username.
full_name	string	No	Customer full name.
order_id	string	No	Your internal order identifier for tracking.
defaultPaymentMethod	string	No	Pre-selected payment method: visamaster, mir, crypto, or sbp. Must also be enabled for your account.
availablePaymentMethods	array	No	Restrict available methods: ["visamaster", "mir", "crypto", "sbp"].
language	string	No	Payment page language: en, hy, or ru.

Protocol

In Production, callback_url and return_url must use HTTPS. In Sandbox, HTTP is also accepted.

Skipping the payment method selection page

When you send defaultPaymentMethod, the returned session_url points directly at the checkout page for that method, skipping the intermediate method-selection page. This works for every method — visamaster, mir, crypto, and sbp.

If you omit defaultPaymentMethod and more than one method is enabled, the customer is sent to the selection page first.

Cryptocurrency Payments

Set defaultPaymentMethod to crypto (or include it in availablePaymentMethods) to accept cryptocurrency.

{
  "product_name": "Premium Subscription",
  "price": 100,
  "currency": "USD",
  "callback_url": "https://example.com/api/payment-callback",
  "return_url": "https://example.com/thank-you",
  "order_id": "ORDER_123456",
  "defaultPaymentMethod": "crypto",
  "language": "en"
}

How it works:

1. The customer chooses a coin and network on the checkout page.
2. They are shown the exact crypto amount to send and a wallet address.
3. Once the network confirms the transfer, the session becomes paid and your callback_url is called.

Notes:

• Pricing stays in your session currency. You set price and currency as usual; the crypto amount is calculated at payment time.
• Confirmation is not instant. Depending on the coin and network, confirmation typically takes a few minutes. The session stays pending until the network confirms, and crypto sessions are given a longer window than the standard 15-minute card timeout.
• Always rely on the callback, not the customer returning to return_url — the customer may close the browser while the transfer confirms.
• Underpayments and overpayments are resolved by the amount actually received.

SBP Payments (RUB)

Set defaultPaymentMethod to sbp (or include it in availablePaymentMethods) to accept payments through SBP, Russia's Fast Payments System.

{
  "product_name": "Premium Subscription",
  "price": 1000,
  "currency": "RUB",
  "callback_url": "https://example.com/api/payment-callback",
  "return_url": "https://example.com/thank-you",
  "order_id": "ORDER_123456",
  "defaultPaymentMethod": "sbp",
  "language": "ru"
}

How it works:

1. The customer is shown a QR code and the exact amount to pay.
2. They scan it with their Russian banking app, or tap through to their bank directly.
3. Once the payment is confirmed, the session becomes paid and your callback_url is called.

Notes:

• The customer must pay the exact amount shown. A different amount may not be matched to the order automatically.
• The payment window is 10 minutes, shorter than the 15-minute default for cards. After that the session becomes expired.
• The customer stays on our page — there is no redirect to a bank's site. They pay in their banking app while the checkout page waits.
• Always rely on the callback. The customer may close the browser after paying, and confirmation is not instant.
• Pricing in another currency is converted to RUB at payment time. Set price in RUB if you want full control over the amount the customer sees.

Response

{
  "session_url": "https://spayon.io/session/5716f328-5adb-46fe-938f-d72f1d65b98e",
  "session_id": "5716f328-5adb-46fe-938f-d72f1d65b98e",
  "status": "pending",
  "order_id": "ORDER_123456"
}

Immediately redirect the user to session_url after receiving this response.

Response Codes

Status Code	Description
200 OK	Session created successfully
400 Bad Request	Invalid or missing parameters
401 Unauthorized	Invalid or expired Bearer Token

Session Constraints

Property	Value
Expiry	15 minutes from creation (10 minutes for sbp; longer for crypto)
Single use	Each session URL can only be used once
Redirect	Redirect users immediately — do not delay