Integration Modes

Every card collection starts the same way: your backend creates a session (POST /v1/sessions) and gets back a session_token and an iframe_url. From there you choose how the cardholder enters their card — and you pick by setting one field, integration_type, on the session.

Embedded

Prava’s card UI runs inside your app via the SDK. You control the surrounding page and get the result in-app.

Hosted (default)

You redirect the cardholder to a Prava-hosted page. No SDK, minimal code — Prava returns them to your callback_url when done.

Either way, the card is entered on Prava’s secure surface and tokenized — your app never touches the raw card number. There is no mode where you collect the PAN yourself.

At a glance

	Embedded (`"embedding"`)	Hosted (`"full_checkout"`, default)
SDK required	Yes (`@prava-sdk/core`)	No
Where the card UI renders	An iframe inside your page	A full Prava-hosted page you redirect to
What you build	A container + SDK wiring	A redirect + a `callback_url` route
How you get the result	`onSuccess` callback, in-app	Prava redirects the user to your `callback_url`
Best when	You want the flow to feel native to your product	You want the fastest, lowest-maintenance integration

Both modes use the same session and the same iframe_url — embed it, or open it directly.

Embedded mode

Create the session with integration_type: "embedding", then mount the card UI with the SDK.

// 1. Backend: create the session
const session = await createSession({
  /* user_id, user_email, total_amount, currency, purchase_context … */
  integration_type: 'embedding',
});

// 2. Frontend: mount Prava's secure iframe in your page
import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({ publishableKey: 'pk_test_xxx' });

await prava.collectPAN({
  sessionToken: session.session_token,
  iframeUrl: session.iframe_url,
  container: '#card-form',
  onSuccess: (data) => console.log(`Collected •••• ${data.last4}`),
  onError: (err) => console.error(err.code, err.message),
});

<div id="card-form"></div>

The result arrives in onSuccess without leaving your page. See Collect Card Details for every option and callback, and remember to call prava.destroy() on cleanup.

Hosted mode (default)

Leave integration_type off (it defaults to "full_checkout") and give Prava a callback_url. Then send the cardholder to the returned iframe_url — no SDK needed.

// 1. Backend: create the session (hosted is the default)
const session = await createSession({
  /* user_id, user_email, total_amount, currency, purchase_context … */
  callback_url: 'https://yourapp.com/checkout/complete', // must be https
});

// 2. Frontend: send the user to the hosted page
const url = new URL(session.iframe_url);
url.searchParams.set('session_token', session.session_token);
window.location.href = url.toString(); // or window.open(url, '_blank')

When the cardholder finishes, Prava redirects them back to your callback_url. Your backend then reads the outcome with Get Payment Result and reports the final status with Report Status.

callback_url must be an https URL. Without it, a hosted checkout has nowhere to return the user.

Which should I use?

Choose Embedded

You want the card step to feel native, keep the user on your page, and react to the result in-app.

Choose Hosted

You want to ship fast with minimal frontend code and are happy to redirect out and back.

Next steps

SDK Overview

The library behind embedded mode.

Create Session

integration_type, callback_url, and the full request/response.

Getting Started

Guides

Prava SDK

Prava MCP

Prava CLI

Resources

Embedded

Hosted (default)

At a glance

Embedded mode

Hosted mode (default)

Which should I use?

Choose Embedded

Choose Hosted

Next steps

SDK Overview

Create Session

Embedded

Hosted (default)

​At a glance

​Embedded mode

​Hosted mode (default)

​Which should I use?

Choose Embedded

Choose Hosted

​Next steps

SDK Overview

Create Session

At a glance

Embedded mode

Hosted mode (default)

Which should I use?

Next steps