{
  "openapi": "3.0.3",
  "info": {
    "title": "XPayr Merchant & Webhook API",
    "description": "Official OpenAPI 3.0 specification for XPayr crypto payment sessions, router settlement, and webhooks.",
    "version": "1.0.0",
    "contact": {
      "name": "XPayr Engineering",
      "url": "https://xpayr.com/doc-api"
    }
  },
  "servers": [
    {
      "url": "https://xpayr.com/api/v1",
      "description": "Production Mainnet & Testnet API"
    }
  ],
  "paths": {
    "/payments": {
      "post": {
        "summary": "Create Payment Session",
        "description": "Initializes a non-custodial crypto payment session supporting Dual Checkout (Web3 1-Click Pay & Direct Transfer / QR with on-chain explorer verification), multi-chain asset selection, and reusable link modes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount", "currency", "order_id"],
                "properties": {
                  "amount": { "type": "number", "example": 50.00 },
                  "currency": { "type": "string", "example": "USDT" },
                  "network": { "type": "string", "example": "tron-mainnet", "description": "Blockchain network key (e.g. tron-mainnet, bsc-mainnet, solana-mainnet). Can be omitted if is_multi_chain is true." },
                  "order_id": { "type": "string", "example": "ORD-12345" },
                  "description": { "type": "string", "example": "Premium Membership Plan" },
                  "is_multi_chain": { "type": "boolean", "default": false, "description": "When true, customer can select from all active merchant networks and assets at checkout." },
                  "is_reusable": { "type": "boolean", "default": false, "description": "When true, the payment link remains active for 1 year and allows recurring or repeated payments." },
                  "send_invoice_email": { "type": "boolean", "default": false, "description": "When true and customer_email is set, dispatches a branded invoice email to the customer." },
                  "customer_email": { "type": "string", "format": "email", "example": "buyer@example.com" },
                  "coupon_code": { "type": "string", "example": "XPAYR-DEMO" },
                  "ipn_callback_url": { "type": "string", "example": "https://mystore.com/api/xpayr_webhook" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string", "example": "ps_89a0b1c2d3e4f5a6" },
                    "checkout_url": { "type": "string", "example": "https://xpayr.com/pay/ps_89a0b1c2d3e4f5a6" },
                    "amount": { "type": "number", "example": 50.00 },
                    "currency": { "type": "string", "example": "USDT" },
                    "network": { "type": "string", "example": "tron-mainnet" },
                    "is_multi_chain": { "type": "boolean", "example": true },
                    "is_reusable": { "type": "boolean", "example": false },
                    "status": { "type": "string", "example": "pending" },
                    "expires_at": { "type": "string", "example": "2026-10-04T19:00:00+00:00" },
                    "discount_applied": { "type": "number", "example": 5.00 },
                    "effective_price": { "type": "number", "example": 45.00 }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/webhooks": {
      "post": {
        "summary": "Register Webhook Endpoint",
        "description": "Configures a webhook callback receiver for payment lifecycle events.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "example": "https://mystore.com/api/xpayr_webhook" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook registered and secret returned"
          }
        }
      }
    }
  }
}