> ## Documentation Index > Fetch the complete documentation index at: https://docs.prava.space/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > Create a new payment session for a customer and order `user_id` and `user_email` are **required** for merchant (secret-key) requests: they identify the customer this session belongs to. Only **one** `purchase_context` entry is supported per session (multi-merchant is not yet available). ## Notes * Sessions are **short-lived** and **single-use**, tied to a specific merchant, customer, and order. * `effective_until_minutes` in `purchase_context` controls how long the mandate (the spending permission created when the cardholder approves) is valid (default: 15). * `session_token` and `iframe_url` are used on the frontend: embedded via the [SDK](/sdk/overview), or opened directly for [hosted checkout](/sdk/integration-modes). * Set `integration_type: "embedding"` for the SDK flow; omit it (or use `"full_checkout"`) for hosted, and provide a `callback_url`. * Sessions can be revoked via [`POST /v1/sessions/:id/revoke`](/api-reference/revoke-session). ## Error responses | Status | Code | Cause | | ------ | ----------------------- | -------------------------------------------------------------------------- | | 400 | `VAL_2001` | Validation error: missing or invalid fields (details included in response) | | 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 merchant account for the given key | | 500 | `CONFIG_ERROR` | Server-side configuration issue (Visa or Skyflow not configured) | ## OpenAPI ````yaml api-reference/openapi.json POST /v1/sessions openapi: 3.1.0 info: title: Prava Payments API description: >- Server-side REST API for Prava Payments. All requests are authenticated with your secret key (sk_test_* in sandbox, sk_live_* in production). version: 1.0.0 servers: - url: https://sandbox.api.prava.space description: Sandbox - url: https://api.prava.space description: Production security: - bearerAuth: [] paths: /v1/sessions: post: summary: Create Session description: Create a new payment session for a customer and order. operationId: createSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' responses: '201': description: Session created content: application/json: schema: $ref: '#/components/schemas/CreateSessionResponse' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' components: schemas: CreateSessionRequest: type: object required: - user_id - user_email - total_amount - currency - purchase_context properties: user_id: type: string maxLength: 255 description: Unique identifier for the customer in your system user_email: type: string format: email description: Customer's email address total_amount: type: string description: Total order amount in decimal format (e.g. "49.99") currency: type: string description: ISO 4217 currency code — exactly 3 uppercase letters (e.g. "USD") purchase_context: type: array minItems: 1 maxItems: 1 description: >- Exactly one purchase context object. Multi-merchant sessions are not currently supported. items: $ref: '#/components/schemas/PurchaseContext' user_phone: type: string description: Customer's phone number user_country_code_iso2: type: string description: Customer's country — 2 uppercase ISO 3166-1 letters external_order_ref: type: string maxLength: 255 description: Your external order reference ID description: type: string description: Human-readable description of the order integration_type: type: string enum: - full_checkout - embedding default: full_checkout description: >- How the card is collected. full_checkout = hosted redirect; embedding = mount the iframe via the SDK. callback_url: type: string maxLength: 2048 description: >- For hosted checkout: the https URL Prava redirects the cardholder to after they finish. card: type: object description: Pre-select a card for the session properties: card_id: type: string description: An existing enrolled card ID vault_ref_id: type: string format: uuid description: A valid UUID referencing a vaulted card CreateSessionResponse: type: object properties: session_id: type: string description: Unique session identifier session_token: type: string description: JWT to authenticate client-side SDK operations within this session iframe_url: type: string description: URL for the secure card collection surface order_id: type: string description: Internal order identifier expires_at: type: string format: date-time description: ISO 8601 timestamp when the session expires PurchaseContext: type: object required: - merchant_details - product_details properties: merchant_details: type: object required: - name - url - country_code_iso2 properties: name: type: string description: Merchant display name url: type: string description: Merchant website URL country_code_iso2: type: string description: Two uppercase ISO 3166-1 country code (e.g. "US") category_code: type: string maxLength: 10 description: Merchant category code category: type: string maxLength: 100 description: Merchant category description product_details: type: array minItems: 1 items: type: object required: - description - unit_price properties: description: type: string description: Product description unit_price: type: string description: Unit price as a string (e.g. "49.99") product_id: type: string maxLength: 50 description: Your external product identifier quantity: type: integer default: 1 description: Quantity of this product effective_until_minutes: type: integer default: 15 description: How long the mandate remains effective, in minutes. Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code (e.g. VAL_2001, AUTH_1001) message: type: string description: Human-readable error message details: type: object description: >- Optional — included for validation errors to specify which fields failed responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your secret key: sk_test_* (sandbox) or sk_live_* (production).' ````