Create Session

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Widget", "unit_price": "24.99", "quantity": 2 }]
      }]
    },
    "integration_type": "full_checkout",
    "callback_url": "https://acme.example.com/return"
  }'

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "22.45",
    "currency": "USD",
    "purchase_context": {
      "quote": true,
      "quote_id": "qte_9f2c..."
    }
  }'

import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "user_id": "user_123",
        "user_email": "jane@example.com",
        "total_amount": "49.99",
        "currency": "USD",
        "purchase_context": {
            "custom": [{
                "merchant_details": {"name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US"},
                "product_details": [{"description": "Widget", "unit_price": "24.99", "quantity": 2}],
            }],
        },
        "integration_type": "full_checkout",
        "callback_url": "https://acme.example.com/return",
    },
)

const resp = await fetch("https://sandbox.api.prava.space/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "user_123",
    user_email: "jane@example.com",
    total_amount: "49.99",
    currency: "USD",
    purchase_context: {
      custom: [{
        merchant_details: { name: "Acme Store", url: "https://acme.example.com", country_code_iso2: "US" },
        product_details: [{ description: "Widget", unit_price: "24.99", quantity: 2 }],
      }],
    },
    integration_type: "full_checkout",
    callback_url: "https://acme.example.com/return",
  }),
});

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "40.00",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Monthly plan", "unit_price": "40.00" }]
      }]
    },
    "mandate_setup": {
      "intent": "mandate_setup",
      "recurring_frequency": "monthly",
      "merchant_scope": "listed",
      "max_charges": 12
    }
  }'

{
  "session_id": "ses_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "session_id": "ses_7d1a...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_7d1a...",
  "order_id": "ord_88c2...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "error": {
    "code": "VAL_2001",
    "message": "Validation failed",
    "details": { "currency": "Unsupported currency code" }
  }
}

{
  "error": { "code": "AUTH_1001", "message": "Invalid API key" }
}

POST

sessions

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Widget", "unit_price": "24.99", "quantity": 2 }]
      }]
    },
    "integration_type": "full_checkout",
    "callback_url": "https://acme.example.com/return"
  }'

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "22.45",
    "currency": "USD",
    "purchase_context": {
      "quote": true,
      "quote_id": "qte_9f2c..."
    }
  }'

import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "user_id": "user_123",
        "user_email": "jane@example.com",
        "total_amount": "49.99",
        "currency": "USD",
        "purchase_context": {
            "custom": [{
                "merchant_details": {"name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US"},
                "product_details": [{"description": "Widget", "unit_price": "24.99", "quantity": 2}],
            }],
        },
        "integration_type": "full_checkout",
        "callback_url": "https://acme.example.com/return",
    },
)

const resp = await fetch("https://sandbox.api.prava.space/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "user_123",
    user_email: "jane@example.com",
    total_amount: "49.99",
    currency: "USD",
    purchase_context: {
      custom: [{
        merchant_details: { name: "Acme Store", url: "https://acme.example.com", country_code_iso2: "US" },
        product_details: [{ description: "Widget", unit_price: "24.99", quantity: 2 }],
      }],
    },
    integration_type: "full_checkout",
    callback_url: "https://acme.example.com/return",
  }),
});

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "40.00",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Monthly plan", "unit_price": "40.00" }]
      }]
    },
    "mandate_setup": {
      "intent": "mandate_setup",
      "recurring_frequency": "monthly",
      "merchant_scope": "listed",
      "max_charges": 12
    }
  }'

{
  "session_id": "ses_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "session_id": "ses_7d1a...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_7d1a...",
  "order_id": "ord_88c2...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "error": {
    "code": "VAL_2001",
    "message": "Validation failed",
    "details": { "currency": "Unsupported currency code" }
  }
}

{
  "error": { "code": "AUTH_1001", "message": "Invalid API key" }
}

Create a short-lived, single-use session tied to one merchant, customer, and order. The response gives you a session_token + iframe_url for the frontend — embed the iframe via the SDK or open the hosted checkout directly. POST /v1/sessions · Authenticated with your secret key.

Which flow?

Standard checkout
Mandate setup

Omit mandate_setup (or send intent: "checkout"). The session collects a card and charges immediately.

