Skip to main content

​
Endpoint

POST /v1/sessions
EnvironmentFull URL
Sandboxhttps://sandbox.api.prava.space/v1/sessions
Productionhttps://api.prava.space/v1/sessions

​
Authentication

Bearer token using your secret key: 
Authorization: Bearer sk_test_xxx

​
Request Body

user_id and user_email are required for merchant (secret-key) requests. They identify the customer this session belongs to.

​
Required Fields

​
user_id
string
required
Unique identifier for the customer in your system (max 255 characters)
​
user_email
string
required
Customer’s email address (must be a valid email)
​
total_amount
string
required
Total order amount in decimal format (e.g., "49.99")
​
currency
string
required
ISO 4217 currency code — exactly 3 uppercase letters (e.g., "USD")
​
purchase_context
array
required
Array containing exactly 1 purchase context object describing the order. Multi-merchant sessions are not currently supported.

​
Optional Fields

​
user_phone
string
Customer’s phone number
​
user_country_code_iso2
string
Customer’s country — exactly 2 uppercase letters ISO 3166-1 (e.g., "US")
​
external_order_ref
string
Your external order reference ID (max 255 characters)
​
description
string
Human-readable description of the order
​
integration_type
string
default:"full_checkout"
How the card is collected. One of:
  • "full_checkout" (default) — hosted mode. The iframe_url is a full Prava-hosted page you redirect the cardholder to; Prava returns them to your callback_url when done. No SDK required.
  • "embedding" — embedded mode. Mount the iframe_url inside your own page with the SDK (collectPAN) and handle the result in-app.
See Integration Modes for a full comparison.
​
callback_url
string
For hosted checkout: the URL Prava redirects the cardholder to after they finish. Must use https (max 2048 characters).
​
card
object
Pre-select a card for the session

​
Response (201)

​
session_id
string
Unique session identifier
​
session_token
string
JWT token used to authenticate client-side SDK operations within this session
​
iframe_url
string
URL for the secure card collection surface. Embed it via the SDK’s collectPAN(), or open it directly (append session_token) for hosted checkout — see Integration Modes.
​
order_id
string
Internal order identifier
​
expires_at
string
ISO 8601 timestamp indicating when the session expires

​
Example

Swap the host for production: use https://api.prava.space instead of https://sandbox.api.prava.space.
curl -X POST https://sandbox.api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": [{
      "merchant_details": {
        "name": "Your Store",
        "url": "https://yourstore.com",
        "country_code_iso2": "US"
      },
      "product_details": [{
        "description": "Wireless Headphones",
        "unit_price": "49.99",
        "quantity": 1
      }]
    }]
  }'

curl -X POST https://api.prava.space/v1/sessions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "total_amount": "49.99",
    "currency": "USD",
    "purchase_context": [{
      "merchant_details": {
        "name": "Your Store",
        "url": "https://yourstore.com",
        "country_code_iso2": "US"
      },
      "product_details": [{
        "description": "Wireless Headphones",
        "unit_price": "49.99",
        "quantity": 1
      }]
    }]
  }'

const BASE_URL = 'https://sandbox.api.prava.space'; // or https://api.prava.space

const session = await fetch(`${BASE_URL}/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: 'Your Store',
        url: 'https://yourstore.com',
        country_code_iso2: 'US',
      },
      product_details: [{
        description: 'Wireless Headphones',
        unit_price: '49.99',
        quantity: 1,
      }],
    }],
  }),
}).then(res => res.json());

​
Response

{
  "session_id": "ses_a1b2c3d4",
  "session_token": "stok_xyz789...",
  "iframe_url": "https://secure.prava.space/collect/ses_a1b2c3d4",
  "order_id": "ord_m7kx9...",
  "expires_at": "2026-04-08T13:00:00Z"
}

​
Error Responses

StatusCodeCause
400VAL_2001Validation error — missing or invalid fields (details included in response)
401AUTH_1001Invalid API key
401AUTH_1002Missing or invalid Authorization header
429TRIES_EXHAUSTEDSandbox test-transaction limit reached for this merchant
500MERCHANT_LOOKUP_ERRORFailed to load merchant account for the given key
500CONFIG_ERRORServer-side configuration issue (Visa or Skyflow not configured)

​
Error Response Format

{
  "error": {
    "code": "VAL_2001",
    "message": "Validation error",
    "details": {
      "user_email": "Invalid email format"
    }
  }
}

​
Notes

  • Sessions are short-lived and expire after a configured duration.
  • Sessions are single-use — tied to a specific merchant, customer, and order.
  • Only one purchase_context entry is supported per session (multi-merchant not yet available).
  • The effective_until_minutes field in purchase_context controls how long the mandate is valid (default: 15 minutes).
  • Sessions can be revoked via POST /v1/sessions/:id/revoke.
  • The session_token and iframe_url are used on the frontend — embedded via the SDK, or opened directly for hosted checkout.
  • Set integration_type: "embedding" for the SDK flow; omit it (or use "full_checkout") for hosted, and provide a callback_url.