> ## 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. # Create a new 3DS Authentication session > Start a new 3DS authentication session to authenticate a payer ## OpenAPI ````yaml /openapi/payment-acceptance.json post /threeds/authentications 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: /threeds/authentications: post: tags: - 3DS Authentication summary: Create a new 3DS Authentication session description: | Start a new 3DS authentication session to authenticate a payer operationId: lite.3ds.createAuthentication parameters: - $ref: '#/components/parameters/x-correlation-id' - $ref: '#/components/parameters/x-idempotency-key' requestBody: $ref: '#/components/requestBodies/CreateAuthentication' responses: '201': $ref: '#/components/responses/AuthenticationCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: parameters: 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 x-idempotency-key: name: x-idempotency-key in: header required: false description: >- Unique key for idempotent request processing. Duplicate requests with the same key are safely ignored. schema: type: string format: uuid example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 requestBodies: CreateAuthentication: description: Create a new 3DS authentication session content: application/json: schema: $ref: '#/components/schemas/CreateAuthenticationRequest' responses: AuthenticationCreated: description: Authentication session created. content: application/json: schema: $ref: '#/components/schemas/AuthenticationSession' BadRequest: description: > The request was invalid or malformed. Returned when: - Request validation fails (missing required fields, invalid field formats) - Payment details do not match the session (amount, currency, order reference mismatch) - The operation is not allowed given the current resource state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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' schemas: CreateAuthenticationRequest: type: object required: - instrument_id - customer - order - return_url properties: instrument_id: type: string format: uuid description: Instrument ID example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 device: $ref: '#/components/schemas/Device' customer: $ref: '#/components/schemas/Customer' order: $ref: '#/components/schemas/Order' return_url: type: string format: uri description: Return URL for 3DS challenge completion example: https://example.com/threeds/callback AuthenticationSession: type: object required: - id - merchant_id - instrument_id - status properties: id: type: string format: uuid description: Unique 3DS authentication ID example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 merchant_id: type: string format: uuid description: Merchant ID example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 instrument_id: type: string format: uuid description: Instrument ID example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 status: type: string description: 3DS authentication status example: AUTHENTICATED oneOf: - title: Pending const: PENDING description: >- Authentication session has been created and is awaiting processing - title: Challenge Required const: CHALLENGE_REQUIRED description: Cardholder must complete a 3DS challenge for authentication - title: Authenticated const: AUTHENTICATED description: Cardholder was successfully authenticated - title: Expired const: EXPIRED description: Authentication session expired before completion - title: Failed const: FAILED description: Authentication failed or was rejected authentication_value: type: string description: Authentication value (CAVV) example: AAABBJkZUgAAAAAAAAAAAAAAAAA= eci: type: string minLength: 2 maxLength: 2 description: Electronic Commerce Indicator example: '05' xid: type: string minLength: 1 maxLength: 100 description: Transaction identifier (XID) example: abc123xyz version: type: string pattern: ^\d+\.\d+\.\d+$ description: 3DS protocol version example: 2.1.0 threeds_server_trans_id: type: string description: 3DS Server transaction ID example: threeds_a1b2c3d4e5f6 ds_transaction_id: type: string description: Directory Server transaction ID example: dstxn_a1b2c3d4e5f6 acs_transaction_id: type: string description: ACS transaction ID example: acstxn_a1b2c3d4e5f6 acs_reference_number: type: string minLength: 1 maxLength: 32 description: ACS reference number example: ELAVON_ACS_EMULATOR_REF_NUMBER32 ds_reference_number: type: string minLength: 1 maxLength: 32 description: Directory Server reference number example: ELAVON_3DS_DS_EMULATOR_REF_NUM32 acs_operator_id: type: string minLength: 1 maxLength: 32 description: ACS operator ID example: ELAVON_ACS_EMULATOR_OPERATOR_ID1 acs_challenge_mandated: type: string description: Whether a challenge is required example: 'Y' oneOf: - title: 'Yes' const: 'Y' description: Challenge is mandated - title: 'No' const: 'N' description: Challenge is not mandated acs_authentication_type: type: string minLength: 2 maxLength: 10 description: ACS authentication type code example: '01' acs_challenge_cancel_reason: type: string description: Challenge cancel reason code example: '01' trans_status: type: string pattern: ^[A-Z]$ description: Transaction status code example: C trans_status_reason: type: string description: Transaction status reason example: '01' return_url: type: string description: Return URL for 3DS challenge example: https://example.com/threeds/callback 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' Device: type: object description: Device information (required for 3DS and risk assessment) required: - ip - user_agent - accept_header - language - screen_height - screen_width - color_depth - timezone - java_enabled - java_script_enabled properties: ip: type: string description: Device IP address example: 192.168.1.100 user_agent: type: string description: User agent string example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 accept_header: type: string description: Accept header from HTTP request example: text/html,application/xhtml+xml,application/xml;q=0.9 language: type: string description: Browser language setting example: en-US screen_height: type: integer description: Screen height in pixels example: 1080 screen_width: type: integer description: Screen width in pixels example: 1920 color_depth: type: integer description: Color depth in bits example: 24 timezone: type: integer description: Timezone offset in minutes example: -180 java_enabled: type: boolean description: Whether Java is enabled in the browser example: false java_script_enabled: type: boolean description: Whether JavaScript is enabled in the browser example: true device_data: type: object description: Opaque device metadata payload device_fingerprint: type: string description: Device fingerprint identifier example: fp_123 ip_country: type: string description: IP country code example: SA ip_city: type: string description: IP city example: Riyadh ip_region: type: string description: IP region example: Riyadh Region ip_postal_code: type: string description: IP postal code example: '12213' ip_latitude: type: number description: IP latitude example: 24.7136 ip_longitude: type: number description: IP longitude example: 46.6753 terminal_id: type: string description: Terminal ID example: '1234567890123456' 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 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 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 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 . ````