{
  "openapi": "3.1.0",
  "info": {
    "title": "FalePay Merchant Payment API",
    "version": "2026-10-14",
    "description": "Versioned machine-readable contract for server-side merchant payment integration. Every /api/v1 request uses HMAC headers; this document does not grant credentials or enable a Huifu channel."
  },
  "servers": [{ "url": "https://api.falepay.com", "description": "Production API" }],
  "tags": [{ "name": "Payments" }, { "name": "Refunds" }, { "name": "Health" }],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Health"],
        "operationId": "getHealth",
        "responses": { "200": { "description": "Service health" } }
      }
    },
    "/api/v1/payments": {
      "post": {
        "tags": ["Payments"],
        "operationId": "createPayment",
        "summary": "Create an order and obtain payer-facing payment parameters",
        "description": "The merchant_order_no is idempotent per merchant. Treat the response as a payment intent until a verified webhook or server-side query says paid. Do not use a browser redirect as payment proof.",
        "security": [{ "FalePayHmac": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } } },
        "responses": {
          "201": { "description": "Payment intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "200": { "description": "Existing idempotent intent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "503": { "$ref": "#/components/responses/ProviderUnavailable" }
        }
      },
      "get": {
        "tags": ["Payments"],
        "operationId": "listPayments",
        "security": [{ "FalePayHmac": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "name": "merchant_order_no", "in": "query", "schema": { "type": "string", "maxLength": 128 } }
        ],
        "responses": { "200": { "description": "Recent orders" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/api/v1/payments/{paymentId}": {
      "parameters": [{ "$ref": "#/components/parameters/PaymentId" }],
      "get": {
        "tags": ["Payments"], "operationId": "getPayment", "security": [{ "FalePayHmac": [] }],
        "responses": { "200": { "description": "Payment snapshot" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/api/v1/payments/{paymentId}/query": {
      "parameters": [{ "$ref": "#/components/parameters/PaymentId" }],
      "post": {
        "tags": ["Payments"], "operationId": "queryPayment", "security": [{ "FalePayHmac": [] }],
        "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } },
        "responses": { "200": { "description": "Synchronized payment snapshot" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ProviderUnavailable" } }
      }
    },
    "/api/v1/payments/{paymentId}/close": {
      "parameters": [{ "$ref": "#/components/parameters/PaymentId" }],
      "post": {
        "tags": ["Payments"], "operationId": "closePayment", "security": [{ "FalePayHmac": [] }],
        "responses": { "200": { "description": "Close result" }, "202": { "description": "Provider accepted close request; query close status before treating it as closed" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ProviderUnavailable" } }
      }
    },
    "/api/v1/payments/{paymentId}/close/query": {
      "parameters": [{ "$ref": "#/components/parameters/PaymentId" }],
      "post": {
        "tags": ["Payments"], "operationId": "queryClosePayment", "security": [{ "FalePayHmac": [] }],
        "responses": { "200": { "description": "Close status" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ProviderUnavailable" } }
      }
    },
    "/api/v1/payments/{paymentId}/refunds": {
      "parameters": [{ "$ref": "#/components/parameters/PaymentId" }],
      "post": {
        "tags": ["Refunds"], "operationId": "createRefund", "security": [{ "FalePayHmac": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } },
        "responses": { "201": { "description": "Refund submitted" }, "200": { "description": "Existing idempotent refund" }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ProviderUnavailable" } }
      }
    },
    "/api/v1/refunds/{refundId}/query": {
      "parameters": [{ "name": "refundId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "post": {
        "tags": ["Refunds"], "operationId": "queryRefund", "security": [{ "FalePayHmac": [] }],
        "responses": { "200": { "description": "Refund status" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ProviderUnavailable" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "FalePayHmac": {
        "type": "apiKey", "in": "header", "name": "X-9AIPay-Signature",
        "description": "Also send X-9AIPay-Key, X-9AIPay-Timestamp and a unique X-9AIPay-Nonce. Sign timestamp.nonce.METHOD.path.raw_body with the application api_secret using HMAC-SHA256 and prefix sha256=. The path includes its query string; raw_body is the exact UTF-8 JSON bytes sent. Timestamp skew is 5 minutes and nonce replay is rejected."
      }
    },
    "parameters": {
      "PaymentId": { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Strongly recommended: use a stable unique value for a refund retry. Reusing it returns the original result; without it, the caller must prevent duplicate submissions." }
    },
    "schemas": {
      "CreatePaymentRequest": {
        "type": "object", "additionalProperties": false, "required": ["merchant_order_no", "amount_cents", "subject", "channel"],
        "properties": {
          "merchant_order_no": { "type": "string", "minLength": 1, "maxLength": 128 },
          "amount_cents": { "type": "integer", "minimum": 1, "description": "CNY fen; never use a floating point amount." },
          "currency": { "type": "string", "const": "CNY", "default": "CNY" },
          "subject": { "type": "string", "minLength": 1, "maxLength": 256 },
          "channel": { "type": "string", "enum": ["alipay", "wechat"] },
          "notify_url": { "type": "string", "format": "uri", "pattern": "^https://" },
          "trade_type": { "type": "string", "description": "Provider-approved trade type; JSAPI/MINIAPP also require provider-specific identity fields." },
          "sub_appid": { "type": "string" }, "sub_openid": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }
        }
      },
      "RefundRequest": {
        "type": "object", "additionalProperties": false,
        "properties": { "amount_cents": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "maxLength": 256 } }
      },
      "PaymentResponse": { "type": "object", "properties": { "order": { "type": "object" }, "payment": { "type": "object" }, "idempotent": { "type": "boolean" } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request; correct input before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing, expired, replayed or invalid HMAC request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "Merchant or provider onboarding gate is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found for this application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "Order state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ProviderUnavailable": { "description": "Upstream payment provider unavailable; do not show paid/refunded and retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "x-falepay-integration": {
    "webhook": {
      "headers": ["X-9AIPay-Webhook-Id", "X-9AIPay-Webhook-Timestamp", "X-9AIPay-Webhook-Signature"],
      "signing": "HMAC-SHA256(timestamp + '.' + webhook_id + '.' + raw_json_body)",
      "events": ["payment.succeeded"],
      "requirements": ["verify raw bytes before JSON parsing", "deduplicate by webhook id and merchant_order_no", "return 2xx quickly and process asynchronously"]
    },
    "safety": ["server-side only", "never commit api_secret", "never treat a redirect as payment proof", "no SDK method is called during installation or tests"]
  }
}
