# Generated. Do not edit.
"openapi": "3.1.0"
"info":
  "title": "LuxPay Wallet API"
  "version": "1.0.0"
  "summary": "Wallet, payments, payouts, settlements and merchant integration API."
  "description": "Source-derived developer contract for the LuxPay wallet and payment runtime. Runtime base URLs are provisioned per environment. Internal Manager and console synchronization routes are intentionally excluded from the public contract."
  "contact":
    "name": "LuxPay Developer Support"
  "license":
    "name": "Proprietary — authorized LuxPay integrations only"
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema"
"servers":
  -
    "url": "https://{apiHost}/v1"
    "description": "LuxPay API endpoint selected per environment"
    "x-placeholder": true
    "variables":
      "apiHost":
        "default": "api.lux.foodtech-pos.com"
        "description": "Production LuxPay API host. Replace only with an officially provisioned environment host."
  -
    "url": "https://sandbox-api.luxpay.example/v1"
    "description": "Sandbox placeholder — use only after an official sandbox host is provisioned"
    "x-placeholder": true
"tags":
  -
    "name": "Health"
    "description": "Public service availability."
  -
    "name": "Authentication"
    "description": "Customer and business-user token issuance."
  -
    "name": "Wallets"
    "description": "Wallet lifecycle, balances and administrative states."
  -
    "name": "Transactions"
    "description": "Deposits, withdrawals, refunds and wallet transaction history."
  -
    "name": "Transfers"
    "description": "Wallet-to-wallet and customer-to-merchant movement."
  -
    "name": "Holds"
    "description": "Temporary reservation and release of wallet funds."
  -
    "name": "Ledger"
    "description": "Immutable ledger access, statements, reversals and integrity."
  -
    "name": "Audit"
    "description": "Wallet audit records."
  -
    "name": "Merchant wallets"
    "description": "Merchant-facing wallet overview, payment links, QR and settlement requests."
  -
    "name": "Payment services"
    "description": "Provider discovery and next-action selection."
  -
    "name": "Payments"
    "description": "Payment initiation, confirmation, status, cancellation and refunds."
  -
    "name": "Payouts"
    "description": "Approval-based payout lifecycle."
  -
    "name": "Settlements"
    "description": "Approval-based wallet settlement lifecycle."
  -
    "name": "Reports"
    "description": "Financial summaries by date range and business scope."
  -
    "name": "Provider webhooks"
    "description": "Inbound provider events with signature and replay protection."
"security":
  -
    "BearerAuth": []
"x-source-repository": "Ibrahimalzoriqi/LuxApi"
"x-source-branch": "production release"
"x-source-reviewed-at": "2026-09-26"
"x-contract-status": "55 documented routes verified present in production LuxApi release; additional production routes remain outside this contract until separately reviewed."
"x-excluded-routes":
  - "/sync/*"
  - "/manager/*"
  - "/launch/*"
  - "merchant portal administration routes"
