> ## 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 payment > Initiates a payment request for processing. Returns immediately with an accepted response; the payment is processed asynchronously. `payment_instrument` accepts three shapes at the gateway: 1. `{ "id": "" }` — use an existing instrument 2. `{ "payment_method", "pan_data", ... }` — gateway tokenizes card data first 3. `{ "payment_method", "data", ... }` — gateway tokenizes encrypted payload first Inline tokenization requires `customer.id`. The payment service always receives `payment_instrument.id` after gateway processing. ## OpenAPI ````yaml /openapi/payment-acceptance.json post /payments 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: /payments: post: tags: - Server-to-Server Payments summary: Create a new payment description: > Initiates a payment request for processing. Returns immediately with an accepted response; the payment is processed asynchronously. `payment_instrument` accepts three shapes at the gateway: 1. `{ "id": "" }` — use an existing instrument 2. `{ "payment_method", "pan_data", ... }` — gateway tokenizes card data first 3. `{ "payment_method", "data", ... }` — gateway tokenizes encrypted payload first Inline tokenization requires `customer.id`. The payment service always receives `payment_instrument.id` after gateway processing. operationId: lite.server-to-server.createPayment parameters: - $ref: '#/components/parameters/x-correlation-id' - $ref: '#/components/parameters/x-idempotency-key' requestBody: $ref: '#/components/requestBodies/CreatePayment' responses: '202': $ref: '#/components/responses/PaymentAccepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' 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: CreatePayment: description: Create a new payment required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentRequest' examples: instrumentId: $ref: '#/components/examples/create-payment-instrument-id' panData: $ref: '#/components/examples/create-payment-pan-data' encryptedData: $ref: '#/components/examples/create-payment-encrypted-data' responses: PaymentAccepted: description: Payment accepted for processing. content: application/json: schema: type: object required: - payment properties: payment: type: object required: - id properties: id: type: string format: uuid description: Unique payment identifier example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 status: type: string description: Payment status enum: - CREATED - PENDING example: PENDING merchant_reference: type: string description: Merchant order reference example: ORD-123456 _links: type: object description: Available action links (HATEOAS) properties: self: $ref: '#/components/schemas/Link' capture: $ref: '#/components/schemas/Link' void: $ref: '#/components/schemas/Link' refund: $ref: '#/components/schemas/Link' redirect: $ref: '#/components/schemas/Link' 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' 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' 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: CreatePaymentRequest: oneOf: - title: Existing instrument description: | Pay with a previously tokenized instrument. The gateway forwards `payment_instrument.id` as-is; `customer` is optional. allOf: - $ref: '#/components/schemas/CreatePaymentRequestFields' - type: object required: - payment_instrument properties: payment_instrument: $ref: '#/components/schemas/PaymentInstrumentById' - title: Inline PAN data description: > Gateway-side card tokenization from inline `pan_data`. Requires `customer.id` as the instrument holder ID. The gateway forwards only `payment_instrument.id` to payment-v2 after instrument creation. allOf: - $ref: '#/components/schemas/CreatePaymentRequestFields' - type: object required: - payment_instrument - customer properties: payment_instrument: $ref: '#/components/schemas/PaymentInstrumentWithPanData' customer: allOf: - $ref: '#/components/schemas/Customer' - type: object required: - id - title: Encrypted instrument data description: > Gateway-side tokenization from encrypted `data`. Requires `customer.id` as the instrument holder ID. The gateway forwards only `payment_instrument.id` to payment-v2 after instrument creation. allOf: - $ref: '#/components/schemas/CreatePaymentRequestFields' - type: object required: - payment_instrument - customer properties: payment_instrument: $ref: '#/components/schemas/PaymentInstrumentWithEncryptedData' customer: allOf: - $ref: '#/components/schemas/Customer' - type: object required: - id 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 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' CreatePaymentRequestFields: type: object required: - amount - currency - device properties: amount: type: integer minimum: 1 description: Payment amount in minor units (e.g. 10000 for 100.00 SAR) example: 10000 currency: type: string description: Currency code (ISO 4217) example: SAR processing: type: object description: Processing details properties: processing_type: type: string description: Processing type example: REGULAR oneOf: - title: Regular const: REGULAR description: Standard one-time payment - title: Card on File const: CARD_ON_FILE description: Payment using previously stored card details - title: Unscheduled Card on File const: UNSCHEDULED_CARD_ON_FILE description: Payment using card on file without a fixed schedule initiator: type: string description: Who initiated the transaction example: CARD_HOLDER oneOf: - title: Card Holder const: CARD_HOLDER description: Transaction initiated by the cardholder (customer-present) - title: Merchant const: MERCHANT description: Transaction initiated by the merchant (merchant-initiated) capture_options: type: object description: Capture options required: - capture_mode properties: capture_mode: type: string description: Whether to capture automatically (INSTANT) or manually (MANUAL) example: MANUAL oneOf: - title: Instant const: INSTANT description: Capture the payment immediately upon authorization - title: Manual const: MANUAL description: Capture the payment manually at a later time order: $ref: '#/components/schemas/Order' customer: $ref: '#/components/schemas/Customer' device: $ref: '#/components/schemas/Device' threeds: type: object description: 3DS settings properties: force: type: boolean description: Force 3DS authentication regardless of risk engine decision example: true data: type: object description: 3DS authentication data (for pre-authenticated 3DS) required: - authentication_value - eci - version - ds_transaction_id - trans_status properties: authentication_value: type: string description: Cardholder Authentication Verification Value example: AAABBJkZUgAAAAAAAAAAAAAAAAA= eci: type: string minLength: 2 maxLength: 2 description: Electronic Commerce Indicator example: '05' version: type: string description: 3DS protocol version example: 2.1.0 ds_transaction_id: type: string description: Directory Server Transaction ID example: dstxn_a1b2c3d4e5f6 trans_status: type: string pattern: ^[A-Z]$ description: Transaction status from 3DS authentication example: 'Y' xid: type: string description: Transaction identifier (XID), primarily for 3DS v1 example: abc123xyz risk: type: object description: Risk assessment data properties: enabled: type: boolean description: Whether risk assessment is enabled example: true device_session_id: type: string description: Device session ID for risk assessment example: sess_abc123 return_info: type: object description: Return URLs properties: success: type: string format: uri description: Success URL example: https://example.com/success cancel: type: string format: uri description: Cancel URL example: https://example.com/cancel error: type: string format: uri description: Error URL example: https://example.com/error metadata: type: object description: Additional metadata example: custom_field: value channel_id: type: string format: uuid description: Channel ID for the payment example: 019859f8-3149-7a55-8211-a8179675d269 PaymentInstrumentById: type: object description: Reference an existing tokenized payment instrument by ID. required: - id properties: id: type: string format: uuid description: >- Instrument ID returned by a previous tokenization or instrument creation call. example: e835c96f-3ede-47ff-85e3-3515b7ac125f PaymentInstrumentWithPanData: type: object description: > Inline card data nested under `payment_instrument`. The gateway tokenizes the card via instrument-service before forwarding the payment request with `payment_instrument.id` only. `holder_id` is derived from `customer.id` and must not be sent by the client. required: - payment_method - pan_data properties: payment_method: type: string description: Payment method type example: card oneOf: - title: Card const: card description: Credit or debit card pan_data: $ref: '#/components/schemas/PanData' future_usage: type: string description: Optional future usage intent for card-on-file storage. example: recurring oneOf: - title: Unscheduled Card on File const: unscheduled_card_on_file - title: Recurring const: recurring - title: Unscheduled const: unscheduled agreement: $ref: '#/components/schemas/Agreement' 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' PaymentInstrumentWithEncryptedData: type: object description: > Encrypted card payload nested under `payment_instrument`. The gateway creates an instrument via instrument-service before forwarding the payment request with `payment_instrument.id` only. `holder_id` is derived from `customer.id` and must not be sent by the client. required: - payment_method - data properties: payment_method: type: string description: Payment method type example: card oneOf: - title: Card const: card description: Credit or debit card data: type: string description: Encrypted instrument payload (for example a JWE token). example: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0... future_usage: type: string description: Optional future usage intent for card-on-file storage. example: unscheduled_card_on_file oneOf: - title: Unscheduled Card on File const: unscheduled_card_on_file - title: Recurring const: recurring - title: Unscheduled const: unscheduled 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 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' PanData: type: object description: PAN (Primary Account Number) data for card tokenization required: - card_number - expiry_month - expiry_year - cvc - holder_name properties: card_number: type: string description: Card number (PAN) pattern: ^\d{13,19}$ minLength: 13 maxLength: 19 example: '4111111111111111' expiry_month: type: string description: Expiry month (MM) pattern: ^(0[1-9]|1[0-2])$ example: '12' expiry_year: type: string description: Expiry year (YY) pattern: ^\d{2}$ example: '30' cvc: type: string description: Card verification code pattern: ^\d{3,4}$ minLength: 3 maxLength: 4 example: '123' holder_name: type: string description: Cardholder name maxLength: 255 example: John Doe Agreement: type: object description: Card-on-file agreement details for recurring or unscheduled transactions properties: reference: type: string description: Agreement ID defined by merchant example: custom-reference initial_transaction_reference: type: string description: Reference of the initial transaction that established the agreement example: transaction-reference-xxx consent: $ref: '#/components/schemas/AgreementConsent' 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 AgreementConsent: type: object description: Consent details for card-on-file agreement required: - disclosure_version - accepted_at - ip_address - user_agent properties: disclosure_version: type: string description: Version of the disclosure shown to the cardholder example: v1.2 accepted_at: type: string format: date-time description: Timestamp when consent was accepted example: '2025-03-08T12:22:11Z' ip_address: oneOf: - type: string format: ipv4 description: IPv4 address example: 203.0.113.42 - type: string format: ipv6 description: IPv6 address example: 2001:db8::1 user_agent: type: string description: User agent of the cardholder's browser at time of consent example: Mozilla/5.0 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 examples: create-payment-instrument-id: summary: Create payment with an existing instrument ID value: amount: 10000 currency: SAR device: ip: 203.0.113.42 user_agent: Mozilla/5.0 customer: id: 06463cf8-c156-4ff6-bf02-5d559b738718 payment_instrument: id: e835c96f-3ede-47ff-85e3-3515b7ac125f create-payment-pan-data: summary: Create payment with inline PAN data (gateway tokenizes first) value: amount: 10000 currency: SAR device: ip: 203.0.113.42 user_agent: Mozilla/5.0 customer: id: 06463cf8-c156-4ff6-bf02-5d559b738718 payment_instrument: payment_method: card pan_data: card_number: '5186001700008785' expiry_month: '12' expiry_year: '34' cvc: '123' holder_name: John Doe future_usage: recurring agreement: reference: '12345' create-payment-encrypted-data: summary: Create payment with encrypted instrument data (gateway tokenizes first) value: amount: 10000 currency: SAR device: ip: 203.0.113.42 user_agent: Mozilla/5.0 customer: id: 06463cf8-c156-4ff6-bf02-5d559b738718 payment_instrument: payment_method: card future_usage: unscheduled_card_on_file data: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.example.payload 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 . ````