From 600b9fcee0914ce3c4134a7847bc5b9da52b8791 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 21 Apr 2026 12:04:11 +0700 Subject: [PATCH 1/2] docs: add Stripe session retrieval endpoint to OpenAPI specification Introduced a new endpoint for retrieving a Stripe checkout session by its client reference ID. The OpenAPI specification now includes detailed descriptions of the endpoint, required parameters, and response schemas for successful and error cases. Additionally, updated the documentation to include a new group for Stripe in the navigation structure. --- api-reference/openapi/accounts.json | 146 +++++++++++++++++++++++++ api-reference/stripe/sessions-list.mdx | 4 + docs.json | 6 + 3 files changed, 156 insertions(+) create mode 100644 api-reference/stripe/sessions-list.mdx diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index 4ad84341..dccb0248 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -415,6 +415,88 @@ } } }, + "/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": "UUID of the account to query sessions for. Admin-only override — 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/GetStripeSessionErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized — invalid or missing authentication", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetStripeSessionErrorResponse" + } + } + } + }, + "404": { + "description": "No session found with the given `referenceId`", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetStripeSessionErrorResponse" + } + } + } + } + } + } + }, "/api/workspaces": { "post": { "description": "Create a new workspace account. Workspaces can optionally be linked to an organization.", @@ -2934,6 +3016,70 @@ "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" + } + } + } + }, + "GetStripeSessionErrorResponse": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Human-readable error message.", + "example": "referenceId is required" + } + } } } } diff --git a/api-reference/stripe/sessions-list.mdx b/api-reference/stripe/sessions-list.mdx new file mode 100644 index 00000000..f92e8d6e --- /dev/null +++ b/api-reference/stripe/sessions-list.mdx @@ -0,0 +1,4 @@ +--- +title: 'List Stripe Sessions' +openapi: '/api-reference/openapi/accounts.json GET /api/stripe/sessions' +--- diff --git a/docs.json b/docs.json index 997442ca..e189a650 100644 --- a/docs.json +++ b/docs.json @@ -331,6 +331,12 @@ "api-reference/subscriptions/get" ] }, + { + "group": "Stripe", + "pages": [ + "api-reference/stripe/sessions-list" + ] + }, { "group": "Admins", "pages": [ From 8e3562a0930511fd71a47662dc3de70599875307 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 21 Apr 2026 12:23:23 +0700 Subject: [PATCH 2/2] docs: update Stripe session endpoint and refine account query descriptions Replaced the Stripe sessions list endpoint with a new session retrieval endpoint in the documentation. Updated the OpenAPI specification to enhance the description of the `accountId` query parameter, clarifying its applicability for accounts with organization membership. Changed error response references from `GetStripeSessionErrorResponse` to `AccountErrorResponse` for consistency. Removed the obsolete sessions list documentation file. --- api-reference/openapi/accounts.json | 31 +++++++++---------- .../{sessions-list.mdx => session-get.mdx} | 2 +- docs.json | 2 +- 3 files changed, 16 insertions(+), 19 deletions(-) rename api-reference/stripe/{sessions-list.mdx => session-get.mdx} (72%) diff --git a/api-reference/openapi/accounts.json b/api-reference/openapi/accounts.json index dccb0248..4768946d 100644 --- a/api-reference/openapi/accounts.json +++ b/api-reference/openapi/accounts.json @@ -445,7 +445,7 @@ { "name": "accountId", "in": "query", - "description": "UUID of the account to query sessions for. Admin-only override — if not provided, the API key's own account is used.", + "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", @@ -469,7 +469,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetStripeSessionErrorResponse" + "$ref": "#/components/schemas/AccountErrorResponse" } } } @@ -479,7 +479,17 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetStripeSessionErrorResponse" + "$ref": "#/components/schemas/AccountErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden - account override not permitted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountErrorResponse" } } } @@ -489,7 +499,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GetStripeSessionErrorResponse" + "$ref": "#/components/schemas/AccountErrorResponse" } } } @@ -3067,19 +3077,6 @@ } } } - }, - "GetStripeSessionErrorResponse": { - "type": "object", - "required": [ - "error" - ], - "properties": { - "error": { - "type": "string", - "description": "Human-readable error message.", - "example": "referenceId is required" - } - } } } } diff --git a/api-reference/stripe/sessions-list.mdx b/api-reference/stripe/session-get.mdx similarity index 72% rename from api-reference/stripe/sessions-list.mdx rename to api-reference/stripe/session-get.mdx index f92e8d6e..fe1269bd 100644 --- a/api-reference/stripe/sessions-list.mdx +++ b/api-reference/stripe/session-get.mdx @@ -1,4 +1,4 @@ --- -title: 'List Stripe Sessions' +title: 'Get Stripe Session' openapi: '/api-reference/openapi/accounts.json GET /api/stripe/sessions' --- diff --git a/docs.json b/docs.json index e189a650..20cc5722 100644 --- a/docs.json +++ b/docs.json @@ -334,7 +334,7 @@ { "group": "Stripe", "pages": [ - "api-reference/stripe/sessions-list" + "api-reference/stripe/session-get" ] }, {