"x-source-commit": "146e98baa44e34667ac5f7b36d2c0a94860bd63c"
"paths":
  "/health":
    "get":
      "operationId": "getHealth"
      "tags":
        - "Health"
      "summary": "API health"
      "description": "Returns service availability, version and timestamp."
      "x-summary-ar": "حالة الخدمة"
      "x-description-ar": "يعيد حالة الخدمة والإصدار والوقت."
      "x-access-tier": "public"
      "x-rate-limit": "public"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::health"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/HealthEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security": []
  "/auth/customer/register":
    "post":
      "operationId": "registerCustomer"
      "tags":
        - "Authentication"
      "summary": "Register wallet customer"
      "description": "Creates a customer, provisions the initial YER primary wallet and returns a bearer token."
      "x-summary-ar": "تسجيل عميل محفظة"
      "x-description-ar": "ينشئ العميل ومحفظة YER الأساسية ويعيد رمز وصول."
      "x-access-tier": "public"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/UserAuthController.php::customerRegister"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/CustomerAuthEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CustomerRegisterRequest"
  "/auth/customer/login":
    "post":
      "operationId": "loginCustomer"
      "tags":
        - "Authentication"
      "summary": "Customer login"
      "description": "Authenticates a wallet customer by phone and password and returns a bearer token."
      "x-summary-ar": "دخول عميل المحفظة"
      "x-description-ar": "يصادق عميل المحفظة بالهاتف وكلمة المرور ويعيد رمز وصول."
      "x-access-tier": "public"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/UserAuthController.php::customerLogin"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/CustomerAuthEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CustomerLoginRequest"
  "/auth/employee/login":
    "post":
      "operationId": "loginEmployee"
      "tags":
        - "Authentication"
      "summary": "Business employee login"
      "description": "Authenticates a business employee using business scope plus email/phone and password."
      "x-summary-ar": "دخول موظف النشاط"
      "x-description-ar": "يصادق موظف النشاط ضمن نطاق النشاط وبالبريد أو الهاتف وكلمة المرور."
      "x-access-tier": "public"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/UserAuthController.php::employeeLogin"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/EmployeeAuthEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/EmployeeLoginRequest"
  "/wallets":
    "get":
      "operationId": "listWallets"
      "tags":
        - "Wallets"
      "summary": "List accessible wallets"
      "description": "Lists wallets for the authenticated owner context."
      "x-summary-ar": "قائمة المحافظ"
      "x-description-ar": "يعرض المحافظ التي يسمح بها سياق الهوية الموثق."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::index"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletListEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
    "post":
      "operationId": "createWallet"
      "tags":
        - "Wallets"
      "summary": "Create wallet"
      "description": "Creates a wallet for an allowed owner and currency. Owner scope is verified by the backend."
      "x-summary-ar": "إنشاء محفظة"
      "x-description-ar": "ينشئ محفظة لمالك وعملة مسموحين مع التحقق من النطاق في الخادم."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::create"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreateWalletRequest"
  "/wallets/users":
    "post":
      "operationId": "createCustomerWallet"
      "tags":
        - "Wallets"
      "summary": "Create customer wallet"
      "description": "Creates a primary wallet for an existing customer."
      "x-summary-ar": "إنشاء محفظة عميل"
      "x-description-ar": "ينشئ محفظة أساسية لعميل موجود."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::createUserWallet"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreateCustomerWalletRequest"
  "/wallets/{walletId}":
    "get":
      "operationId": "getWallet"
      "tags":
        - "Wallets"
      "summary": "Get wallet"
      "description": "Returns one wallet after business-scope authorization."
      "x-summary-ar": "تفاصيل المحفظة"
      "x-description-ar": "يعيد محفظة واحدة بعد التحقق من نطاق النشاط."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::show"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/balance":
    "get":
      "operationId": "getWalletBalance"
      "tags":
        - "Wallets"
      "summary": "Get wallet balance"
      "description": "Returns cached, held, pending and available balances with verification time."
      "x-summary-ar": "رصيد المحفظة"
      "x-description-ar": "يعيد الأرصدة المخزنة والمحجوزة والمعلقة والمتاحة مع وقت التحقق."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::balance"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletBalanceEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/transactions":
    "get":
      "operationId": "listWalletTransactions"
      "tags":
        - "Transactions"
      "summary": "List wallet transactions"
      "description": "Returns paginated transaction history for the wallet."
      "x-summary-ar": "عمليات المحفظة"
      "x-description-ar": "يعيد سجل عمليات المحفظة بصفحات."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::transactions"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransactionPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/deposit":
    "post":
      "operationId": "depositWallet"
      "tags":
        - "Transactions"
      "summary": "Deposit funds"
      "description": "Posts a deposit using an idempotency key carried in the request body."
      "x-summary-ar": "إيداع في المحفظة"
      "x-description-ar": "ينفذ إيداعًا باستخدام مفتاح منع التكرار داخل جسم الطلب."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::deposit"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransactionEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/WalletMovementRequest"
  "/wallets/{walletId}/withdraw":
    "post":
      "operationId": "withdrawWallet"
      "tags":
        - "Transactions"
      "summary": "Withdraw funds"
      "description": "Posts a withdrawal. Approval policy can apply according to transaction controls."
      "x-summary-ar": "سحب من المحفظة"
      "x-description-ar": "ينفذ سحبًا وقد يخضع لسياسة موافقة حسب ضوابط العملية."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::withdraw"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransactionEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/WalletMovementRequest"
  "/wallets/{walletId}/freeze":
    "post":
      "operationId": "freezeWallet"
      "tags":
        - "Wallets"
      "summary": "Freeze wallet"
      "description": "Freezes a wallet and records the actor context and optional reason."
      "x-summary-ar": "تجميد المحفظة"
      "x-description-ar": "يجمد المحفظة ويسجل سياق المنفذ والسبب الاختياري."
      "x-access-tier": "restricted_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::freeze"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/ReasonRequest"
  "/wallets/{walletId}/unfreeze":
    "post":
      "operationId": "unfreezeWallet"
      "tags":
        - "Wallets"
      "summary": "Unfreeze wallet"
      "description": "Restores a frozen wallet according to authorization controls."
      "x-summary-ar": "إلغاء تجميد المحفظة"
      "x-description-ar": "يعيد المحفظة المجمدة وفق ضوابط الصلاحية."
      "x-access-tier": "restricted_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::unfreeze"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/ledger":
    "get":
      "operationId": "listWalletLedger"
      "tags":
        - "Ledger"
      "summary": "List ledger entries"
      "description": "Returns immutable ledger entries for the wallet. Corrections are represented by reversal entries."
      "x-summary-ar": "قيود دفتر المحفظة"
      "x-description-ar": "يعيد قيود الدفتر غير القابلة للتعديل؛ التصحيح يتم بقيود عكس."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::ledger"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/LedgerPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/audit":
    "get":
      "operationId": "listWalletAudit"
      "tags":
        - "Audit"
      "summary": "List wallet audit records"
      "description": "Returns audit records associated with the wallet."
      "x-summary-ar": "سجل تدقيق المحفظة"
      "x-description-ar": "يعيد سجلات التدقيق المرتبطة بالمحفظة."
      "x-access-tier": "business_auditor"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::auditLog"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/AuditPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallets/{walletId}/statement":
    "get":
      "operationId": "getWalletStatement"
      "tags":
        - "Ledger"
      "summary": "Get wallet statement"
      "description": "Returns a paginated statement sourced from immutable ledger entries."
      "x-summary-ar": "كشف المحفظة"
      "x-description-ar": "يعيد كشفًا مقسمًا إلى صفحات من قيود الدفتر غير القابلة للتعديل."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::statement"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/LedgerPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/transfers":
    "post":
      "operationId": "createTransfer"
      "tags":
        - "Transfers"
      "summary": "Transfer between wallets"
      "description": "Moves funds between source and destination wallets with optional fee."
      "x-summary-ar": "تحويل بين المحافظ"
      "x-description-ar": "ينقل الأموال بين محفظتين مع رسم اختياري."
      "x-access-tier": "customer_or_business"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::transfer"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransferEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/TransferRequest"
  "/wallets/pay-merchant":
    "post":
      "operationId": "payMerchant"
      "tags":
        - "Transfers"
      "summary": "Pay merchant wallet"
      "description": "Executes a user-to-merchant wallet transfer."
      "x-summary-ar": "الدفع لمحفظة تاجر"
      "x-description-ar": "ينفذ تحويلًا من محفظة مستخدم إلى محفظة تاجر."
      "x-access-tier": "customer"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::payMerchant"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransferEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/MerchantPaymentRequest"
  "/wallets/hold":
    "post":
      "operationId": "createHold"
      "tags":
        - "Holds"
      "summary": "Hold wallet funds"
      "description": "Creates a temporary hold against wallet funds."
      "x-summary-ar": "حجز مبلغ"
      "x-description-ar": "ينشئ حجزًا مؤقتًا على أموال المحفظة."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::hold"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/HoldEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreateHoldRequest"
  "/wallets/release":
    "post":
      "operationId": "releaseHold"
      "tags":
        - "Holds"
      "summary": "Release held funds"
      "description": "Releases an existing hold by its UUID."
      "x-summary-ar": "إفراج عن مبلغ محجوز"
      "x-description-ar": "يفرج عن حجز موجود باستخدام UUID."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::release"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/HoldEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/ReleaseHoldRequest"
  "/wallets/refund":
    "post":
      "operationId": "refundWalletTransaction"
      "tags":
        - "Transactions"
      "summary": "Refund wallet transaction"
      "description": "Creates a refund against an original wallet transaction UUID."
      "x-summary-ar": "استرداد عملية محفظة"
      "x-description-ar": "ينشئ استردادًا مرتبطًا بمعرف العملية الأصلية."
      "x-access-tier": "business_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::refund"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/TransactionEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/WalletRefundRequest"
  "/wallets/reverse":
    "post":
      "operationId": "reverseLedgerPair"
      "tags":
        - "Ledger"
      "summary": "Reverse ledger posting"
      "description": "Creates reversal entries for an original debit/credit ledger pair. Original entries remain immutable."
      "x-summary-ar": "عكس قيد مالي"
      "x-description-ar": "ينشئ قيود عكس لزوج مدين ودائن مع بقاء القيود الأصلية غير قابلة للتعديل."
      "x-access-tier": "restricted_finance"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::reverse"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/LedgerReversalEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/LedgerReversalRequest"
  "/wallets/{walletId}/verify-integrity":
    "get":
      "operationId": "verifyWalletLedgerIntegrity"
      "tags":
        - "Ledger"
      "summary": "Verify ledger integrity"
      "description": "Verifies the wallet ledger integrity chain. This operation is restricted and potentially expensive."
      "x-summary-ar": "التحقق من سلامة الدفتر"
      "x-description-ar": "يتحقق من سلسلة سلامة دفتر المحفظة؛ العملية مقيّدة وقد تكون مكلفة."
      "x-access-tier": "restricted_auditor"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/WalletApiController.php::verifyIntegrity"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "walletId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Numeric wallet identifier."
          "example": 42
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/IntegrityEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/merchant-wallets":
    "post":
      "operationId": "createMerchantWallet"
      "tags":
        - "Merchant wallets"
      "summary": "Create merchant wallet"
      "description": "Creates a primary wallet for a merchant/business."
      "x-summary-ar": "إنشاء محفظة تاجر"
      "x-description-ar": "ينشئ محفظة أساسية لتاجر أو نشاط."
      "x-access-tier": "business_operator"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::create"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WalletEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreateMerchantWalletRequest"
  "/merchant-wallets/{merchantId}/overview":
    "get":
      "operationId": "getMerchantWalletOverview"
      "tags":
        - "Merchant wallets"
      "summary": "Merchant wallet overview"
      "description": "Returns merchant wallets and aggregated branch balances."
      "x-summary-ar": "نظرة عامة على محفظة التاجر"
      "x-description-ar": "يعيد محافظ التاجر وأرصدة الفروع المجمعة."
      "x-access-tier": "merchant"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::overview"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "merchantId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Merchant/business identifier."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/MerchantOverviewEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/merchant-wallets/{merchantId}/transactions":
    "get":
      "operationId": "listMerchantTransactions"
      "tags":
        - "Merchant wallets"
      "summary": "List merchant transactions"
      "description": "Returns merchant transactions with compact pagination metadata."
      "x-summary-ar": "عمليات التاجر"
      "x-description-ar": "يعيد عمليات التاجر مع بيانات صفحات مختصرة."
      "x-access-tier": "merchant"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::transactions"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "merchantId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Merchant/business identifier."
          "example": 10101
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/MerchantTransactionPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/merchant-wallets/{merchantId}/settlement-request":
    "post":
      "operationId": "requestMerchantSettlement"
      "tags":
        - "Merchant wallets"
      "summary": "Request merchant settlement"
      "description": "Creates a manual settlement request for a merchant wallet period."
      "x-summary-ar": "طلب تسوية تاجر"
      "x-description-ar": "ينشئ طلب تسوية يدويًا لفترة محفظة التاجر."
      "x-access-tier": "merchant_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::settlementRequest"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "merchantId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Merchant/business identifier."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/MerchantSettlementRequest"
  "/merchant-wallets/{merchantId}/payment-link":
    "post":
      "operationId": "createMerchantPaymentLink"
      "tags":
        - "Merchant wallets"
      "summary": "Create payment link"
      "description": "Creates a payment-link payload for the merchant and amount."
      "x-summary-ar": "إنشاء رابط دفع"
      "x-description-ar": "ينشئ بيانات رابط دفع للتاجر والمبلغ."
      "x-access-tier": "merchant"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::paymentLink"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "merchantId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Merchant/business identifier."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentLinkEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/PaymentLinkRequest"
  "/merchant-wallets/{merchantId}/qr-payment":
    "post":
      "operationId": "createMerchantQrPayload"
      "tags":
        - "Merchant wallets"
      "summary": "Create QR payment payload"
      "description": "Returns a serialized LuxPay QR payload for the selected merchant wallet."
      "x-summary-ar": "إنشاء بيانات QR للدفع"
      "x-description-ar": "يعيد بيانات QR مسلسلة لمحفظة التاجر المحددة."
      "x-access-tier": "merchant"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/LuxPayIdentity/Http/Controllers/Api/MerchantWalletApiController.php::qrPayment"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "merchantId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Merchant/business identifier."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/QrPaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/QrPaymentRequest"
  "/payment-services":
    "get":
      "operationId": "listPaymentServices"
      "tags":
        - "Payment services"
      "summary": "List payment services"
      "description": "Lists enabled payment services, optionally filtered by currency and method."
      "x-summary-ar": "قائمة خدمات الدفع"
      "x-description-ar": "يعرض خدمات الدفع المفعلة مع تصفية اختيارية بالعملة والطريقة."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentServiceController.php::index"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "currency"
          "in": "query"
          "required": false
          "schema":
            "type": "string"
            "minLength": 3
            "maxLength": 3
          "description": "ISO 4217 currency code."
          "example": "YER"
        -
          "name": "method"
          "in": "query"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 80
          "description": "Payment method filter."
          "example": "wallet"
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentServiceListEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payment-services/{provider}":
    "get":
      "operationId": "getPaymentService"
      "tags":
        - "Payment services"
      "summary": "Get payment service"
      "description": "Returns one registered payment service, including exposure and selection capability."
      "x-summary-ar": "تفاصيل خدمة الدفع"
      "x-description-ar": "يعيد خدمة دفع مسجلة مع حالة الإتاحة وإمكانية الاختيار."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentServiceController.php::show"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "provider"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "maxLength": 80
          "description": "Provider code registered by LuxPay."
          "example": "wallet"
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentServiceEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payment-services/{provider}/select":
    "post":
      "operationId": "selectPaymentService"
      "tags":
        - "Payment services"
      "summary": "Select payment service"
      "description": "Evaluates provider selection and returns the next action for the client."
      "x-summary-ar": "اختيار خدمة الدفع"
      "x-description-ar": "يقيّم اختيار المزود ويعيد الإجراء التالي للعميل."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentServiceController.php::select"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "provider"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "maxLength": 80
          "description": "Provider code registered by LuxPay."
          "example": "wallet"
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentServiceSelectionEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/PaymentServiceSelectionRequest"
  "/payments/initiate":
    "post":
      "operationId": "initiatePayment"
      "tags":
        - "Payments"
      "summary": "Initiate payment"
      "description": "Creates a payment through the payment orchestrator. business_id is derived from authentication context and must not be sent."
      "x-summary-ar": "بدء عملية دفع"
      "x-description-ar": "ينشئ عملية دفع عبر المنسق؛ يتم اشتقاق business_id من المصادقة ولا يُرسل في الطلب."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "header:Idempotency-Key"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentController.php::initiate"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "Idempotency-Key"
          "in": "header"
          "required": true
          "schema":
            "type": "string"
            "minLength": 8
            "maxLength": 255
          "description": "Unique key for safely retrying this mutation. Reuse only for the same logical request."
          "example": "pay_01JABC..."
      "responses":
        "200":
          "description": "Duplicate replay of a previously successful request."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/InitiatePaymentRequest"
  "/payments/{paymentUuid}/confirm":
    "post":
      "operationId": "confirmPayment"
      "tags":
        - "Payments"
      "summary": "Confirm payment"
      "description": "Confirms an initiated payment and accepts optional confirmation metadata."
      "x-summary-ar": "تأكيد عملية دفع"
      "x-description-ar": "يؤكد عملية دفع مبدوءة ويقبل بيانات تأكيد اختيارية."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "header:Idempotency-Key"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentController.php::confirm"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "paymentUuid"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "format": "uuid"
          "description": "Payment UUID."
          "example": "cf1b7e8e-5bba-4ddb-b2e4-6f4a10d24857"
        -
          "name": "Idempotency-Key"
          "in": "header"
          "required": true
          "schema":
            "type": "string"
            "minLength": 8
            "maxLength": 255
          "description": "Unique key for safely retrying this mutation. Reuse only for the same logical request."
          "example": "pay_01JABC..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/ConfirmPaymentRequest"
  "/payments/{paymentUuid}/cancel":
    "post":
      "operationId": "cancelPayment"
      "tags":
        - "Payments"
      "summary": "Cancel payment"
      "description": "Cancels a payment when its current state permits cancellation."
      "x-summary-ar": "إلغاء عملية دفع"
      "x-description-ar": "يلغي عملية الدفع عندما تسمح حالتها الحالية."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "header:Idempotency-Key"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentController.php::cancel"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "paymentUuid"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "format": "uuid"
          "description": "Payment UUID."
          "example": "cf1b7e8e-5bba-4ddb-b2e4-6f4a10d24857"
        -
          "name": "Idempotency-Key"
          "in": "header"
          "required": true
          "schema":
            "type": "string"
            "minLength": 8
            "maxLength": 255
          "description": "Unique key for safely retrying this mutation. Reuse only for the same logical request."
          "example": "pay_01JABC..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payments/{paymentUuid}/refund":
    "post":
      "operationId": "refundPayment"
      "tags":
        - "Payments"
      "summary": "Refund payment"
      "description": "Refunds all or part of a payment. Amount is optional for a full refund."
      "x-summary-ar": "استرداد عملية دفع"
      "x-description-ar": "يسترد كامل عملية الدفع أو جزءًا منها؛ المبلغ اختياري للاسترداد الكامل."
      "x-access-tier": "merchant_finance"
      "x-rate-limit": "pay_api"
      "x-idempotency": "header:Idempotency-Key"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/PaymentController.php::refund"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "paymentUuid"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "format": "uuid"
          "description": "Payment UUID."
          "example": "cf1b7e8e-5bba-4ddb-b2e4-6f4a10d24857"
        -
          "name": "Idempotency-Key"
          "in": "header"
          "required": true
          "schema":
            "type": "string"
            "minLength": 8
            "maxLength": 255
          "description": "Unique key for safely retrying this mutation. Reuse only for the same logical request."
          "example": "pay_01JABC..."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/RefundPaymentRequest"
  "/payments/{paymentUuid}/status":
    "get":
      "operationId": "getPaymentStatus"
      "tags":
        - "Payments"
      "summary": "Get payment status"
      "description": "Returns the latest orchestrated payment state."
      "x-summary-ar": "حالة عملية الدفع"
      "x-description-ar": "يعيد أحدث حالة لعملية الدفع من المنسق."
      "x-access-tier": "authenticated"
      "x-rate-limit": "pay_api"
      "x-idempotency": "none"
      "x-source": "LuxApi/Modules/PayAPI/Controllers/StatusController.php::show"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "paymentUuid"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "format": "uuid"
          "description": "Payment UUID."
          "example": "cf1b7e8e-5bba-4ddb-b2e4-6f4a10d24857"
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PaymentEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payouts":
    "get":
      "operationId": "listPayouts"
      "tags":
        - "Payouts"
      "summary": "List payouts"
      "description": "Lists payouts with wallet, status and business filters."
      "x-summary-ar": "قائمة طلبات الصرف"
      "x-description-ar": "يعرض طلبات الصرف مع مرشحات المحفظة والحالة والنشاط."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::index"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "wallet_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
        -
          "name": "status"
          "in": "query"
          "required": false
          "schema":
            "type": "string"
            "enum":
              - "pending"
              - "under_review"
              - "approved"
              - "rejected"
              - "executing"
              - "executed"
              - "failed"
              - "cancelled"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
    "post":
      "operationId": "createPayout"
      "tags":
        - "Payouts"
      "summary": "Create payout request"
      "description": "Creates an idempotent payout request from a wallet."
      "x-summary-ar": "إنشاء طلب صرف"
      "x-description-ar": "ينشئ طلب صرف غير قابل للتكرار من محفظة."
      "x-access-tier": "business_finance"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::create"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreatePayoutRequest"
  "/payouts/{payoutId}":
    "get":
      "operationId": "getPayout"
      "tags":
        - "Payouts"
      "summary": "Get payout"
      "description": "Returns a payout and its attempts."
      "x-summary-ar": "تفاصيل طلب الصرف"
      "x-description-ar": "يعيد طلب الصرف ومحاولات تنفيذه."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::show"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "payoutId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Payout identifier."
          "example": 8001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payouts/{payoutId}/approve":
    "post":
      "operationId": "approvePayout"
      "tags":
        - "Payouts"
      "summary": "Approve payout"
      "description": "Approves a payout under authorization and state-transition controls."
      "x-summary-ar": "الموافقة على الصرف"
      "x-description-ar": "يوافق على طلب الصرف وفق الصلاحيات وانتقالات الحالة."
      "x-access-tier": "restricted_approver"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::approve"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "payoutId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Payout identifier."
          "example": 8001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/NotesRequest"
  "/payouts/{payoutId}/reject":
    "post":
      "operationId": "rejectPayout"
      "tags":
        - "Payouts"
      "summary": "Reject payout"
      "description": "Rejects a payout with a required reason."
      "x-summary-ar": "رفض الصرف"
      "x-description-ar": "يرفض طلب الصرف مع سبب إلزامي."
      "x-access-tier": "restricted_approver"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::reject"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "payoutId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Payout identifier."
          "example": 8001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/RequiredReasonRequest"
  "/payouts/{payoutId}/execute":
    "post":
      "operationId": "executePayout"
      "tags":
        - "Payouts"
      "summary": "Execute payout"
      "description": "Executes an approved payout."
      "x-summary-ar": "تنفيذ الصرف"
      "x-description-ar": "ينفذ طلب صرف تمت الموافقة عليه."
      "x-access-tier": "restricted_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::execute"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "payoutId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Payout identifier."
          "example": 8001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/payouts/{payoutId}/cancel":
    "post":
      "operationId": "cancelPayout"
      "tags":
        - "Payouts"
      "summary": "Cancel payout"
      "description": "Cancels a payout with a required reason when the transition is allowed."
      "x-summary-ar": "إلغاء الصرف"
      "x-description-ar": "يلغي طلب الصرف بسبب إلزامي عندما تسمح الحالة."
      "x-access-tier": "business_finance"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/PayoutApiController.php::cancel"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "payoutId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Payout identifier."
          "example": 8001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/PayoutEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/RequiredReasonRequest"
  "/wallet-settlements":
    "get":
      "operationId": "listSettlements"
      "tags":
        - "Settlements"
      "summary": "List settlements"
      "description": "Lists settlements with wallet, status and business filters."
      "x-summary-ar": "قائمة التسويات"
      "x-description-ar": "يعرض التسويات مع مرشحات المحفظة والحالة والنشاط."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::index"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "wallet_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
        -
          "name": "status"
          "in": "query"
          "required": false
          "schema":
            "type": "string"
            "enum":
              - "pending"
              - "approved"
              - "rejected"
              - "executing"
              - "executed"
              - "failed"
              - "cancelled"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
        -
          "name": "per_page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "maximum": 100
            "default": 20
          "description": "Page size."
          "example": 20
        -
          "name": "page"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
            "default": 1
          "description": "Page number."
          "example": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementPageEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
    "post":
      "operationId": "createSettlement"
      "tags":
        - "Settlements"
      "summary": "Create settlement"
      "description": "Creates a settlement for a defined period and wallet."
      "x-summary-ar": "إنشاء تسوية"
      "x-description-ar": "ينشئ تسوية لمحفظة وفترة محددتين."
      "x-access-tier": "business_finance"
      "x-rate-limit": "20/min"
      "x-idempotency": "body:idempotency_key"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::create"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
      "responses":
        "201":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/CreateSettlementRequest"
  "/wallet-settlements/{settlementId}":
    "get":
      "operationId": "getSettlement"
      "tags":
        - "Settlements"
      "summary": "Get settlement"
      "description": "Returns a settlement with its items."
      "x-summary-ar": "تفاصيل التسوية"
      "x-description-ar": "يعيد التسوية وبنودها."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::show"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "settlementId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Settlement identifier."
          "example": 7001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallet-settlements/{settlementId}/approve":
    "post":
      "operationId": "approveSettlement"
      "tags":
        - "Settlements"
      "summary": "Approve settlement"
      "description": "Approves a pending settlement."
      "x-summary-ar": "الموافقة على التسوية"
      "x-description-ar": "يوافق على تسوية معلقة."
      "x-access-tier": "restricted_approver"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::approve"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "settlementId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Settlement identifier."
          "example": 7001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/NotesRequest"
  "/wallet-settlements/{settlementId}/reject":
    "post":
      "operationId": "rejectSettlement"
      "tags":
        - "Settlements"
      "summary": "Reject settlement"
      "description": "Rejects a settlement with a reason."
      "x-summary-ar": "رفض التسوية"
      "x-description-ar": "يرفض التسوية مع سبب."
      "x-access-tier": "restricted_approver"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::reject"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "settlementId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Settlement identifier."
          "example": 7001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/RequiredReasonRequest"
  "/wallet-settlements/{settlementId}/execute":
    "post":
      "operationId": "executeSettlement"
      "tags":
        - "Settlements"
      "summary": "Execute settlement"
      "description": "Executes an approved settlement."
      "x-summary-ar": "تنفيذ التسوية"
      "x-description-ar": "ينفذ تسوية تمت الموافقة عليها."
      "x-access-tier": "restricted_operator"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::execute"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "settlementId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Settlement identifier."
          "example": 7001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/wallet-settlements/{settlementId}/cancel":
    "post":
      "operationId": "cancelSettlement"
      "tags":
        - "Settlements"
      "summary": "Cancel settlement"
      "description": "Cancels a settlement with a reason when allowed."
      "x-summary-ar": "إلغاء التسوية"
      "x-description-ar": "يلغي التسوية بسبب عندما تسمح الحالة."
      "x-access-tier": "business_finance"
      "x-rate-limit": "20/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/SettlementApiController.php::cancel"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "settlementId"
          "in": "path"
          "required": true
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Settlement identifier."
          "example": 7001
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SettlementEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/RequiredReasonRequest"
  "/reports/summary":
    "get":
      "operationId": "getBalanceSummary"
      "tags":
        - "Reports"
      "summary": "Balance summary"
      "description": "Returns balance summary, optionally scoped by business."
      "x-summary-ar": "ملخص الأرصدة"
      "x-description-ar": "يعيد ملخص الأرصدة مع نطاق نشاط اختياري."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/ReportApiController.php::summary"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReportEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/reports/transactions":
    "get":
      "operationId": "getTransactionReport"
      "tags":
        - "Reports"
      "summary": "Transaction report"
      "description": "Returns transaction summary for a date range."
      "x-summary-ar": "تقرير العمليات"
      "x-description-ar": "يعيد ملخص العمليات لفترة زمنية."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/ReportApiController.php::transactions"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "from"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive start date."
          "example": "2026-07-01"
        -
          "name": "to"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive end date."
          "example": "2026-07-31"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Business filter for privileged actors."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReportEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/reports/fees":
    "get":
      "operationId": "getFeeReport"
      "tags":
        - "Reports"
      "summary": "Fee report"
      "description": "Returns fee summary for a date range."
      "x-summary-ar": "تقرير الرسوم"
      "x-description-ar": "يعيد ملخص الرسوم لفترة زمنية."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/ReportApiController.php::fees"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "from"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive start date."
          "example": "2026-07-01"
        -
          "name": "to"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive end date."
          "example": "2026-07-31"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Business filter for privileged actors."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReportEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/reports/payouts":
    "get":
      "operationId": "getPayoutReport"
      "tags":
        - "Reports"
      "summary": "Payout report"
      "description": "Returns payout summary for a date range."
      "x-summary-ar": "تقرير الصرف"
      "x-description-ar": "يعيد ملخص الصرف لفترة زمنية."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/ReportApiController.php::payouts"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "from"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive start date."
          "example": "2026-07-01"
        -
          "name": "to"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive end date."
          "example": "2026-07-31"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Business filter for privileged actors."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReportEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/reports/settlements":
    "get":
      "operationId": "getSettlementReport"
      "tags":
        - "Reports"
      "summary": "Settlement report"
      "description": "Returns settlement summary for a date range."
      "x-summary-ar": "تقرير التسويات"
      "x-description-ar": "يعيد ملخص التسويات لفترة زمنية."
      "x-access-tier": "business_finance"
      "x-rate-limit": "60/min"
      "x-idempotency": "none"
      "x-source": "LuxApi/app/Http/Controllers/Api/ReportApiController.php::settlements"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "from"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive start date."
          "example": "2026-07-01"
        -
          "name": "to"
          "in": "query"
          "required": true
          "schema":
            "type": "string"
            "format": "date"
          "description": "Inclusive end date."
          "example": "2026-07-31"
        -
          "name": "business_id"
          "in": "query"
          "required": false
          "schema":
            "type": "integer"
            "minimum": 1
          "description": "Business filter for privileged actors."
          "example": 10101
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReportEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "BearerAuth": []
  "/webhooks/{provider}":
    "post":
      "operationId": "receiveProviderWebhook"
      "tags":
        - "Provider webhooks"
      "summary": "Receive provider webhook"
      "description": "Provider-facing inbound webhook. Sign the exact payload with the provisioned provider secret and send timestamp plus stable event identifier."
      "x-summary-ar": "استقبال Webhook من مزود"
      "x-description-ar": "Webhook وارد للمزود؛ يجب توقيع الحمولة وإرسال الوقت ومعرف حدث ثابت."
      "x-access-tier": "provider_only"
      "x-rate-limit": "pay_api"
      "x-idempotency": "provider event id"
      "x-source": "LuxApi/Modules/PayWebhooks/Controllers/WebhookController.php::handle"
      "parameters":
        -
          "name": "X-Request-ID"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 128
          "description": "Client correlation identifier. LuxPay may generate one when omitted."
          "example": "req_01J..."
        -
          "name": "provider"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
            "maxLength": 80
          "description": "Provider code registered by LuxPay."
          "example": "wallet"
        -
          "name": "X-Signature"
          "in": "header"
          "required": true
          "schema":
            "type": "string"
          "description": "Provider signature."
        -
          "name": "X-Timestamp"
          "in": "header"
          "required": true
          "schema":
            "type": "integer"
            "format": "int64"
          "description": "Unix timestamp used for replay protection."
        -
          "name": "X-Provider-Event-Id"
          "in": "header"
          "required": false
          "schema":
            "type": "string"
            "maxLength": 191
          "description": "Stable event identifier for deduplication."
      "responses":
        "200":
          "description": "Successful response."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WebhookReceiptEnvelope"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "description": "Signature or timestamp verification failed."
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/WebhookReceiptEnvelope"
        "404":
          "$ref": "#/components/responses/NotFound"
        "409":
          "$ref": "#/components/responses/Conflict"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
        "429":
          "$ref": "#/components/responses/RateLimited"
        "500":
          "$ref": "#/components/responses/ServerError"
      "security":
        -
          "WebhookSignature": []
          "WebhookTimestamp": []
      "requestBody":
        "required": true
        "description": "JSON request body."
        "content":
          "application/json":
            "schema":
              "$ref": "#/components/schemas/ProviderWebhookPayload"
