> ## 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 payment by ID > Returns payment details. Use query parameter `include=instrument,operations` to expand instrument and/or operations in the response. ## OpenAPI ````yaml /openapi/payment-acceptance.json get /payments/{payment_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: /payments/{payment_id}: get: tags: - Server-to-Server Payments summary: Get payment by ID description: > Returns payment details. Use query parameter `include=instrument,operations` to expand instrument and/or operations in the response. operationId: lite.server-to-server.getPayment parameters: - $ref: '#/components/parameters/payment_id' - $ref: '#/components/parameters/x-correlation-id' - $ref: '#/components/parameters/include' responses: '200': $ref: '#/components/responses/PaymentResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: payment_id: name: payment_id in: path required: true description: Unique identifier of the payment schema: type: string format: uuid example: 9822ffb8-26de-423b-ad15-0d129cf1b4ac 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 include: in: query name: include required: false schema: type: array items: type: string enum: - instrument - operations description: Comma-separated list of related resources to include style: form explode: false responses: PaymentResponse: description: Payment details. content: application/json: schema: type: object required: - payment properties: payment: $ref: '#/components/schemas/Payment' next_action: type: object description: >- Next action for the client (present only when action is required) properties: redirect: type: object properties: method: type: string description: HTTP method for the redirect example: GET url: type: string format: uri description: Redirect URL for 3DS challenge _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' 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' schemas: Payment: type: object required: - id - merchant_id - amount - currency - status - created_at properties: id: type: string format: uuid description: Unique payment identifier example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 merchant_id: type: string format: uuid description: Merchant ID example: f3baf375-1cac-4aa2-bd36-0d7ca49ef59b amount: type: integer description: Payment amount in minor units example: 10000 currency: type: string description: Currency code (ISO 4217) example: SAR status: type: string description: Payment status example: PENDING oneOf: - title: Created const: CREATED description: Payment has been created and queued for processing - title: Pending const: PENDING description: Payment is being processed - title: Authorized const: AUTHORIZED description: Payment has been authorized but not yet captured - title: Failed const: FAILED description: Payment processing failed - title: Expired const: EXPIRED description: Payment authorization has expired - title: Authorization Reversed const: AUTHORIZATION_REVERSED description: Authorization was reversed before capture - title: Voided const: VOIDED description: Payment was voided after authorization - title: Partially Captured const: PARTIALLY_CAPTURED description: Only part of the authorized amount was captured - title: Captured const: CAPTURED description: Full authorized amount has been captured - title: Refunded const: REFUNDED description: Payment has been fully refunded - title: Disputed const: DISPUTED description: Payment is disputed by the cardholder - title: Dispute Challenged const: DISPUTE_CHALLENGED description: Merchant has challenged the dispute - title: Arbitration Initiated const: ARBITRATION_INITIATED description: Dispute has escalated to arbitration - title: Arbitration Lost const: ARBITRATION_LOST description: Merchant lost the arbitration - title: Chargeback const: CHARGEDBACK description: Funds were reclaimed via chargeback - title: Requires Action const: REQUIRES_ACTION description: Payment requires merchant action to proceed 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 capture_mode: type: string description: Capture mode example: MANUAL oneOf: - title: Instant const: INSTANT description: Payment was captured immediately upon authorization - title: Manual const: MANUAL description: Payment was captured manually after authorization payment_instrument_id: type: string format: uuid description: Payment instrument ID example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 payment_method: type: string description: Payment method example: CARD oneOf: - title: Card const: CARD description: Credit or debit card payment - title: Apple Pay const: APPLE_PAY description: Apple Pay digital wallet - title: Google Pay const: GOOGLE_PAY description: Google Pay digital wallet - title: Samsung Pay const: SAMSUNG_PAY description: Samsung Pay digital wallet - title: Mastercard Digital Enablement Service const: MDES description: Mastercard digital wallet token - title: Secure Card on File const: SCOF description: Secure card-on-file token - title: Visa Token Service const: VTS description: Visa digital wallet token - title: Visa Click to Pay const: VCOF description: Visa card-on-file token - title: IBAN const: IBAN description: IBAN-based bank transfer risk: type: object description: Risk assessment data and result properties: data: type: object description: Risk input configuration properties: enabled: type: boolean description: Whether risk assessment was enabled example: true device_session_id: type: string description: Device session ID example: sess_abc123 result: type: object description: Risk assessment result properties: score: type: integer description: Risk assessment score example: 75 customer: $ref: '#/components/schemas/Customer' order: $ref: '#/components/schemas/Order' device: $ref: '#/components/schemas/Device' threeds: type: object description: 3DS authentication data and result properties: data: type: object description: 3DS input configuration properties: authentication_value: type: string eci: type: string version: type: string ds_transaction_id: type: string trans_status: type: string xid: type: string result: type: object description: 3DS authentication result properties: authentication_status: type: string description: 3DS authentication status example: 'Y' challenge_required: type: boolean description: Whether challenge was required eci: type: string description: Electronic Commerce Indicator example: '05' authentication_value: type: string description: Cardholder Authentication Verification Value xid: type: string description: Transaction identifier (XID) version: type: string description: 3DS version ds_trans_id: type: string format: uuid description: Directory Server Transaction ID example: 550e8400-e29b-41d4-a716-446655440000 acs_trans_id: type: string description: ACS Transaction ID return_info: type: object description: Return URLs properties: success: type: string format: uri example: https://example.com/success cancel: type: string format: uri example: https://example.com/cancel error: type: string format: uri example: https://example.com/error metadata: type: object description: Additional metadata created_at: type: string format: date-time description: Creation timestamp example: '2026-04-08T20:53:45.517Z' instrument: type: object description: Payment instrument details (returned when include=instrument) properties: id: type: string description: Instrument ID type: type: string description: Instrument type last_four_digits: type: string description: Last four digits of the card example: '1111' brand: type: string description: Card brand example: mada expiry_month: type: integer description: Card expiry month example: 12 expiry_year: type: integer description: Card expiry year example: 27 cardholder_name: type: string description: Cardholder name fingerprint: type: string description: Card fingerprint future_usage: type: string description: >- Indicates whether and how the card details should be saved and reused for future payments. oneOf: - title: Unscheduled Card on File const: unscheduled_card_on_file description: >- Store the card for future unscheduled transactions (e.g., single merchant-initiated payments, top-ups). - title: Recurring const: recurring description: >- Store the card for recurring payments (e.g., subscriptions, installment plans with a fixed schedule). - title: Unscheduled const: unscheduled description: >- Store the card for one-off future transactions where the amount or timing is not predetermined. agreement_id: type: string description: Agreement ID created_at: type: string format: date-time description: Creation timestamp operations: type: array description: Payment operations (returned when include=operations) items: type: object required: - id - payment_id - operation_type - status - amount - currency - created_at - updated_at properties: id: type: string format: uuid description: Operation ID payment_id: type: string format: uuid description: Payment ID idempotency_key: type: string format: uuid description: Idempotency key operation_type: type: string description: Operation type example: CAPTURE oneOf: - title: Authorize const: AUTHORIZE description: Authorization of the payment amount - title: Capture const: CAPTURE description: Capture of an authorized payment - title: Refund const: REFUND description: Refund of a captured payment - title: Void const: VOID description: Reversal of an authorization before capture - title: Reverse const: REVERSE description: Reversal of a captured payment status: type: string description: Operation status example: SUCCESS oneOf: - title: Pending const: PENDING description: Operation is queued or in progress - title: Success const: SUCCESS description: Operation completed successfully - title: Failure const: FAILURE description: Operation failed amount: type: integer description: Operation amount in minor units example: 10000 currency: type: string description: Currency code example: SAR reason: type: string description: Failure reason initiated_by: type: string description: Who initiated the operation connector_type: type: string description: Gateway connector type connector_response_code: type: string description: Gateway response code connector_response_message: type: string description: Gateway response message connector_transaction_id: type: string description: Gateway transaction ID http_status_code: type: integer description: Gateway HTTP status code processing_duration_ms: type: integer description: Processing duration in milliseconds retry_count: type: integer description: Number of retries max_retries: type: integer description: Maximum retries next_retry_at: type: string format: date-time description: Next retry timestamp created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp 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' 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 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' 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 . ````