SDK Overview

Not sure this is the right path? See Choosing Your Integration.

What is the Prava SDK?

The Prava SDK (@prava-sdk/core) is a lightweight browser library for securely collecting a card in your web app. It mounts a PCI-compliant iframe, handles the card entry and authentication inside it, and hands you back a safe result — the raw card number never touches your page, your JavaScript, or your servers.

The SDK is the client-side piece of a session-based integration. Your backend creates the session (see the API Reference); the SDK renders the secure card form for that session. If instead you want an AI agent to pay from the command line, use Prava Pay.

The SDK powers the embedded integration mode — Prava’s card UI inside your own page. Don’t want to embed? Use hosted mode (a redirect, no SDK). See Integration Modes to choose.

What it does (and doesn’t)

The SDK’s job is deliberately small — one secure operation, done well:

The SDK handles	Your backend handles
Rendering the secure card iframe	Creating the session (`POST /v1/sessions`)
Card entry, validation, and in-iframe authentication	Reading the payment result
Returning a safe, tokenized result	Reporting the final transaction status

Everything money-related — mandates, one-time payment credentials, spending limits — is enforced by Prava and the card network, not by code running in your page. See Payments and Guardrails for how that works.

Install

npm install @prava-sdk/core

yarn add @prava-sdk/core

pnpm add @prava-sdk/core

Quick start

Initialize with your publishable key

import { PravaSDK } from '@prava-sdk/core';

const prava = new PravaSDK({
  publishableKey: 'pk_live_xxx', // from the Prava Dashboard
});

The publishable key is safe to ship to the browser. Your secret key stays on your server and is never used here.

Create a session on your backend

Your server creates a session with your secret key and returns the session_token and iframe_url to your frontend:

// Server-side (never expose your secret key to the browser)
const session = await fetch('https://api.prava.space/v1/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_id: 'user_123',
    user_email: 'user@example.com',
    total_amount: '49.99',
    currency: 'USD',
    purchase_context: [{
      merchant_details: { name: 'Amazon', url: 'https://amazon.com', country_code_iso2: 'US' },
      product_details: [{ description: 'Wireless Headphones', unit_price: '49.99', quantity: 1 }],
    }],
  }),
}).then((r) => r.json());
// → { session_id, session_token, iframe_url, expires_at, order_id }

Full request/response details: Create Session.

Collect the card in the browser

const result = 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>

See Collect Card Details for every option and callback.

Read the result on your backend

After the card is collected and the transaction runs, your backend reads the outcome and reports the final status. See Get Payment Result and Report Status.

API surface

The SDK exposes exactly two methods:

Method	Description
`collectPAN(options)`	Mounts the secure iframe, collects the card, resolves with a `CollectPANResult`.
`destroy()`	Tears down the iframe and listeners. Call it on unmount/cleanup.

// Clean up when your component unmounts
prava.destroy();

Authentication

Key	Where it’s used	Where it lives
Publishable key (`pk_live_` / `pk_test_`)	Initialize the SDK in the browser	Frontend
Secret key (`sk_*`)	Create sessions, read results	Backend only

Never put your secret key in client-side code or version control.

Result & error types

interface CollectPANResult {
  enrollmentId: string;
  last4: string;
  brand: string;      // "visa", "mastercard", …
  expMonth: number;
  expYear: number;
}

interface PravaError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

Error codes, every collectPAN option, and validation states are documented on Collect Card Details — the canonical collectPAN reference.

Requirements

Browsers: Chrome 80+, Firefox 80+, Safari 14+, Edge 80+.
Backend: Your server implements the session API (POST /v1/sessions) with your secret key.
Keys: Obtain publishableKey and secretKey from the Prava Dashboard.

Next steps

Collect Card Details

Every collectPAN option, callback, and validation state.

API Reference

Create sessions, read payment results, and report status server-side.

How Prava Works

The lifecycle behind a Prava payment.

Prava Pay (CLI)

Let an AI agent pay from the command line.

Getting Started

Guides

Prava SDK

Prava MCP

Prava CLI

Resources

What is the Prava SDK?

What it does (and doesn’t)

Install

Quick start

API surface

Authentication

Result & error types

Requirements

Next steps

Collect Card Details

API Reference

How Prava Works

Prava Pay (CLI)

​What is the Prava SDK?

​What it does (and doesn’t)

​Install

​Quick start

​API surface

​Authentication

​Result & error types

​Requirements

​Next steps

Collect Card Details

API Reference

How Prava Works

Prava Pay (CLI)

What is the Prava SDK?

What it does (and doesn’t)

Install

Quick start

API surface

Authentication

Result & error types

Requirements

Next steps