Include a mandate_setup block with intent: "mandate_setup". The session is authorize-only: it returns an iframe_url for passkey approval, and completing setup issues no payment credentials. Charge later with Charge a Mandate. There is no separate POST /v1/mandates create endpoint — a mandate is always set up through this endpoint.

Mandate setup

Mandate creation is part of the Session APIs — this endpoint is how mandates are created. Send a mandate_setup block (see Body) with intent: "mandate_setup" and the session becomes authorize-only: the response carries an iframe_url where the owner approves once with their passkey. Completing setup does not issue payment credentials. Once the mandate is active, charge it with Charge a Mandate within its approved terms — no further passkey needed. The mandate_setup field reference below covers recurring_frequency, merchant_scope, max_charges, and valid_until; see Mandates for the concept and guardrails.

Choosing a card source. Omit card to let the cardholder select or enter a card in the collection surface. Send card.card_id to pre-select an already-enrolled card, or card.vault_ref_id (a Skyflow UUID) for the vault-ref flow. Send exactly one — if both are present, card_id wins. After collection, Get Payment Result returns the card bound to each transaction as transactions[].card_id.

Body

string

required

Unique identifier for the customer in your system (1–255 chars). Required for merchant (secret-key) sessions — omitting it returns 400 VAL_2001.

string

required

Customer email. Required for merchant sessions. Must be a valid email address.

string

required

Total order amount as a decimal string with up to 2 decimals, e.g. "49.99". Need not equal the sum of line items (it may include tax, shipping, and fees). This value becomes the authorized amount cap.

string

required

ISO 4217 code — 3 uppercase letters — and must be a supported currency. Supported: USD, EUR, GBP, INR, CAD, AUD, JPY, SGD, AED, HKD, MXN, BRL, CHF, CNY, NZD, SEK, NOK, DKK, ZAR, THB, KRW, PLN, TWD, PHP, IDR, MYR, CZK, ILS, CLP, ARS, COP, PEN, SAR, QAR, KWD, BHD, OMR, EGP, NGN, KES, GHS, TZS, UGX, PKR, BDT, LKR, VND, MMK, NPR. Other codes are rejected.This is your pricing currency and is independent of the card’s issuing country: there is no requirement that it match country_code_iso2 (the merchant’s location) or the cardholder’s country. A US-issued card can pay an INR-denominated session; the card network settles the cross-currency conversion. Price in whatever currency your product uses — you don’t need to re-denominate.

object

required

What is being bought. Two modes — pick one:

From a quote — send quote: true and the opaque quote_id (qte_…) returned when the quote was created. Merchant and product details come from that quote, so nothing else is needed.
Custom — omit quote (or send false) and describe the merchant and products yourself in custom.

Show purchase_context properties

boolean

default:false

Set true to build the session from an existing quote. When true, pass quote_id and nothing else — custom must be omitted. When false or absent, custom is required and quote_id must be omitted.

string

Required when quote is true. The opaque public quote id returned by quote creation (for example, qte_…). The quote carries the merchant, products, and locked price. Create the session before the quote expires; its expiry is separate from the session’s lifetime. total_amount and currency must match the quote’s final total. Do not send a merchant checkout-session id.

object[]

Required when quote is not true. Exactly one entry — multi-merchant sessions are not yet supported.

Show custom[] properties

object

required

The destination merchant — the business the cardholder is buying from, not your application. The name renders as the header on the checkout page and is forwarded to Visa as the merchant of record for the token.

Show merchant_details properties

string

required

Merchant display name. Sanitized to a Visa-safe character set (e.g. H&M → HM); must contain at least one usable character.

string

required

Merchant website URL. Must use https — the URL is forwarded to Visa.

string

required

Merchant country — 2 uppercase ISO 3166-1 letters, e.g. "US".

string

Merchant category code (MCC). Free-form string, max 10 characters.

string

Merchant category description, max 100 characters.

object[]

required

At least one product.

Show product_details[] properties

string

required

Product description.

string

required

Unit price as a string, e.g. "24.99".

string

Your external product identifier, max 50 characters.

integer

default:1

Quantity of this product. Positive integer.

integer

default:15

How long the resulting mandate stays effective, in minutes. Positive integer.

string

default:"full_checkout"

full_checkout (hosted redirect) or embedding (mount the iframe via the SDK). Read by the frontend to choose the surface.

