Choose Your Integration Method

The recommended integration is both at once. Create the payment session from your backend with your secret key (sk_), then hand the returned session_id to the JavaScript SDK in the browser and let it take the customer to the payment page. Your server stays in control of the amount and gets the ip fraud prevention parameter; the SDK handles the redirect. Everything below is a variation on that.

Recommended: backend session + SDK

This is how a typical checkout should work.

Your backend creates the session

Compute the amount from your own data — never from a value sent by the browser — and call POST /session with your secret key. Return the session_id to your frontend.

Node.js — your server

const response = await fetch('https://api.payviox.com/session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYVIOX_SECRET_KEY}`, // sk_
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1000, // cents — computed server-side from your cart
    currency: 'USD',
    customer: 'customer_123',
    description: 'Order #12345',
    order_id: 'order_12345',
    ip: req.ip, // fraud prevention, unlocked by the secret key
    items: [{ name: 'Product A', quantity: 2, price: 500 }],
  }),
});

const { session_id } = await response.json();

The SDK takes over in the browser

Initialize the SDK with your public key (pk_) and call openSession() with the session ID your backend returned.

Browser

const payviox = new Payviox('pk_live_your_key');

const { session_id } = await fetch('/api/checkout', { method: 'POST' }).then((r) => r.json());

payviox.openSession(session_id); // redirects to the secure payment page

Confirm with a webhook

The customer comes back to your site after paying, but the payment is confirmed by the webhook — that’s what you fulfill the order on, not the redirect.

Why not create the session from the browser? You can (see below), but then the amount comes from client-side code and can be tampered with, and you lose the ip parameter. If you have a backend, use it.

The two variations

SDK only — no backend

The SDK creates the session itself with your public key via createSession(), then redirects or opens an iframe.Use it when:

You have no backend (static site, prototype)
You’re evaluating Payviox and want a payment working in 5 minutes
You want iframe mode, which today requires createSession() client-side

Trade-off: the amount originates in the browser. Always verify amount and order_id in your webhook handler before fulfilling.SDK reference →

REST API only — no browser

Your server creates the session and sends the customer to https://secure.payviox.com/{session_id} itself — a plain HTTP redirect, or a link in an email.Use it when:

There is no browser to run the SDK in (backend service, cron, worker)
You’re on a mobile app backend
You’re on a non-JavaScript stack (PHP, Python, Ruby, Go…)
You send payment links by email or messaging

API reference →

Quick Comparison

	Backend session + SDK (recommended)	SDK only	API only
Amount computed	Server-side	Browser	Server-side
`ip` fraud parameter	✅ Available	❌ Auto-captured only	✅ Available
Redirect handling	SDK	SDK	Your code
Iframe mode	✅ Supported	✅ Supported	❌
Setup time	15-20 minutes	5-10 minutes	15-30 minutes
Needs a browser	Yes	Yes	No
Webhooks	Required	Required	Required

Want an embedded iframe instead of a redirect? Pass your iframe configuration straight to openIframe() — it works with a backend-created session exactly like openSession():

payviox.openIframe(session_id, { iframeTarget: document.getElementById('payment-container') });

Iframe mode requires your domain to be whitelisted in the dashboard. Note that redirect-based providers can’t render in an iframe: selecting one navigates the full page to the provider. See Iframe integration.

Which Should You Choose?

You have a backend (recommended path)

Create the session server-side with sk_, hand the session_id to the SDK, redirect with openSession(). This is the path to follow unless something below applies.

You have no backend at all

Use the SDK on its own with createSession() and your pk_ key. Add server-side session creation later when you have somewhere to put it — the frontend change is a two-line swap to openSession().

You need an embedded iframe

Same as the recommended path, but call openIframe(session_id, { iframeTarget }) instead of openSession(session_id). Without a backend, use createSession() with iframeMode from the browser. Either way, whitelist your domain in the dashboard. See Iframe integration.

You have no browser in the flow

Use the REST API on its own: create the session, then send the customer to https://secure.payviox.com/{session_id} — by HTTP redirect, email link, or however your product reaches them.

Next Steps

Complete Examples

Full working code for each of the three setups

POST /session

Create a session from your backend

openSession()

Hand a session ID to the SDK

Webhooks

Confirm payments — required in every setup