> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lite.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a checkout session

> Retrieves a checkout session with full details including available payment
methods, checkout configuration, and HATEOAS action links.




## OpenAPI

````yaml /openapi/payment-acceptance.json get /checkout/sessions/{session_id}
openapi: 3.1.0
info:
  title: lite - Payment Acceptance
  version: 1.0.0
servers:
  - url: https://api.lite.sa/v1
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: 3DS Authentication
    description: Standalone payer authentication via the 3DS standard
  - name: Hosted Checkout
    description: Create, manage and deploy hosted checkout pages
  - name: Server-to-Server Payments
    description: Direct payment API for server-side integrations
paths:
  /checkout/sessions/{session_id}:
    get:
      tags:
        - Hosted Checkout
      summary: Get a checkout session
      description: >
        Retrieves a checkout session with full details including available
        payment

        methods, checkout configuration, and HATEOAS action links.
      operationId: lite.checkout.getSession
      parameters:
        - $ref: '#/components/parameters/session_id'
        - $ref: '#/components/parameters/x-correlation-id'
        - name: with_config
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Whether to include checkout configuration and payment methods
      responses:
        '200':
          $ref: '#/components/responses/SessionDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    session_id:
      name: session_id
      in: path
      required: true
      description: Unique identifier of the checkout session
      schema:
        type: string
        example: ses_a1b2c3d4e5f6
    x-correlation-id:
      name: x-correlation-id
      in: header
      required: false
      description: >-
        Unique identifier for request tracing. Generated by the client or server
        if not provided.
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    SessionDetails:
      description: Checkout session details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckoutSessionDetails'
    Unauthorized:
      description: |
        Authentication failed — missing or invalid token.

        Returned when:
        - The JWT bearer token is missing, expired, or has an invalid signature
        - The API key is missing or invalid
        - The authenticated session token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >
        Request blocked by security policy.


        Returned when:

        - A security threat is detected (SQL injection, XSS, NoSQL injection,
        LDAP injection, path traversal)

        - Header injection or suspicious headers are detected

        - The request payload exceeds the maximum allowed size

        - Geo-region validation fails (user country does not match client
        region)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: |
        The requested resource was not found.

        Returned when:
        - The specified resource ID does not exist
        - The path does not match any known endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: >
        An unexpected error occurred on the server.


        Returned when an unhandled exception or infrastructure failure prevents
        the request from being processed. Retry the request with exponential
        backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CheckoutSessionDetails:
      type: object
      description: Full checkout session details
      required:
        - id
        - status
        - expires_on
        - order_id
        - amount
        - currency
        - three_ds_required
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique checkout session identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        session_id:
          type: string
          description: Deprecated — use id instead
          example: ses_a1b2c3d4e5f6
        status:
          $ref: '#/components/schemas/CheckoutSessionStatus'
        expires_on:
          type: string
          format: date-time
          description: Session expiry timestamp
          example: '2026-05-18T12:00:00.000Z'
        order_id:
          type: string
          description: Order reference
          example: ORD-123456
        amount:
          type: integer
          description: Session amount in minor units
          example: 10000
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: SAR
        redirect_urls:
          $ref: '#/components/schemas/RedirectUrls'
        three_ds_required:
          type: boolean
          description: Whether 3DS authentication is required
          example: true
        customer:
          $ref: '#/components/schemas/Customer'
        order:
          $ref: '#/components/schemas/Order'
        metadata:
          type: object
          description: Additional metadata
          example:
            session_type: standard
        payment_methods:
          $ref: '#/components/schemas/CheckoutPaymentMethods'
        checkout_config:
          $ref: '#/components/schemas/CheckoutConfig'
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2026-05-17T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2026-05-17T12:00:00.000Z'
        _links:
          $ref: '#/components/schemas/CheckoutSessionLinks'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - timestamp
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: PAYMENT_DETAILS_MISMATCH
            message:
              type: string
              description: Human-readable error description
              example: The request was invalid or malformed
            details:
              type: object
              description: Additional error details
            correlationId:
              type: string
              format: uuid
              description: Correlation ID for tracking the request
              example: 550e8400-e29b-41d4-a716-446655440000
            timestamp:
              type: string
              format: date-time
              description: Timestamp when the error occurred
              example: '2024-12-16T10:30:00.000Z'
    CheckoutSessionStatus:
      type: string
      description: Session status
      example: Pending
      oneOf:
        - title: Pending
          const: Pending
          description: Session is active and awaiting payment
        - title: Completed
          const: Completed
          description: Session has been completed
        - title: Expired
          const: Expired
          description: Session has expired
        - title: Cancelled
          const: Cancelled
          description: Session was explicitly cancelled
    RedirectUrls:
      type: object
      description: Redirect URLs for checkout session
      properties:
        success:
          type: string
          format: uri
          description: Redirect URL on successful payment
          example: https://example.com/success
        failure:
          type: string
          format: uri
          description: Redirect URL on failed payment
          example: https://example.com/failure
    Customer:
      type: object
      description: Customer details
      properties:
        id:
          type: string
          description: Customer ID
          example: cust_a1b2c3d4e5f6
        email:
          type: string
          format: email
          description: Customer email
          example: donald.duck@duckworld.com
        first_name:
          type: string
          description: Customer first name
          example: Donald
        last_name:
          type: string
          description: Customer last name
          example: Duck
        phone_country_code:
          type: string
          description: Phone country code
          example: '+966'
        phone_number:
          type: string
          description: Phone number
          example: '555123456'
    Order:
      type: object
      description: Order details
      required:
        - reference
      properties:
        reference:
          type: string
          description: Order reference
          example: ORD-123456
        items:
          $ref: '#/components/schemas/OrderItems'
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        amount:
          type: integer
          description: Order amount in minor units
          minimum: 0
          example: 10000
        currency:
          type: string
          description: Currency code (ISO 4217)
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          example: SAR
        description:
          type: string
          description: Order description
          example: Order description
    CheckoutPaymentMethods:
      type: object
      description: Available payment methods for the checkout session
      properties:
        card:
          $ref: '#/components/schemas/CardMethod'
        apple_pay:
          $ref: '#/components/schemas/WalletMethod'
        google_pay:
          $ref: '#/components/schemas/WalletMethod'
        samsung_pay:
          $ref: '#/components/schemas/WalletMethod'
    CheckoutConfig:
      type: object
      description: Checkout page configuration
      properties:
        locale:
          type: string
          description: Checkout page locale (ISO 639-1, optionally with region)
          pattern: ^[a-z]{2}(-[A-Z]{2})?$
          example: en
        redirect_urls:
          type: object
          description: Checkout page redirect URLs
          properties:
            success:
              type: string
              format: uri
              description: Redirect URL on success
              example: https://example.com/success
            failure:
              type: string
              format: uri
              description: Redirect URL on failure
              example: https://example.com/failure
            cancel:
              type: string
              format: uri
              description: Redirect URL on cancel
              example: https://example.com/cancel
        theme:
          type: object
          description: Checkout page theme configuration
          properties:
            primaryColor:
              type: string
              description: Primary color in hex format
              pattern: ^#[0-9A-Fa-f]{6}$
              example: '#0056D2'
            secondaryColor:
              type: string
              description: Secondary color in hex format
              pattern: ^#[0-9A-Fa-f]{6}$
              example: '#0041A5'
            backgroundColor:
              type: string
              description: Background color in hex format
              pattern: ^#[0-9A-Fa-f]{6}$
              example: '#FFFFFF'
            fontFamily:
              type: string
              description: Font family for the checkout page
              example: Arial, sans-serif
            logoUrl:
              type: string
              format: uri
              description: URL to the merchant's logo
              example: https://example.com/logo.png
    CheckoutSessionLinks:
      type: object
      description: HATEOAS links for checkout session actions
      properties:
        self:
          $ref: '#/components/schemas/Link'
        tokenize:
          $ref: '#/components/schemas/Link'
        authorize:
          $ref: '#/components/schemas/Link'
        start_payment_session:
          $ref: '#/components/schemas/Link'
        payment:
          $ref: '#/components/schemas/Link'
    OrderItems:
      type: object
      description: Order line items
      properties:
        products:
          type: array
          description: Product line items
          items:
            $ref: '#/components/schemas/Product'
        vat:
          type: object
          description: VAT details
          properties:
            amount:
              type: integer
              description: VAT amount in minor units
              minimum: 0
              example: 750
        shipping:
          type: object
          description: Shipping details
          properties:
            amount:
              type: integer
              description: Shipping amount in minor units
              minimum: 0
              example: 1000
    Address:
      type: object
      description: Address information
      properties:
        name:
          type: string
          description: Contact name
          example: John Doe
        email:
          type: string
          format: email
          description: Email
          example: john@example.com
        street:
          type: string
          description: Street address
          example: 123 Main St
        city:
          type: string
          description: City
          example: Riyadh
        state:
          type: string
          description: State/region
          example: Riyadh Region
        zip:
          type: string
          description: Zip/postal code
          example: '12213'
        country:
          type: string
          description: Country code (ISO 3166 alpha-2)
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: SA
    CardMethod:
      type: object
      description: Card payment method with checkout configuration
      properties:
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          oneOf:
            - title: Active
              const: ACTIVE
              description: Payment method is available
            - title: Inactive
              const: INACTIVE
              description: Payment method is not available
        config:
          $ref: '#/components/schemas/CardConfig'
        stored_instruments:
          type: array
          description: Stored payment instruments
          items:
            $ref: '#/components/schemas/StoredInstrument'
    WalletMethod:
      type: object
      description: Digital wallet payment method
      properties:
        status:
          type: string
          description: Payment method status
          example: ACTIVE
          oneOf:
            - title: Active
              const: ACTIVE
              description: Payment method is available
            - title: Inactive
              const: INACTIVE
              description: Payment method is not available
        dependencies:
          $ref: '#/components/schemas/WalletDependencies'
    Link:
      type: object
      required:
        - href
        - method
      properties:
        href:
          type: string
          format: uri
          description: Link URL
        method:
          type: string
          description: HTTP method
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
            - HEAD
            - OPTIONS
          example: POST
    Product:
      type: object
      required:
        - id
        - price
        - quantity
      properties:
        id:
          type: string
          description: Item ID
          example: prod_123
        name:
          type: string
          description: Item name
          example: T-Shirt
        price:
          type: integer
          minimum: 0
          description: Item price in minor units
          example: 5000
        quantity:
          type: integer
          minimum: 1
          description: Quantity
          example: 2
        metadata:
          type: object
          description: Item metadata
          example:
            color: Blue
            size: L
    CardConfig:
      type: object
      description: Card method configuration
      properties:
        public_key:
          type: string
          description: Public key for card encryption
          example: pk_live_a1b2c3d4e5f6
        payment_confirmation:
          type: string
          description: Payment confirmation mode
          example: DELAYED
          oneOf:
            - title: Immediate
              const: IMMEDIATE
              description: Payment is confirmed immediately
            - title: Delayed
              const: DELAYED
              description: Payment confirmation is delayed
        networks:
          $ref: '#/components/schemas/CardNetworks'
    StoredInstrument:
      type: object
      description: Stored payment instrument for quick checkout
      properties:
        id:
          type: string
          description: Instrument ID
          example: instr_a1b2c3d4e5f6
        payment_method:
          type: string
          description: Payment method type
          example: card
        holder_type:
          type: string
          description: Cardholder type
          example: primary
        display:
          $ref: '#/components/schemas/InstrumentDisplay'
    WalletDependencies:
      type: object
      description: Wallet method dependencies
      properties:
        merchant_identifier:
          type: string
          description: Merchant identifier for the wallet provider
          example: merchant.com.live
        service_id:
          type: string
          description: Service identifier for the wallet provider
          example: srv_a1b2c3d4e5f6
    CardNetworks:
      type: object
      description: Supported card networks
      properties:
        mada:
          type: boolean
          description: Mada network support
          example: true
        visa:
          type: boolean
          description: Visa network support
          example: true
        mastercard:
          type: boolean
          description: Mastercard network support
          example: true
    InstrumentDisplay:
      type: object
      description: Card display information for stored instruments
      properties:
        expiry_year:
          type: string
          description: Card expiry year (YY)
          pattern: ^\d{2}$
          example: '27'
        expiry_month:
          type: string
          description: Card expiry month (MM)
          pattern: ^(0[1-9]|1[0-2])$
          example: '12'
        scheme:
          type: string
          description: Card scheme/brand
          example: mada
        last_4:
          type: string
          description: Last four digits of the card
          pattern: ^\d{4}$
          example: '1111'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for service-to-service or merchant authentication.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Bearer token obtained from user authentication. Passed as
        Authorization: Bearer <token>.

````