string

For hosted checkout: the URL Prava redirects the cardholder to after they finish. Must use https, max 2048 chars. Optional for all integration types.

object

Pre-select a card. Send one of the two fields below (see the note above).

Show card properties

string

An enrolled card id (the enrollmentId from the SDK’s collectPAN(), or a card_id from List Cards). Scoped to this customer + merchant.

string

A Skyflow vault reference UUID. Triggers provisioning at session-create.

object

Turns the session into mandate setup (authorize-only). See the Mandate setup tab above.

Show mandate_setup properties

string

mandate_setup (authorize-only, no charge) or checkout. Defaults to mandate_setup when this block is present.

string

one_time, weekly, monthly, or yearly.

string

listed (locked to this merchant) or any (any merchant). Recurring frequencies force listed — sending any with a recurring frequency returns 400 MANDATE_RECURRING_MUST_BE_SCOPED.

string

ISO 8601 datetime. Ignored for one_time, which is always clamped to 7 days. Recurring horizons: yearly 5y, monthly 2y, weekly 1y.

integer

default:1

Maximum number of charges allowed against this mandate. Positive integer. (The per-charge amount cap is enforced separately, at the card network.)

string

Customer phone number.

string

Customer country — 2 uppercase ISO 3166-1 letters.

string

Your external order reference id, max 255 chars.

string

Human-readable description of the order.

object

Optional, sandbox-only payment success simulation for quote-backed checkout. The exact shape is { "stage": "payment", "outcome": "success" }; both fields are required and additional fields are rejected. Custom checkout, production, and mandate-setup sessions cannot use it. Normal card collection and verification still run. An eligible terminal payment result can complete the sandbox lifecycle while observed_result retains the actual outcome. See Sandbox simulation.

Response

string

Unique session identifier.

string

JWT authenticating client-side SDK calls within this session.

string

Secure card-collection (or, for mandate setup, passkey-approval) surface.

string

Internal order identifier.

string

ISO 8601 timestamp when the session expires.

Notes

Sessions are short-lived and single-use, tied to a specific merchant, customer, and order.
session_token and iframe_url are used on the frontend: embedded via the SDK, or opened directly for hosted checkout.
Sessions can be revoked before use via POST /v1/sessions/:id/revoke.

Error responses

Status	Code	Cause
400	`VAL_2001`	Validation error (missing/invalid fields; `user_id`/`user_email` missing on a merchant session; `quote: true` without a `quote_id`; `custom` missing when `quote` is not true). `details` names the fields.
400	`CARD_NOT_FOUND`	Pre-selected `card_id` does not exist for this customer + merchant
400	`CARD_INACTIVE`	Pre-selected card is not active
400	`MANDATE_RECURRING_MUST_BE_SCOPED`	Recurring frequency sent with `merchant_scope: "any"`
400	`SANDBOX_SIMULATION_NOT_ALLOWED`	Simulation requested outside sandbox, for a custom checkout, or for mandate setup
401	`AUTH_1001`	Invalid API key
401	`AUTH_1002`	Missing or invalid Authorization header
409	`QUOTE_SESSION_MISMATCH`	Session amount or currency differs from the quote’s final total
410	`QUOTE_EXPIRED`	The quote expired before session creation
429	`TRIES_EXHAUSTED`	Sandbox test-transaction limit reached for this merchant
500	`MERCHANT_LOOKUP_ERROR`	Failed to load the merchant account for the key
500	`CONFIG_ERROR`	Server-side configuration issue (Visa or Skyflow not configured)

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Widget", "unit_price": "24.99", "quantity": 2 }]
      }]
    },
    "integration_type": "full_checkout",
    "callback_url": "https://acme.example.com/return"
  }'

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "22.45",
    "currency": "USD",
    "purchase_context": {
      "quote": true,
      "quote_id": "qte_9f2c..."
    }
  }'

import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/sessions",
    headers={"Authorization": "Bearer sk_test_..."},
    json={
        "user_id": "user_123",
        "user_email": "jane@example.com",
        "total_amount": "49.99",
        "currency": "USD",
        "purchase_context": {
            "custom": [{
                "merchant_details": {"name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US"},
                "product_details": [{"description": "Widget", "unit_price": "24.99", "quantity": 2}],
            }],
        },
        "integration_type": "full_checkout",
        "callback_url": "https://acme.example.com/return",
    },
)