"components":
  "securitySchemes":
    "BearerAuth":
      "type": "http"
      "scheme": "bearer"
      "bearerFormat": "LuxPay token"
      "description": "Send the token returned by the authorized authentication flow."
    "WebhookSignature":
      "type": "apiKey"
      "in": "header"
      "name": "X-Signature"
      "description": "Provider-specific payload signature."
    "WebhookTimestamp":
      "type": "apiKey"
      "in": "header"
      "name": "X-Timestamp"
      "description": "Unix timestamp used for replay protection."
  "responses":
    "BadRequest":
      "description": "Malformed request or missing business selector."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "Unauthorized":
      "description": "Authentication failed or token is missing."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "Forbidden":
      "description": "Authenticated actor lacks the required scope."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "NotFound":
      "description": "Requested resource was not found."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "Conflict":
      "description": "Idempotency conflict or invalid state transition."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "UnprocessableEntity":
      "description": "Validation or control decision failure."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "RateLimited":
      "description": "Rate limit exceeded."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
    "ServerError":
      "description": "Unexpected server error. Use request_id when contacting support."
      "content":
        "application/json":
          "schema":
            "$ref": "#/components/schemas/Error"
  "schemas":
    "Money":
      "type": "object"
      "required":
        - "amount"
        - "currency_code"
      "properties":
        "amount":
          "type": "number"
          "minimum": 0
          "multipleOf": 0.000001
          "example": 1250.5
        "currency_code":
          "type": "string"
          "minLength": 3
          "maxLength": 10
          "example": "YER"
    "Wallet":
      "type": "object"
      "required":
        - "id"
        - "uuid"
        - "owner_type"
        - "owner_id"
        - "wallet_type"
        - "status"
        - "currency_code"
        - "account_number"
      "properties":
        "id":
          "type": "integer"
          "example": 42
        "uuid":
          "type": "string"
          "format": "uuid"
          "example": "6ee4b4a8-9f8d-4f18-a586-b32c4593b094"
        "owner_type":
          "type": "string"
          "enum":
            - "business"
            - "branch"
            - "customer"
            - "employee"
            - "luxpay_staff"
            - "system"
          "example": "customer"
        "owner_id":
          "type": "integer"
          "example": 2201
        "wallet_type":
          "type": "string"
          "enum":
            - "primary"
            - "fee"
            - "settlement"
            - "clearing"
            - "reserve"
            - "custody"
            - "commission"
          "example": "primary"
        "status":
          "type": "string"
          "enum":
            - "active"
            - "frozen"
            - "suspended"
            - "closed"
            - "pending_activation"
          "example": "active"
        "currency_code":
          "type": "string"
          "example": "YER"
        "account_number":
          "type": "string"
          "example": "C-YER-00000042"
        "cached_balance":
          "type": "number"
          "example": 5000
        "cached_pending_balance":
          "type": "number"
          "example": 0
        "cached_held_balance":
          "type": "number"
          "example": 500
        "business_id":
          "type":
            - "integer"
            - "null"
          "example": 10101
        "branch_id":
          "type":
            - "integer"
            - "null"
          "example": 7
        "balance_verified_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
        "meta":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "created_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
        "updated_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
    "WalletBalance":
      "type": "object"
      "required":
        - "wallet_id"
        - "currency_code"
        - "available_balance"
        - "cached_balance"
        - "held_balance"
        - "pending_balance"
      "properties":
        "wallet_id":
          "type": "integer"
          "example": 42
        "account_number":
          "type": "string"
          "example": "C-YER-00000042"
        "currency_code":
          "type": "string"
          "example": "YER"
        "available_balance":
          "type": "number"
          "example": 4500
        "cached_balance":
          "type": "number"
          "example": 5000
        "held_balance":
          "type": "number"
          "example": 500
        "pending_balance":
          "type": "number"
          "example": 0
        "balance_verified_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
    "Transaction":
      "type": "object"
      "required":
        - "id"
        - "uuid"
        - "wallet_id"
        - "transaction_type"
        - "status"
        - "amount"
        - "currency_code"
      "properties":
        "id":
          "type": "integer"
          "example": 901
        "uuid":
          "type": "string"
          "format": "uuid"
        "wallet_id":
          "type": "integer"
          "example": 42
        "owner_type":
          "type": "string"
          "example": "customer"
        "owner_id":
          "type": "integer"
          "example": 2201
        "transaction_type":
          "type": "string"
          "enum":
            - "deposit"
            - "withdrawal"
            - "payment"
            - "refund"
            - "reversal"
            - "adjustment"
            - "hold"
            - "release_hold"
            - "freeze"
            - "unfreeze"
            - "transfer"
            - "fee"
            - "settlement"
            - "payout"
            - "commission"
            - "dispute"
            - "chargeback"
          "example": "transfer"
        "status":
          "type": "string"
          "enum":
            - "pending"
            - "completed"
            - "failed"
            - "reversed"
            - "held"
            - "disputed"
            - "cancelled"
            - "requires_approval"
          "example": "completed"
        "amount":
          "type": "number"
          "example": 1250.5
        "currency_code":
          "type": "string"
          "example": "YER"
        "exchange_rate":
          "type":
            - "number"
            - "null"
        "local_amount":
          "type":
            - "number"
            - "null"
        "fee_amount":
          "type": "number"
          "example": 0
        "net_amount":
          "type": "number"
          "example": 1250.5
        "reference_type":
          "type":
            - "string"
            - "null"
        "reference_id":
          "type":
            - "integer"
            - "string"
            - "null"
        "external_reference":
          "type":
            - "string"
            - "null"
        "idempotency_key":
          "type":
            - "string"
            - "null"
        "business_id":
          "type":
            - "integer"
            - "null"
        "branch_id":
          "type":
            - "integer"
            - "null"
        "payment_method":
          "type":
            - "string"
            - "null"
        "description":
          "type":
            - "string"
            - "null"
        "meta":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "completed_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
        "failed_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
        "reversed_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
        "created_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
    "LedgerEntry":
      "type": "object"
      "required":
        - "id"
        - "uuid"
        - "wallet_id"
        - "direction"
        - "amount"
        - "currency_code"
        - "balance_after"
      "properties":
        "id":
          "type": "integer"
          "example": 3301
        "uuid":
          "type": "string"
          "format": "uuid"
        "wallet_id":
          "type": "integer"
          "example": 42
        "transaction_id":
          "type":
            - "integer"
            - "null"
        "direction":
          "type": "string"
          "enum":
            - "debit"
            - "credit"
          "example": "debit"
        "amount":
          "type": "number"
          "example": 1250.5
        "signed_amount":
          "type": "number"
          "example": -1250.5
        "currency_code":
          "type": "string"
          "example": "YER"
        "exchange_rate":
          "type":
            - "number"
            - "null"
        "local_amount":
          "type":
            - "number"
            - "null"
        "signed_local_amount":
          "type":
            - "number"
            - "null"
        "local_currency_code":
          "type":
            - "string"
            - "null"
        "balance_after":
          "type": "number"
          "example": 3749.5
        "entry_type":
          "type": "string"
          "example": "transfer"
        "status":
          "type": "string"
          "enum":
            - "posted"
            - "held"
          "example": "posted"
        "idempotency_key":
          "type":
            - "string"
            - "null"
        "reference_type":
          "type":
            - "string"
            - "null"
        "reference_id":
          "type":
            - "integer"
            - "string"
            - "null"
        "description":
          "type":
            - "string"
            - "null"
        "reversed_by_entry_id":
          "type":
            - "integer"
            - "null"
        "is_reversal":
          "type": "boolean"
          "example": false
        "reverses_entry_id":
          "type":
            - "integer"
            - "null"
        "meta":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "created_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
    "AuditRecord":
      "type": "object"
      "additionalProperties": true
      "properties":
        "id":
          "type": "integer"
        "event":
          "type": "string"
          "example": "wallet_frozen"
        "entity_type":
          "type": "string"
          "example": "wallet"
        "entity_id":
          "type": "integer"
          "example": 42
        "actor_type":
          "type": "string"
        "actor_id":
          "type": "integer"
        "created_at":
          "type": "string"
          "format": "date-time"
    "Transfer":
      "type": "object"
      "additionalProperties": true
      "properties":
        "uuid":
          "type": "string"
          "format": "uuid"
        "source_wallet_id":
          "type": "integer"
        "destination_wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
        "currency_code":
          "type": "string"
        "fee_amount":
          "type": "number"
        "status":
          "type": "string"
        "idempotency_key":
          "type": "string"
    "Hold":
      "type": "object"
      "additionalProperties": true
      "properties":
        "uuid":
          "type": "string"
          "format": "uuid"
        "wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
        "currency_code":
          "type": "string"
        "status":
          "type": "string"
          "enum":
            - "active"
            - "released"
            - "expired"
            - "captured"
        "reason":
          "type":
            - "string"
            - "null"
        "expires_at":
          "type":
            - "string"
            - "null"
          "format": "date-time"
    "PaymentResult":
      "type": "object"
      "required":
        - "success"
      "properties":
        "success":
          "type": "boolean"
        "transaction_id":
          "type":
            - "string"
            - "null"
        "status":
          "type":
            - "string"
            - "null"
        "provider":
          "type":
            - "string"
            - "null"
        "provider_ref":
          "type":
            - "string"
            - "null"
        "amount":
          "type":
            - "number"
            - "null"
        "currency":
          "type":
            - "string"
            - "null"
        "fee_amount":
          "type":
            - "number"
            - "null"
        "net_amount":
          "type":
            - "number"
            - "null"
        "message":
          "type":
            - "string"
            - "null"
        "error_code":
          "type":
            - "string"
            - "null"
        "is_duplicate":
          "type": "boolean"
          "default": false
        "metadata":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
    "PaymentService":
      "type": "object"
      "additionalProperties": true
      "properties":
        "provider":
          "type": "string"
          "example": "wallet"
        "display_name":
          "type": "string"
          "example": "LuxPay Wallet"
        "enabled":
          "type": "boolean"
          "example": true
        "can_select":
          "type": "boolean"
          "example": true
        "currencies":
          "type": "array"
          "items":
            "type": "string"
        "methods":
          "type": "array"
          "items":
            "type": "string"
        "channels":
          "type": "array"
          "items":
            "type": "string"
    "Payout":
      "type": "object"
      "additionalProperties": true
      "properties":
        "id":
          "type": "integer"
        "uuid":
          "type": "string"
          "format": "uuid"
        "wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
        "currency_code":
          "type": "string"
        "status":
          "type": "string"
          "enum":
            - "pending"
            - "under_review"
            - "approved"
            - "rejected"
            - "executing"
            - "executed"
            - "failed"
            - "cancelled"
        "payout_method":
          "type":
            - "string"
            - "null"
        "payout_destination":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "description":
          "type":
            - "string"
            - "null"
        "idempotency_key":
          "type": "string"
        "attempts":
          "type": "array"
          "items":
            "type": "object"
            "additionalProperties": true
        "created_at":
          "type": "string"
          "format": "date-time"
    "Settlement":
      "type": "object"
      "additionalProperties": true
      "properties":
        "id":
          "type": "integer"
        "uuid":
          "type": "string"
          "format": "uuid"
        "wallet_id":
          "type": "integer"
        "period_type":
          "type": "string"
          "enum":
            - "daily"
            - "weekly"
            - "monthly"
            - "custom"
            - "manual"
        "period_start":
          "type": "string"
          "format": "date"
        "period_end":
          "type": "string"
          "format": "date"
        "status":
          "type": "string"
          "enum":
            - "pending"
            - "approved"
            - "rejected"
            - "executing"
            - "executed"
            - "failed"
            - "cancelled"
        "idempotency_key":
          "type": "string"
        "notes":
          "type":
            - "string"
            - "null"
        "items":
          "type": "array"
          "items":
            "type": "object"
            "additionalProperties": true
        "created_at":
          "type": "string"
          "format": "date-time"
    "Error":
      "type": "object"
      "required":
        - "success"
        - "message"
      "properties":
        "success":
          "type": "boolean"
          "example": false
        "status":
          "type": "boolean"
          "example": false
        "error":
          "type":
            - "string"
            - "null"
          "example": "validation_error"
        "code":
          "type":
            - "string"
            - "null"
          "example": "validation_error"
        "message":
          "type": "string"
          "example": "The request could not be processed."
        "errors":
          "type":
            - "object"
            - "null"
          "additionalProperties":
            "type": "array"
            "items":
              "type": "string"
        "request_id":
          "type":
            - "string"
            - "null"
    "PaginationMeta":
      "type": "object"
      "properties":
        "current_page":
          "type": "integer"
          "example": 1
        "last_page":
          "type": "integer"
          "example": 4
        "per_page":
          "type": "integer"
          "example": 20
        "total":
          "type": "integer"
          "example": 73
        "from":
          "type":
            - "integer"
            - "null"
        "to":
          "type":
            - "integer"
            - "null"
    "Health":
      "type": "object"
      "properties":
        "status":
          "type": "string"
          "example": "ok"
        "service":
          "type": "string"
          "example": "luxpay"
        "version":
          "type": "string"
          "example": "1.0.0"
        "timestamp":
          "type": "string"
          "format": "date-time"
    "Customer":
      "type": "object"
      "properties":
        "id":
          "type": "integer"
        "full_name":
          "type": "string"
        "phone":
          "type": "string"
    "BusinessUser":
      "type": "object"
      "properties":
        "id":
          "type": "integer"
        "full_name":
          "type": "string"
        "email":
          "type": "string"
        "is_owner":
          "type": "boolean"
    "Business":
      "type": "object"
      "properties":
        "id":
          "type": "integer"
        "legal_name":
          "type": "string"
        "business_number":
          "type": "string"
    "CustomerRegisterRequest":
      "type": "object"
      "required":
        - "full_name"
        - "phone"
        - "password"
      "properties":
        "full_name":
          "type": "string"
          "maxLength": 160
          "example": "أحمد محمد"
        "phone":
          "type": "string"
          "maxLength": 40
          "example": "+9677XXXXXXX"
        "email":
          "type":
            - "string"
            - "null"
          "format": "email"
          "maxLength": 160
        "password":
          "type": "string"
          "minLength": 6
          "format": "password"
    "CustomerLoginRequest":
      "type": "object"
      "required":
        - "phone"
        - "password"
      "properties":
        "phone":
          "type": "string"
          "example": "+9677XXXXXXX"
        "password":
          "type": "string"
          "format": "password"
    "EmployeeLoginRequest":
      "type": "object"
      "required":
        - "email"
        - "password"
      "anyOf":
        -
          "required":
            - "business_id"
        -
          "required":
            - "business_number"
      "properties":
        "business_id":
          "type":
            - "integer"
            - "null"
          "example": 10101
        "business_number":
          "type":
            - "string"
            - "null"
          "example": "FT-10101"
        "email":
          "type": "string"
          "example": "employee@example.com"
        "password":
          "type": "string"
          "format": "password"
    "CreateWalletRequest":
      "type": "object"
      "required":
        - "owner_type"
        - "owner_id"
        - "currency_code"
      "properties":
        "owner_type":
          "type": "string"
          "enum":
            - "business"
            - "branch"
            - "customer"
            - "employee"
            - "luxpay_staff"
            - "system"
          "example": "customer"
        "owner_id":
          "type": "integer"
          "example": 2201
        "currency_code":
          "type": "string"
          "maxLength": 10
          "example": "YER"
        "wallet_type":
          "type": "string"
          "enum":
            - "primary"
            - "fee"
            - "settlement"
            - "clearing"
            - "reserve"
            - "custody"
            - "commission"
          "default": "primary"
    "CreateCustomerWalletRequest":
      "type": "object"
      "required":
        - "owner_id"
        - "currency_code"
      "properties":
        "owner_id":
          "type": "integer"
          "example": 2201
        "currency_code":
          "type": "string"
          "maxLength": 10
          "example": "YER"
    "WalletMovementRequest":
      "type": "object"
      "required":
        - "amount"
        - "currency_code"
        - "idempotency_key"
      "properties":
        "amount":
          "type": "number"
          "minimum": 0.000001
          "example": 5000
        "currency_code":
          "type": "string"
          "maxLength": 10
          "example": "YER"
        "idempotency_key":
          "type": "string"
          "maxLength": 255
          "example": "wallet_move_01JABC..."
        "payment_method":
          "type":
            - "string"
            - "null"
          "example": "cash"
        "description":
          "type":
            - "string"
            - "null"
          "example": "Cash desk deposit"
    "TransferRequest":
      "type": "object"
      "required":
        - "source_wallet_id"
        - "destination_wallet_id"
        - "amount"
        - "currency_code"
        - "idempotency_key"
      "properties":
        "source_wallet_id":
          "type": "integer"
          "example": 42
        "destination_wallet_id":
          "type": "integer"
          "example": 87
        "amount":
          "type": "number"
          "minimum": 0.000001
          "example": 1250.5
        "currency_code":
          "type": "string"
          "maxLength": 10
          "example": "YER"
        "idempotency_key":
          "type": "string"
          "maxLength": 255
          "example": "transfer_01JABC..."
        "transfer_type":
          "type": "string"
          "default": "wallet_to_wallet"
        "fee_amount":
          "type": "number"
          "minimum": 0
          "default": 0
        "description":
          "type":
            - "string"
            - "null"
    "MerchantPaymentRequest":
      "type": "object"
      "required":
        - "source_wallet_id"
        - "destination_wallet_id"
        - "amount"
        - "currency_code"
        - "idempotency_key"
      "properties":
        "source_wallet_id":
          "type": "integer"
        "destination_wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
          "minimum": 0.000001
        "currency_code":
          "type": "string"
          "maxLength": 10
        "idempotency_key":
          "type": "string"
          "maxLength": 255
        "description":
          "type":
            - "string"
            - "null"
    "CreateHoldRequest":
      "type": "object"
      "required":
        - "wallet_id"
        - "amount"
        - "currency_code"
      "properties":
        "wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
          "minimum": 0.000001
        "currency_code":
          "type": "string"
          "maxLength": 10
        "reason":
          "type":
            - "string"
            - "null"
        "expiry_minutes":
          "type":
            - "integer"
            - "null"
          "minimum": 1
    "ReleaseHoldRequest":
      "type": "object"
      "required":
        - "hold_uuid"
      "properties":
        "hold_uuid":
          "type": "string"
          "format": "uuid"
    "WalletRefundRequest":
      "type": "object"
      "required":
        - "original_transaction_uuid"
        - "amount"
      "properties":
        "original_transaction_uuid":
          "type": "string"
          "format": "uuid"
        "amount":
          "type": "number"
          "minimum": 0.000001
        "reason":
          "type":
            - "string"
            - "null"
    "LedgerReversalRequest":
      "type": "object"
      "required":
        - "debit_ledger_entry_id"
        - "credit_ledger_entry_id"
      "properties":
        "debit_ledger_entry_id":
          "type": "integer"
        "credit_ledger_entry_id":
          "type": "integer"
        "reason":
          "type":
            - "string"
            - "null"
    "ReasonRequest":
      "type": "object"
      "properties":
        "reason":
          "type":
            - "string"
            - "null"
          "maxLength": 500
    "RequiredReasonRequest":
      "type": "object"
      "required":
        - "reason"
      "properties":
        "reason":
          "type": "string"
          "maxLength": 500
    "NotesRequest":
      "type": "object"
      "properties":
        "notes":
          "type":
            - "string"
            - "null"
          "maxLength": 500
    "CreateMerchantWalletRequest":
      "type": "object"
      "required":
        - "merchant_id"
        - "currency_code"
      "properties":
        "merchant_id":
          "type": "integer"
        "currency_code":
          "type": "string"
          "maxLength": 10
    "MerchantSettlementRequest":
      "type": "object"
      "required":
        - "wallet_id"
        - "period_start"
        - "period_end"
        - "idempotency_key"
      "properties":
        "wallet_id":
          "type": "integer"
        "period_start":
          "type": "string"
          "format": "date"
        "period_end":
          "type": "string"
          "format": "date"
        "idempotency_key":
          "type": "string"
        "notes":
          "type":
            - "string"
            - "null"
    "PaymentLinkRequest":
      "type": "object"
      "required":
        - "amount"
        - "currency_code"
      "properties":
        "amount":
          "type": "number"
          "minimum": 0.01
        "currency_code":
          "type": "string"
          "maxLength": 10
        "description":
          "type":
            - "string"
            - "null"
    "QrPaymentRequest":
      "type": "object"
      "required":
        - "wallet_id"
      "properties":
        "wallet_id":
          "type": "integer"
    "PaymentServiceSelectionRequest":
      "type": "object"
      "properties":
        "amount":
          "type":
            - "number"
            - "null"
          "minimum": 0.01
        "currency":
          "type":
            - "string"
            - "null"
          "minLength": 3
          "maxLength": 3
        "payment_method":
          "type":
            - "string"
            - "null"
          "maxLength": 80
        "payment_channel":
          "type":
            - "string"
            - "null"
          "maxLength": 80
        "customer":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "metadata":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
    "InitiatePaymentRequest":
      "type": "object"
      "required":
        - "amount"
        - "currency"
        - "payment_method"
        - "payment_channel"
      "properties":
        "amount":
          "type": "number"
          "minimum": 0.01
          "example": 1250.5
        "currency":
          "type": "string"
          "minLength": 3
          "maxLength": 3
          "example": "YER"
        "payment_method":
          "type": "string"
          "maxLength": 80
          "example": "wallet"
        "payment_channel":
          "type": "string"
          "maxLength": 80
          "example": "pos"
        "provider":
          "type":
            - "string"
            - "null"
          "maxLength": 80
        "metadata":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
      "not":
        "required":
          - "business_id"
    "ConfirmPaymentRequest":
      "type": "object"
      "properties":
        "metadata":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
    "RefundPaymentRequest":
      "type": "object"
      "properties":
        "amount":
          "type":
            - "number"
            - "null"
          "minimum": 0.01
        "reason":
          "type":
            - "string"
            - "null"
          "maxLength": 500
    "CreatePayoutRequest":
      "type": "object"
      "required":
        - "wallet_id"
        - "amount"
        - "currency_code"
        - "idempotency_key"
      "properties":
        "wallet_id":
          "type": "integer"
        "amount":
          "type": "number"
          "minimum": 0.000001
        "currency_code":
          "type": "string"
          "maxLength": 10
        "idempotency_key":
          "type": "string"
          "maxLength": 255
        "payout_method":
          "type":
            - "string"
            - "null"
          "maxLength": 50
        "payout_destination":
          "type":
            - "object"
            - "null"
          "additionalProperties": true
        "description":
          "type":
            - "string"
            - "null"
          "maxLength": 500
    "CreateSettlementRequest":
      "type": "object"
      "required":
        - "wallet_id"
        - "period_type"
        - "period_start"
        - "period_end"
        - "idempotency_key"
      "properties":
        "wallet_id":
          "type": "integer"
        "period_type":
          "type": "string"
          "enum":
            - "daily"
            - "weekly"
            - "monthly"
            - "custom"
        "period_start":
          "type": "string"
          "format": "date"
        "period_end":
          "type": "string"
          "format": "date"
        "idempotency_key":
          "type": "string"
          "maxLength": 255
        "notes":
          "type":
            - "string"
            - "null"
          "maxLength": 500
    "ProviderWebhookPayload":
      "type": "object"
      "description": "Provider-specific event payload. LuxPay verifies the signature before queueing the event."
      "additionalProperties": true
      "example":
        "event_id": "evt_01JABC"
        "type": "payment.completed"
        "data":
          "id": "provider_tx_123"
          "status": "completed"
    "SuccessEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "success":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "type":
            - "object"
            - "array"
            - "null"
          "additionalProperties": true
    "HealthEnvelope":
      "$ref": "#/components/schemas/Health"
    "WalletEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Wallet"
    "WalletListEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "array"
          "items":
            "$ref": "#/components/schemas/Wallet"
    "WalletBalanceEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "$ref": "#/components/schemas/WalletBalance"
    "TransactionEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "message_translated":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Transaction"
    "TransferEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Transfer"
    "HoldEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Hold"
    "LedgerReversalEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "type": "object"
          "additionalProperties": true
    "TransactionPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "allOf":
            -
              "type": "object"
              "properties":
                "data":
                  "type": "array"
                  "items":
                    "$ref": "#/components/schemas/Transaction"
            -
              "$ref": "#/components/schemas/PaginationMeta"
    "LedgerPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "allOf":
            -
              "type": "object"
              "properties":
                "data":
                  "type": "array"
                  "items":
                    "$ref": "#/components/schemas/LedgerEntry"
            -
              "$ref": "#/components/schemas/PaginationMeta"
    "AuditPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "allOf":
            -
              "type": "object"
              "properties":
                "data":
                  "type": "array"
                  "items":
                    "$ref": "#/components/schemas/AuditRecord"
            -
              "$ref": "#/components/schemas/PaginationMeta"
    "IntegrityEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
        "message":
          "type": "string"
        "data":
          "type": "object"
          "properties":
            "wallet_id":
              "type": "integer"
            "integrity":
              "type": "string"
              "enum":
                - "valid"
                - "invalid"
    "CustomerAuthEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "token":
          "type": "string"
          "writeOnly": true
        "customer":
          "$ref": "#/components/schemas/Customer"
    "EmployeeAuthEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "token":
          "type": "string"
          "writeOnly": true
        "user":
          "$ref": "#/components/schemas/BusinessUser"
        "business":
          "$ref": "#/components/schemas/Business"
    "MerchantOverviewEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "merchant_id":
              "type": "integer"
            "wallets":
              "type": "array"
              "items":
                "$ref": "#/components/schemas/Wallet"
            "branches":
              "type": "array"
              "items":
                "type": "object"
                "properties":
                  "branch_id":
                    "type": "integer"
                  "balance":
                    "type": "number"
                  "currency_code":
                    "type": "string"
    "MerchantTransactionPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "array"
          "items":
            "$ref": "#/components/schemas/Transaction"
        "meta":
          "$ref": "#/components/schemas/PaginationMeta"
    "SettlementEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Settlement"
    "PaymentLinkEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "merchant_id":
              "type": "integer"
            "amount":
              "type": "number"
            "currency_code":
              "type": "string"
            "description":
              "type":
                - "string"
                - "null"
            "payment_link":
              "type": "string"
              "format": "uri"
    "QrPaymentEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "qr_string":
              "type": "string"
    "PaymentServiceListEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "services":
              "type": "array"
              "items":
                "$ref": "#/components/schemas/PaymentService"
            "count":
              "type": "integer"
    "PaymentServiceEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "service":
              "$ref": "#/components/schemas/PaymentService"
    "PaymentServiceSelectionEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "properties":
            "service":
              "$ref": "#/components/schemas/PaymentService"
            "next_action":
              "type": "object"
              "additionalProperties": true
            "trace_id":
              "type":
                - "string"
                - "null"
    "PaymentEnvelope":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
          "example": true
        "data":
          "$ref": "#/components/schemas/PaymentResult"
    "PayoutEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "message":
          "type":
            - "string"
            - "null"
        "message_translated":
          "type":
            - "string"
            - "null"
        "data":
          "$ref": "#/components/schemas/Payout"
    "PayoutPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "allOf":
            -
              "type": "object"
              "properties":
                "data":
                  "type": "array"
                  "items":
                    "$ref": "#/components/schemas/Payout"
            -
              "$ref": "#/components/schemas/PaginationMeta"
    "SettlementPageEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "allOf":
            -
              "type": "object"
              "properties":
                "data":
                  "type": "array"
                  "items":
                    "$ref": "#/components/schemas/Settlement"
            -
              "$ref": "#/components/schemas/PaginationMeta"
    "ReportEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "boolean"
          "example": true
        "data":
          "type": "object"
          "additionalProperties": true
    "WebhookReceiptEnvelope":
      "type": "object"
      "properties":
        "status":
          "type": "string"
          "enum":
            - "accepted"
            - "rejected"
        "duplicate":
          "type": "boolean"
          "default": false