{
  "openapi": "3.1.0",
  "info": {
    "title": "FamGateway API",
    "version": "2.0.0",
    "description": "Official REST API specification for FamGateway \u2014 India's 100% free, non-custodial automated FamPay UPI payment gateway recognized by Ministry of MSME, Govt. of India (UDYAM-BR-28-0050000). Founded by Aryan Gupta (Aryanispe).",
    "contact": {
      "name": "Aryan Gupta (Aryanispe)",
      "url": "https://famgateway.in",
      "email": "aryanispe@gmail.com"
    },
    "license": {
      "name": "Proprietary / Developer Fair Use",
      "url": "https://famgateway.in/terms.php"
    }
  },
  "servers": [
    {
      "url": "https://famgateway.in",
      "description": "Production Server"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "BearerAuth": []
    },
    {
      "ApiKeyQuery": []
    }
  ],
  "paths": {
    "/api/create-order": {
      "post": {
        "summary": "Create Payment Order & Generate Dynamic QR (Canonical REST API)",
        "description": "Primary production endpoint for creating a dynamic UPI payment session. Generates an atomic 5-minute order session with Bank UTR Idempotency locking, returning deep links, QR payload, and hosted checkout URL.",
        "operationId": "createOrderCanonical",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Merchant API Key (can also be passed via X-Api-Key header)",
                    "example": "fg_live_a1b2c3d4e5f6"
                  },
                  "amount": {
                    "type": "number",
                    "format": "float",
                    "description": "Payment amount in INR (e.g. 499 or 499.00)",
                    "example": 499.0
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Customer full name or user identifier",
                    "example": "Rahul Sharma"
                  },
                  "customer_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email address",
                    "example": "rahul@example.com"
                  },
                  "customer_phone": {
                    "type": "string",
                    "description": "Customer 10-digit mobile number",
                    "example": "9876543210"
                  },
                  "redirect_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Where to redirect customer after hosted checkout payment",
                    "example": "https://yoursite.com/payment-success"
                  },
                  "webhook_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Custom webhook destination override for this specific order",
                    "example": "https://yoursite.com/api/famgateway-webhook"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (Cloudflare L7 Flood Protection)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/qr.php": {
      "get": {
        "summary": "Create Payment Order via Query Parameters (Terminal & POS Alias)",
        "description": "Lightweight GET query parameter alias for creating an order session or displaying dynamic QR codes on hardware POS, IoT terminals, and rapid shell scripts.",
        "operationId": "createOrderQueryAlias",
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "description": "Your Merchant API Key (or pass via X-Api-Key header)",
            "schema": {
              "type": "string",
              "example": "fg_live_a1b2c3d4e5f6"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "description": "The base order amount in INR (e.g. 499 or 499.00)",
            "schema": {
              "type": "number",
              "format": "float",
              "example": 499.0
            }
          },
          {
            "name": "customer_name",
            "in": "query",
            "required": false,
            "description": "Optional customer full name or identifier",
            "schema": {
              "type": "string",
              "example": "Rahul Sharma"
            }
          },
          {
            "name": "redirect_url",
            "in": "query",
            "required": false,
            "description": "Optional merchant redirect URL after payment",
            "schema": {
              "type": "string",
              "format": "uri",
              "example": "https://yoursite.com/payment-success"
            }
          },
          {
            "name": "webhook_url",
            "in": "query",
            "required": false,
            "description": "Optional custom webhook endpoint URL for this order",
            "schema": {
              "type": "string",
              "format": "uri",
              "example": "https://yoursite.com/api/famgateway-webhook"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout-status.php": {
      "get": {
        "summary": "Public Frontend Order Status Polling (No Auth Required)",
        "description": "Lightweight client-side polling endpoint for frontend browser checkouts. Exposes no secret keys and returns cached verification state in <25ms.",
        "operationId": "getCheckoutStatus",
        "security": [],
        "parameters": [
          {
            "name": "order_id",
            "in": "query",
            "required": true,
            "description": "The unique Order ID returned from the create order endpoint",
            "schema": {
              "type": "string",
              "example": "fg_A1B2C3D4"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current order lifecycle status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "pending",
                        "expired"
                      ],
                      "example": "success"
                    },
                    "order_id": {
                      "type": "string",
                      "example": "fg_A1B2C3D4"
                    },
                    "utr": {
                      "type": "string",
                      "example": "420987654321"
                    },
                    "transaction_id": {
                      "type": "string",
                      "example": "FMP987654321"
                    },
                    "sender_name": {
                      "type": "string",
                      "example": "Rahul Sharma"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing order_id parameter"
          }
        }
      }
    },
    "/api/verify-order.php": {
      "get": {
        "summary": "Authoritative Server-to-Server Order Verification",
        "description": "Authoritative endpoint for backend verification returning full transaction metadata, Bank UTR, and payer details. Returns HTTP 408 if order expired without payment.",
        "operationId": "verifyOrder",
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "description": "Merchant API Key (or pass via X-Api-Key header)",
            "schema": {
              "type": "string",
              "example": "fg_live_a1b2c3d4e5f6"
            }
          },
          {
            "name": "order_id",
            "in": "query",
            "required": true,
            "description": "The unique Order ID to inspect",
            "schema": {
              "type": "string",
              "example": "fg_A1B2C3D4"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order verification details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "pending",
                        "expired"
                      ],
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "order_id": {
                          "type": "string",
                          "example": "fg_A1B2C3D4"
                        },
                        "transaction_id": {
                          "type": "string",
                          "example": "FMP987654321"
                        },
                        "amount": {
                          "type": "number",
                          "example": 499
                        },
                        "payable_amount": {
                          "type": "number",
                          "example": 499.00
                        },
                        "utr": {
                          "type": "string",
                          "example": "420987654321"
                        },
                        "sender_name": {
                          "type": "string",
                          "example": "Rahul Sharma"
                        },
                        "payment_time_ist": {
                          "type": "string",
                          "example": "08-09-2026 14:31:12"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized \u2014 invalid or missing API Key"
          },
          "404": {
            "description": "Order not found"
          },
          "408": {
            "description": "Order expired \u2014 payment session timed out after 5 minutes"
          }
        }
      }
    },
    "/transaction-details.php": {
      "get": {
        "summary": "Download Official Signed PDF Transaction Receipt & Invoice",
        "description": "Generates and streams an immutable A4 PDF transaction invoice with Ministry of MSME registration (UDYAM-BR-28-0050000).",
        "operationId": "downloadPdfReceipt",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "The unique order ID or transaction reference",
            "schema": {
              "type": "string",
              "example": "fg_A1B2C3D4"
            }
          },
          {
            "name": "download",
            "in": "query",
            "required": true,
            "description": "Must be set to 'pdf' to trigger the binary PDF download",
            "schema": {
              "type": "string",
              "enum": [
                "pdf"
              ],
              "example": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Official binary PDF file stream",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Transaction not found"
          }
        }
      }
    }
  },
  "webhooks": {
    "paymentSuccess": {
      "post": {
        "summary": "Instant Payment Notification (IPN)",
        "description": "Dispatched to the merchant's configured webhook endpoints upon successful UPI payment clearance.",
        "headers": {
          "X-FamGateway-Signature": {
            "description": "HMAC-SHA256 signature computed over the raw JSON payload using your Merchant Default API Key as secret.",
            "schema": {
              "type": "string"
            }
          },
          "X-FamGateway-Event": {
            "description": "Event name identifier (always 'payment.success')",
            "schema": {
              "type": "string",
              "example": "payment.success"
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "example": "payment.success"
                  },
                  "order_id": {
                    "type": "string",
                    "example": "fg_A1B2C3D4"
                  },
                  "amount": {
                    "type": "number",
                    "example": 499
                  },
                  "payable_amount": {
                    "type": "number",
                    "example": 499.00
                  },
                  "status": {
                    "type": "string",
                    "example": "success"
                  },
                  "transaction_id": {
                    "type": "string",
                    "example": "FMP987654321"
                  },
                  "utr": {
                    "type": "string",
                    "example": "420987654321"
                  },
                  "sender_name": {
                    "type": "string",
                    "example": "Rahul Sharma"
                  },
                  "payment_time": {
                    "type": "string",
                    "example": "08-09-2026 14:31:12"
                  },
                  "timestamp": {
                    "type": "integer",
                    "example": 1788352710
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook received successfully (must return HTTP 200 within 10 seconds to avoid retry backoff)"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Recommended: Pass your Merchant API Key via HTTP request header"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass your Merchant API Key as Bearer token"
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "Legacy/script testing: Pass your API Key as query parameter"
      }
    },
    "schemas": {
      "CreateOrderResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "data": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "example": "fg_A1B2C3D4"
              },
              "qr_url": {
                "type": "string",
                "format": "uri",
                "example": "https://famgateway.in/api/qr-image.php?order_id=fg_A1B2C3D4"
              },
              "checkout_url": {
                "type": "string",
                "format": "uri",
                "example": "https://famgateway.in/pay.php?order_id=fg_A1B2C3D4"
              },
              "upi_id": {
                "type": "string",
                "example": "merchant@fam"
              },
              "amount": {
                "type": "string",
                "example": "499"
              },
              "payable_amount": {
                "type": "string",
                "example": "499.00"
              },
              "upi_intent": {
                "type": "string",
                "example": "upi://pay?pa=merchant@fam&pn=FamPay&tr=fg_A1B2C3D4&tn=fg_A1B2C3D4&am=499.00&cu=INR"
              },
              "created_at_ist": {
                "type": "string",
                "example": "08-09-2026 14:30:00"
              },
              "expires_at_ist": {
                "type": "string",
                "example": "08-09-2026 14:35:00"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string",
            "example": "Missing or invalid amount parameter"
          }
        }
      }
    }
  }
}