{
  "openapi": "3.0.3",
  "info": {
    "title": "CashPay Merchant API",
    "version": "1.0.0",
    "description": "HMAC-authenticated Merchant API for package-based Lightning payments. Credentials are created in the CashPay merchant dashboard."
  },
  "servers": [
    {
      "url": "https://apicashapp.luckygl.com"
    }
  ],
  "tags": [
    { "name": "System" },
    { "name": "Packages" },
    { "name": "Payments" }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "description": "Public connectivity probe. No authentication.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "service": { "type": "string", "example": "cashpay-merchant-api" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/packages": {
      "get": {
        "tags": ["Packages"],
        "summary": "List packages",
        "operationId": "listPackages",
        "security": [{ "ApiKeyAuth": [], "HmacAuth": [] }],
        "responses": {
          "200": {
            "description": "Enabled packages for the merchant",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Package" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/payments": {
      "post": {
        "tags": ["Payments"],
        "summary": "Create payment",
        "operationId": "createPayment",
        "security": [{ "ApiKeyAuth": [], "HmacAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "200": {
            "description": "Idempotent replay of an existing payment",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/Unprocessable" }
        }
      },
      "get": {
        "tags": ["Payments"],
        "summary": "Get payment by merchant order number",
        "operationId": "getPaymentByOrder",
        "security": [{ "ApiKeyAuth": [], "HmacAuth": [] }],
        "parameters": [
          {
            "name": "merchant_order_no",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "maxLength": 64 }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/Unprocessable" }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "tags": ["Payments"],
        "summary": "Get payment by id",
        "operationId": "getPaymentById",
        "security": [{ "ApiKeyAuth": [], "HmacAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "HmacAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature",
        "description": "Lowercase hex HMAC-SHA256 of the canonical string. Also send X-Timestamp and X-Nonce. See Merchant API docs."
      }
    },
    "schemas": {
      "Package": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "amount_usd": { "type": "string", "example": "100.00" },
          "sort_order": { "type": "integer" }
        }
      },
      "CreatePaymentRequest": {
        "type": "object",
        "required": ["package_id", "merchant_order_no"],
        "properties": {
          "package_id": { "type": "string", "format": "uuid" },
          "merchant_order_no": { "type": "string", "maxLength": 64 },
          "notify_url": { "type": "string", "format": "uri" },
          "metadata": { "type": "object", "additionalProperties": true }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "merchant_order_no": { "type": "string" },
          "package_id": { "type": "string", "format": "uuid" },
          "package_name": { "type": "string" },
          "amount_usd": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "paid", "expired"] },
          "bolt11": { "type": "string", "nullable": true },
          "pay_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Hosted checkout URL (frontend_url/pay/invoice/{invoice_id}). Null if frontend_url is not configured.",
            "example": "https://www.example.com/pay/invoice/9236f138-07b5-4d1c-9fe6-bea17a29bc06"
          },
          "expires_at": { "type": "string", "nullable": true },
          "paid_at": { "type": "string", "nullable": true },
          "created_at": { "type": "string" },
          "metadata": { "nullable": true }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing/invalid auth headers or signature",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Forbidden": {
        "description": "API disabled or IP not allowlisted",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unprocessable": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}