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": "ches_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": "sess_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/sess_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

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

{
  "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": "ches_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": "sess_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/sess_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

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

{
  "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 (passkey approval) and authorizeOnly: true, and issues no 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, authorizeOnly: true, and no credentials. Once the mandate is active, charge it any time with Charge a Mandate — 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.

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 a quote_id. Merchant and product details come from the /quote endpoint, 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 id of the quote from the shopping flow (checkout-session-id, e.g. ches_…). The quote carries the merchant, products, and locked price — note that quotes expire (~15 minutes).

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.

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.

boolean

Present and true for mandate-setup sessions (no credentials issued).

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"`
401	`AUTH_1001`	Invalid API key
401	`AUTH_1002`	Missing or invalid Authorization header
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": "ches_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": "sess_9f2c...",
  "session_token": "eyJhbGciOi...",
  "iframe_url": "https://checkout.prava.space/s/sess_9f2c...",
  "order_id": "ord_4a1b...",
  "expires_at": "2026-07-26T12:15:00Z"
}

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

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

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

Server-Side API

Reference

Which flow?

Mandate setup

Body

Response

Notes

Error responses

​Which flow?

​Mandate setup

​Body

​Response

​Notes

​Error responses

Which flow?

Mandate setup

Body

Response

Notes

Error responses