docs: add Stripe session retrieval endpoint to OpenAPI specification

api-reference/openapi/accounts.json

@@ -415,6 +415,98 @@
         }
       }
     },
+    "/api/stripe/sessions": {
+      "get": {
+        "servers": [
+          {
+            "url": "https://api.recoupable.com"
+          }
+        ],
+        "description": "Retrieve a Stripe checkout session by its client reference ID. Returns the full Stripe session object for the matching session. Useful for verifying payment status after a checkout redirect.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "referenceId",
+            "in": "query",
+            "description": "The `client_reference_id` value that was set when the checkout session was created.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "accountId",
+            "in": "query",
+            "description": "Filter to a specific account. Only applicable when the authenticated account has access to multiple accounts via organization membership; if not provided, the API key's own account is used.",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stripe session found and returned successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetStripeSessionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request — missing or invalid `referenceId`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized — invalid or missing authentication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - account override not permitted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No session found with the given `referenceId`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AccountErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/workspaces": {
       "post": {
         "description": "Create a new workspace account. Workspaces can optionally be linked to an organization.",
@@ -2934,6 +3026,57 @@
             "example": "Verified"
           }
         }
+      },
+      "GetStripeSessionResponse": {
+        "type": "object",
+        "description": "A Stripe checkout session object. For the full list of available properties, see the [Stripe Checkout Session API documentation](https://docs.stripe.com/api/checkout/sessions/object).",
+        "required": [
+          "id",
+          "status",
+          "url"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the Stripe checkout session.",
+            "example": "cs_test_a1b2c3d4e5f6g7h8i9j0"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["open", "complete", "expired"],
+            "description": "Current status of the checkout session.",
+            "example": "complete"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "nullable": true,
+            "description": "The URL to the hosted checkout page. Present while the session is open.",
+            "example": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
+          },
+          "client_reference_id": {
+            "type": "string",
+            "description": "The value passed as `referenceId` when the session was created.",
+            "example": "123e4567-e89b-12d3-a456-426614174000"
+          },
+          "customer_email": {
+            "type": "string",
+            "format": "email",
+            "nullable": true,
+            "description": "Email address of the customer, if collected.",
+            "example": "user@example.com"
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Set of key-value pairs attached to the session at creation time.",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "example": {
+              "accountId": "123e4567-e89b-12d3-a456-426614174000"
+            }
+          }
+        }
       }
     }
   }

api-reference/stripe/session-get.mdx

@@ -0,0 +1,4 @@
+---
+title: 'Get Stripe Session'
+openapi: '/api-reference/openapi/accounts.json GET /api/stripe/sessions'
+---

docs.json

@@ -331,6 +331,12 @@
               "api-reference/subscriptions/get"
             ]
           },
+          {
+            "group": "Stripe",
+            "pages": [
+              "api-reference/stripe/session-get"
+            ]
+          },
           {
             "group": "Admins",
             "pages": [