const resp = await fetch("https://sandbox.api.prava.space/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "user_123",
    user_email: "jane@example.com",
    total_amount: "49.99",
    currency: "USD",
    purchase_context: {
      custom: [{
        merchant_details: { name: "Acme Store", url: "https://acme.example.com", country_code_iso2: "US" },
        product_details: [{ description: "Widget", unit_price: "24.99", quantity: 2 }],
      }],
    },
    integration_type: "full_checkout",
    callback_url: "https://acme.example.com/return",
  }),
});

curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "jane@example.com",
    "total_amount": "40.00",
    "currency": "USD",
    "purchase_context": {
      "custom": [{
        "merchant_details": { "name": "Acme Store", "url": "https://acme.example.com", "country_code_iso2": "US" },
        "product_details": [{ "description": "Monthly plan", "unit_price": "40.00" }]
      }]
    },
    "mandate_setup": {
      "intent": "mandate_setup",
      "recurring_frequency": "monthly",
      "merchant_scope": "listed",
      "max_charges": 12
    }
  }'

{
  "session_id": "ses_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "session_id": "ses_7d1a...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/ses_7d1a...",
  "order_id": "ord_88c2...",
  "expires_at": "2026-07-26T12:15:00Z"
}

{
  "error": {
    "code": "VAL_2001",
    "message": "Validation failed",
    "details": { "currency": "Unsupported currency code" }
  }
}

{
  "error": { "code": "AUTH_1001", "message": "Invalid API key" }
}

Authorizations

Authorization

string

header

required

Your secret key: sk_test_* (sandbox) or sk_live_* (production).

Body

application/json

user_id

string

required

Unique identifier for the customer in your system

Required string length: 1 - 255

user_email

string<email>

required

Customer's email address

Maximum string length: 320

total_amount

string

required

Total order amount in decimal format (e.g. "49.99")

Minimum string length: 1

Pattern: ^\d+(\.\d{1,2})?$

currency

string

required

ISO 4217 currency code — exactly 3 uppercase letters, and one of Prava's supported currencies (e.g. USD, EUR, GBP, INR) - other codes are rejected

Required string length: 3

Pattern: ^[A-Z]{3}$

purchase_context

Custom checkout · object

required

What is being bought. Two modes — send exactly one: quote: true + quote_id (session built from an existing quote), or custom (describe the merchant and products yourself).

Custom checkout
Quote checkout

Show child attributes

user_phone

string

Customer's phone number

user_country_code_iso2

string

Customer's country — 2 uppercase ISO 3166-1 letters

Required string length: 2

Pattern: ^[A-Z]{2}$

external_order_ref

string

Your external order reference ID

Maximum string length: 255

description

string

Human-readable description of the order

integration_type

enum<string>

default:full_checkout

How the card is collected. full_checkout = hosted redirect; embedding = mount the iframe via the SDK.

Available options:

full_checkout,

embedding

callback_url

string<uri>

For hosted checkout: the https URL Prava redirects the cardholder to after they finish. Optional for all integration types.

Maximum string length: 2048

Pattern: ^https://

card

object

Pre-select a card. Send card_id OR vault_ref_id; if both are sent, card_id wins.

Show child attributes

mandate_setup

object

Turns the session into mandate setup (authorize-only). Absent = standard checkout.

Show child attributes

sandbox_simulation

object

Sandbox-only success simulation for quote-backed payment sessions. Fixed at session creation; production, custom checkout, and mandate setup reject this option. Normal card collection and verification still run. See Testing in Sandbox.

Show child attributes

Response

Session created

session_id

string

Unique session identifier

session_token

string

JWT to authenticate client-side SDK operations within this session

iframe_url

string

URL for the secure card collection surface

order_id

string

Internal order identifier

expires_at

string<date-time>

ISO 8601 timestamp when the session expires

Server-Side API

Reference

Which flow?

Mandate setup

Body

Response

Notes

Error responses

Authorizations

Body

Response

​Which flow?

​Mandate setup

​Body

​Response

​Notes

​Error responses

Authorizations

Body

Response

Which flow?

Mandate setup

Body

Response

Notes

Error responses