{ "openapi": "3.0.3", "info": { "title": "BEXO Vendor & Integration API", "version": "2026-10-19.1", "description": "Selected owner, checkout, member-consent, terminal and sandbox contracts. Credential types are not interchangeable. Availability depends on deployed configuration and account approval. This reference is not a declaration of production acceptance.", "contact": { "name": "BEXO integration support", "url": "https://mybexo.com/pages/contact" }, "x-source-commit": "b93a4d3" }, "servers": [ { "url": "https://dash.mybexo.com/api", "description": "Production API through the dashboard origin." }, { "url": "http://localhost:5001/api", "description": "Isolated local API." } ], "tags": [ { "name": "vendor-api" }, { "name": "authentication" }, { "name": "checkout" }, { "name": "consent" }, { "name": "verification-api" }, { "name": "sandbox" } ], "paths": { "/vendor/me": { "get": { "operationId": "get__vendor_me", "tags": [ "vendor-api" ], "summary": "Read your vendor workspace", "description": "Private account data. Keep it out of public pages, analytics events and application logs. Resolves the tenant associated with the authenticated owner. Returns 404 when no application is associated.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Vendor" }, "storefrontUrl": { "type": "string", "description": "Public storefront URL.", "nullable": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/applications": { "post": { "operationId": "post__vendor_applications", "tags": [ "vendor-api" ], "summary": "Submit a business application", "description": "Creates or updates the authenticated owner’s application. PAN, GST declaration, support email and registered business details are validated. This is not live activation. Complete compliance steps in the vendor portal.", "security": [ { "MemberSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "responses": { "200": { "description": "Existing application updated or returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Vendor" } }, "additionalProperties": true } } } }, "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Vendor" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/share-link": { "get": { "operationId": "get__vendor_share_link", "tags": [ "vendor-api" ], "summary": "Read the storefront share link", "description": "Returns the owner’s public storefront URL. It is a discovery page, not proof that live checkout is enabled. Returns 409 if the URL is still being prepared.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefrontUrl": { "type": "string", "description": "Storefront URL." }, "slug": { "type": "string", "description": "Public vendor slug." }, "vendorId": { "type": "string", "description": "Vendor ID.", "format": "uuid" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/documents": { "get": { "operationId": "get__vendor_documents", "tags": [ "vendor-api" ], "summary": "List compliance documents", "description": "Lists document metadata for the current owner. Treat filenames and metadata as confidential. This reference does not expose reviewer download or biometric session APIs.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/documents/{kind}": { "post": { "operationId": "post__vendor_documents_kind", "tags": [ "vendor-api" ], "summary": "Upload a compliance document", "description": "Send multipart/form-data with one file field. Maximum 8 MiB; PDF, PNG or JPEG. Allowed kinds: business_registration, tax_id, pan_card, gst_certificate, authorized_signatory. Uploads are accepted only while the application is in a reviewable state.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "One PDF, PNG or JPEG up to 8 MiB." } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/vendor/documents/submit": { "post": { "operationId": "post__vendor_documents_submit", "tags": [ "vendor-api" ], "summary": "Submit documents for review", "description": "Checks required business registration, signatory, PAN/tax and GST documentation. GST evidence depends on the exemption declaration. DOCUMENTS_REQUIRED identifies an incomplete submission. Uploading does not approve the vendor.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Submission accepted." }, "message": { "type": "string", "description": "Acknowledgment." } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/plans": { "get": { "operationId": "get__vendor_plans", "tags": [ "vendor-api" ], "summary": "List plans and checkout URLs", "description": "Lists plans for the authenticated vendor, including unpublished plans. A checkout URL in the response does not bypass vendor approval or the active-plan check.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } }, "post": { "operationId": "post__vendor_plans", "tags": [ "vendor-api" ], "summary": "Create a vendor plan", "description": "Creates a plan. one_time requires durationDays; monthly defaults to 30 if omitted. Use durations of 1–366 for checkout compatibility. The plan is active only for a production_active vendor. Provider provisioning is configuration-dependent.", "security": [ { "MemberSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInput" }, "example": { "name": "Monthly access", "durationDays": 30, "pricePaise": 150000, "billingPeriod": "one_time", "taxInclusive": true } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/plans/{planId}": { "patch": { "operationId": "patch__vendor_plans_planId", "tags": [ "vendor-api" ], "summary": "Update or pause a plan", "description": "Updates a plan belonging to the owner. Set isActive=false to pause new sales. Publishing again requires approval. Existing purchase snapshots are separate from changes to the current plan.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdate" }, "example": { "isActive": false } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/owner/subscriptions": { "get": { "operationId": "get__vendor_owner_subscriptions", "tags": [ "vendor-api" ], "summary": "List recent memberships", "description": "Returns up to 100 recent memberships for the vendor, newest first. No pagination is documented for this endpoint. Use reporting endpoints for supported exports.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/owner/verifications": { "get": { "operationId": "get__vendor_owner_verifications", "tags": [ "vendor-api" ], "summary": "List recent verification events", "description": "Returns up to 100 recent tenant-scoped events. Each event includes id, membershipId, decision, reason and createdAt.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID.", "format": "uuid" }, "membershipId": { "type": "string", "description": "Membership ID.", "format": "uuid", "nullable": true }, "decision": { "type": "string", "description": "allow or deny." }, "reason": { "type": "string", "description": "Decision reason." }, "createdAt": { "type": "string", "description": "Event time.", "format": "date-time", "nullable": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/terminals": { "get": { "operationId": "get__vendor_terminals", "tags": [ "vendor-api" ], "summary": "List registered readers", "description": "Returns readers for the owner’s tenant. A reader serial identifies the device; it cannot authenticate a request alone.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "terminals": { "type": "array", "items": { "$ref": "#/components/schemas/Terminal" } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } }, "post": { "operationId": "post__vendor_terminals", "tags": [ "vendor-api" ], "summary": "Register a reader", "description": "Registers an owner-scoped terminal. Suspended vendors cannot register devices. Serial numbers must be unique; omit serialNumber to receive a generated identifier.", "security": [ { "MemberSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalInput" }, "example": { "label": "Reception" } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Created." }, "terminal": { "$ref": "#/components/schemas/Terminal" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/terminals/{terminalId}": { "patch": { "operationId": "patch__vendor_terminals_terminalId", "tags": [ "vendor-api" ], "summary": "Update a reader", "description": "Updates a terminal owned by the authenticated vendor. Returned status and revocation state should be reviewed before using a reader.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalUpdate" } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Updated." }, "terminal": { "$ref": "#/components/schemas/Terminal" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/api-logs": { "get": { "operationId": "get__vendor_api_logs", "tags": [ "vendor-api" ], "summary": "Read paginated device logs", "description": "Returns masked card identifiers, operational decisions, timing and usage fields. Do not treat masked identifiers as credentials or access proof.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "terminalId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "decision", "in": "query", "schema": { "type": "string", "enum": [ "allow", "deny", "error" ] } } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page." }, "limit": { "type": "integer", "description": "Page size." }, "total": { "type": "integer", "description": "Matching rows." }, "totalPages": { "type": "integer", "description": "Pages." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/reports/subscribers": { "get": { "operationId": "get__vendor_reports_subscribers", "tags": [ "vendor-api" ], "summary": "Export subscribers", "description": "Membership records and total/active/grace/expired counts. Supports search and status filters. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "last_7_days", "last_30_days", "this_month" ] }, "description": "Preset reporting period. Presets take precedence over custom dates." }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "csv returns text/csv; otherwise JSON." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/reports/financial-revenue": { "get": { "operationId": "get__vendor_reports_financial_revenue", "tags": [ "vendor-api" ], "summary": "Export financial revenue", "description": "Transaction and gross/commission/net summary fields. These are application reports, not proof of provider settlement or bank reconciliation. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "last_7_days", "last_30_days", "this_month" ] }, "description": "Preset reporting period. Presets take precedence over custom dates." }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "csv returns text/csv; otherwise JSON." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/reports/terminal-verifications": { "get": { "operationId": "get__vendor_reports_terminal_verifications", "tags": [ "vendor-api" ], "summary": "Export terminal verifications", "description": "Recorded verification events and operational usage summaries. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "last_7_days", "last_30_days", "this_month" ] }, "description": "Preset reporting period. Presets take precedence over custom dates." }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "csv returns text/csv; otherwise JSON." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/reports/metered-billing": { "get": { "operationId": "get__vendor_reports_metered_billing", "tags": [ "vendor-api" ], "summary": "Export metered billing", "description": "Recorded usage statements plus tenantDetails, platformDetails and summary. Confirm your contractual billing terms independently of display defaults. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "csv returns text/csv; otherwise JSON." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "summary": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/identity/v1/keys": { "get": { "operationId": "get__identity_v1_keys", "tags": [ "authentication" ], "summary": "List live-key metadata", "description": "Approved vendor owner only. Returns metadata for up to 100 live keys. Raw key material is not returned.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/KeyMetadata" } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } }, "post": { "operationId": "post__identity_v1_keys", "tags": [ "authentication" ], "summary": "Live key issuance is unavailable", "description": "The reference implementation intentionally returns 503 for approved owners until a supported server-side secret delivery channel exists. This is not a working key-creation endpoint.", "security": [ { "MemberSession": [] } ], "responses": { "503": { "description": "Unavailable in this reference; not a successful credential operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/identity/v1/keys/{id}/revoke": { "post": { "operationId": "post__identity_v1_keys_id_revoke", "tags": [ "authentication" ], "summary": "Revoke a live integration key", "description": "Approved owner only. Revokes an active key owned by the tenant. Repeated revocation can return 404; do not interpret that as a new credential.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "description": "Key ID.", "format": "uuid" }, "revokedAt": { "type": "string", "description": "Revocation time.", "format": "date-time", "nullable": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/identity/v1/keys/{id}/rotate": { "post": { "operationId": "post__identity_v1_keys_id_rotate", "tags": [ "authentication" ], "summary": "Live key rotation is unavailable", "description": "The reference implementation intentionally returns 503 for approved owners. Arrange credential provisioning through your BEXO integration contact.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "responses": { "503": { "description": "Unavailable in this reference; not a successful credential operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/public/{slug}/{tenantId}": { "get": { "operationId": "get__vendor_public_slug_tenantId", "tags": [ "checkout" ], "summary": "Read a public storefront", "description": "Returns public vendor metadata, availability and plans. Unapproved vendors return coming_soon and an empty plans list.", "security": [], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor": { "type": "object", "properties": {}, "additionalProperties": true }, "availability": { "type": "string", "description": "Storefront state.", "enum": [ "available", "coming_soon" ] }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/public/checkout-link": { "post": { "operationId": "post__vendor_public_checkout_link", "tags": [ "checkout" ], "summary": "Create a public checkout link", "description": "Requires an active plan and a production_active vendor. Prefer redirecting the buyer to the returned hosted URL. This route returns a server-issued token; never construct one.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLinkInput" } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/checkout-links": { "post": { "operationId": "post__vendor_checkout_links", "tags": [ "checkout" ], "summary": "Create an owner checkout link", "description": "Requires an approved owner and active, tenant-owned plan. Returns a stable hosted plan URL; every purchase still checks current availability.", "security": [ { "MemberSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLinkInput" }, "example": { "tenantPlanId": "11111111-1111-4111-8111-111111111111" } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/checkout-links/{token}": { "get": { "operationId": "get__vendor_checkout_links_token", "tags": [ "checkout" ], "summary": "Read checkout details", "description": "Returns the vendor, plan, termsVersion, billingPeriod and expiresAt. PLAN_PAUSED means the business has disabled this plan. Keep the token and buyer details out of logs.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Checkout token; do not log." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor": { "type": "object", "properties": {}, "additionalProperties": true }, "plan": { "$ref": "#/components/schemas/Plan" }, "termsVersion": { "type": "string", "description": "Version to pass at checkout." }, "billingPeriod": { "type": "string", "description": "Server mode." }, "expiresAt": { "type": "string", "description": "Returned availability hint." } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/checkout": { "post": { "operationId": "post__vendor_checkout", "tags": [ "checkout" ], "summary": "Start or retry a purchase", "description": "Buyer session, not vendor-owner authority. A new purchase requires phone verification within the last hour and current terms acceptance. Keep the same Idempotency-Key for a retry of the same token. The server fixes the amount, currency, duration and plan name.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "Stable key per buyer purchase attempt; do not change it after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutInput" }, "example": { "checkoutToken": "", "acceptedTerms": true, "acceptedTermsVersion": "" } } } }, "responses": { "200": { "description": "Existing purchase returned on an idempotent retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/checkout/{membershipId}/reconcile": { "post": { "operationId": "post__vendor_checkout_membershipId_reconcile", "tags": [ "checkout" ], "summary": "Reconcile provider payment proof", "description": "Buyer must own the purchase. Supply the original provider callback proof. The server verifies the signature and capture facts; a client callback alone cannot activate access.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProof" } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "membership": { "type": "object", "properties": { "id": { "type": "string", "description": "Membership.", "format": "uuid" }, "status": { "type": "string", "description": "Confirmed state." }, "validUntil": { "type": "string", "description": "Validity.", "format": "date-time", "nullable": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/memberships": { "get": { "operationId": "get__vendor_memberships", "tags": [ "consent" ], "summary": "Read the signed-in member’s memberships", "description": "Returns memberships for the signed-in member. Old pending purchases are filtered after the 30-minute pending window. This route is not an owner’s list of all customers.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "memberships": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/memberships/{membershipId}/resume": { "post": { "operationId": "post__vendor_memberships_membershipId_resume", "tags": [ "checkout" ], "summary": "Resume a pending purchase", "description": "Buyer-owned pending purchases may be resumed for 30 minutes after creation. Reuses the original provider references. Returns 410 CHECKOUT_EXPIRED after the window.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/consents": { "get": { "operationId": "get__vendor_consents", "tags": [ "consent" ], "summary": "Read a member’s disclosure choices", "description": "Returns the signed-in member’s consent records, including purpose, fields, grantedAt and revokedAt.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "consents": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/consents/pending": { "get": { "operationId": "get__vendor_consents_pending", "tags": [ "consent" ], "summary": "Read pending consent requests", "description": "Returns active/grace memberships with no consent record. A previously revoked record is not necessarily included in this list.", "security": [ { "MemberSession": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/vendor/consents/{membershipId}": { "put": { "operationId": "put__vendor_consents_membershipId", "tags": [ "consent" ], "summary": "Grant or revoke membership consent", "description": "Only the membership’s member can change consent. Set granted=false and fields=[] to revoke. An owner or terminal integration key cannot grant consent on behalf of a member.", "security": [ { "MemberSession": [] } ], "parameters": [ { "name": "membershipId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentInput" }, "example": { "granted": true, "purpose": "membership_verification", "fields": [ "membership_status", "valid_until" ] } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "consent": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/pos/v1/ping": { "get": { "operationId": "get__pos_v1_ping", "tags": [ "verification-api" ], "summary": "Check a registered reader connection", "description": "Requires verify:write scope and a registered terminal identifier. Returns vendor, terminal and serverTime; also updates terminal telemetry.", "security": [ { "TenantKey": [] } ], "parameters": [ { "name": "X-Terminal-Serial", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Registered reader serial in the same tenant as the integration key." } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "online." }, "vendor": { "type": "object", "properties": { "id": { "type": "string", "description": "Tenant ID.", "format": "uuid" }, "displayName": { "type": "string", "description": "Name." } }, "additionalProperties": true }, "terminal": { "$ref": "#/components/schemas/Terminal" }, "serverTime": { "type": "string", "description": "Server ISO time.", "format": "date-time" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/pos/v1/verify": { "post": { "operationId": "post__pos_v1_verify", "tags": [ "verification-api" ], "summary": "Evaluate a card or QR tap", "description": "Requires verify:write and a registered reader in the same tenant. The server evaluates current entitlement using its clock. HTTP 200 with decision=deny is a valid business result, not a transport failure. Treat all subscriber data as private and enforce the member’s current disclosure permissions in your client.", "security": [ { "TenantKey": [] } ], "parameters": [ { "name": "X-Terminal-Serial", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Registered reader serial in the same tenant as the integration key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TapInput" }, "example": { "cardUid": "", "timestamp": "2026-10-19T09:00:00Z" } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TapResult" }, "example": { "verified": false, "decision": "deny", "decisionReason": "member_not_found", "status": "not_found", "subscriber": null, "terminal": { "id": "11111111-1111-4111-8111-111111111111", "label": "Reception", "serialNumber": "", "hardwareModel": "BEXO-POS-T1" }, "billing": { "billedPaise": 50, "costRupees": 0.5, "costDisplay": "₹0.50" }, "latencyMs": 18, "timestamp": "2026-10-19T09:00:00Z", "logId": "11111111-1111-4111-8111-111111111111" } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/pos/v1/batch-verify": { "post": { "operationId": "post__pos_v1_batch_verify", "tags": [ "verification-api" ], "summary": "Synchronize buffered tap requests", "description": "Accepts {taps:[…]}, a raw array, or a single tap. Prefer the taps object. Results are evaluated by the server at synchronization time; this is not offline authorization. Retries can create new log/usage entries because no batch idempotency key is documented.", "security": [ { "TenantKey": [] } ], "parameters": [ { "name": "X-Terminal-Serial", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Registered reader serial in the same tenant as the integration key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taps": { "type": "array", "items": { "$ref": "#/components/schemas/TapInput" } } }, "required": [ "taps" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "processedCount": { "type": "integer", "description": "Results processed." }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Per-item processing result." }, "result": { "$ref": "#/components/schemas/TapResult" }, "error": { "type": "string", "description": "Per-item failure, when present." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } } } }, "/identity/tenants": { "post": { "operationId": "post__identity_tenants", "tags": [ "sandbox" ], "summary": "Bootstrap an isolated sandbox tenant", "description": "Use only an agreed isolated test deployment. Creates a sandbox_only tenant and returns a sandbox credential once. Store the key in a server-side secret store immediately. Does not issue live credentials or approve a vendor.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxTenantInput" }, "example": { "legalName": "Example Test Organization", "displayName": "Example Sandbox", "contactEmail": "developer@example.com" } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Vendor" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Credential ID.", "format": "uuid" }, "keyPrefix": { "type": "string", "description": "Safe display prefix." }, "environment": { "type": "string", "description": "sandbox." }, "key": { "type": "string", "description": "One-time credential; never log or publish." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } }, "/identity/tenants/me": { "get": { "operationId": "get__identity_tenants_me", "tags": [ "sandbox" ], "summary": "Read a sandbox tenant", "description": "Sandbox key with verify:read. Live environment keys are rejected by the sandbox-only gate.", "security": [ { "TenantKey": [] } ], "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Vendor" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } }, "/identity/terminals": { "post": { "operationId": "post__identity_terminals", "tags": [ "sandbox" ], "summary": "Register a sandbox terminal", "description": "Sandbox key with verify:write. label is required. serialNumber, devicePublicKey and firmwareVersion are optional.", "security": [ { "TenantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Device label." }, "serialNumber": { "type": "string", "description": "Optional serial." }, "devicePublicKey": { "type": "string", "description": "Optional public key." }, "firmwareVersion": { "type": "string", "description": "Optional firmware version." } }, "required": [ "label" ], "additionalProperties": true } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal": { "$ref": "#/components/schemas/Terminal" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } }, "/identity/plans": { "post": { "operationId": "post__identity_plans", "tags": [ "sandbox" ], "summary": "Create a sandbox plan", "description": "Sandbox key with members:write. This route prepares a plan; it does not create a paid membership.", "security": [ { "TenantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxPlanInput" } } } }, "responses": { "201": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/Plan" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } }, "/identity/verify": { "post": { "operationId": "post__identity_verify", "tags": [ "sandbox" ], "summary": "Evaluate a sandbox membership", "description": "Sandbox key with verify:read. Supply userId or a supported cardToken and optional tenantPlanId/terminalId. Uses uppercase ACTIVE, EXPIRED, NOT_FOUND or SUSPENDED statuses. This contract is distinct from POS v1.", "security": [ { "TenantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxVerifyInput" } } } }, "responses": { "200": { "description": "Successful operation. Examples are illustrative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Result." }, "status": { "type": "string", "description": "Sandbox status.", "enum": [ "ACTIVE", "EXPIRED", "NOT_FOUND", "SUSPENDED" ] }, "member": { "type": "object", "properties": {}, "additionalProperties": true }, "subscription": { "type": "object", "properties": {}, "additionalProperties": true }, "eventId": { "type": "string", "description": "Audit reference.", "format": "uuid" } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } }, "/identity/memberships": { "post": { "operationId": "post__identity_memberships", "tags": [ "sandbox" ], "summary": "Direct activation is retired", "description": "Sandbox direct activation returns 410. Use the approved checkout flow; never fabricate a payment to create an entitlement.", "security": [ { "TenantKey": [] } ], "responses": { "410": { "description": "Retired endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Retirement message." } }, "additionalProperties": true } } } }, "default": { "description": "Request rejected or service unavailable. Authentication middleware may return a legacy {error} object.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Legacy error message." } }, "additionalProperties": true } } } } }, "deprecated": true, "servers": [ { "url": "http://localhost:5001/api", "description": "Isolated development server; do not test-create tenants on production." } ] } } }, "components": { "securitySchemes": { "MemberSession": { "type": "http", "scheme": "bearer", "bearerFormat": "BEXO member session", "description": "Supported BEXO sign-in session. Owner operations resolve the owner; buyer/member operations resolve the buyer." }, "TenantKey": { "type": "http", "scheme": "bearer", "description": "Scoped BEXO integration key. Server or managed-device use only. Never embed in a browser." } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "Problem type; normally about:blank." }, "title": { "type": "string", "description": "Human-readable summary." }, "detail": { "type": "string", "description": "Client-safe recovery detail." }, "status": { "type": "integer", "description": "HTTP status." }, "code": { "type": "string", "description": "Machine-readable error code." }, "requestId": { "type": "string", "description": "Correlation ID, when available." }, "error": { "type": "string", "description": "Legacy error message." } }, "required": [ "status", "code" ], "additionalProperties": true }, "Vendor": { "type": "object", "properties": { "id": { "type": "string", "description": "Vendor identifier.", "format": "uuid" }, "displayName": { "type": "string", "description": "Customer-facing name." }, "legalName": { "type": "string", "description": "Private registered name." }, "status": { "type": "string", "description": "Review state.", "enum": [ "sandbox_only", "entity_verified", "control_verified", "risk_reviewed", "production_active", "suspended" ] }, "publicUrl": { "type": "string", "description": "Public storefront URL, if configured.", "nullable": true } }, "required": [ "id", "status" ], "additionalProperties": true }, "Application": { "type": "object", "properties": { "legalName": { "type": "string", "description": "Registered legal name.", "maxLength": 200 }, "displayName": { "type": "string", "description": "Customer-facing name.", "maxLength": 200 }, "contactEmail": { "type": "string", "description": "Business email.", "format": "email" }, "supportEmail": { "type": "string", "description": "Customer support email.", "format": "email" }, "contactPhone": { "type": "string", "description": "Business phone; optional." }, "businessCategory": { "type": "string", "description": "Business category.", "enum": [ "fitness", "gym", "coworking", "education", "retail", "entertainment", "healthcare", "laundry", "other" ], "default": "other" }, "registeredAddress": { "type": "string", "description": "Business address.", "maxLength": 500 }, "authorizedRepresentative": { "type": "string", "description": "Authorized representative name." }, "serviceDescription": { "type": "string", "description": "Description of the service.", "maxLength": 1000 }, "pan": { "type": "string", "description": "Valid Indian PAN. Supply actual business details privately." }, "gstExempt": { "type": "boolean", "description": "Whether the business declares a GST exemption." }, "gstin": { "type": "string", "description": "Required when gstExempt is false." }, "pincode": { "type": "string", "description": "Six-digit PIN code, when supplied." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State." }, "websiteUrl": { "type": "string", "description": "Website URL.", "format": "uri" }, "refundPolicyUrl": { "type": "string", "description": "Public refund policy URL.", "format": "uri" }, "termsAccepted": { "type": "boolean", "description": "Acceptance of the application terms." } }, "required": [ "legalName", "displayName", "contactEmail", "supportEmail", "registeredAddress", "authorizedRepresentative", "pan" ], "additionalProperties": true }, "PlanInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Plan name." }, "durationDays": { "type": "integer", "description": "Positive duration. Checkout snapshots support 1–366 days.", "minimum": 1, "maximum": 366 }, "pricePaise": { "type": "integer", "description": "Amount in integer INR paise; 100 paise equals INR 1.", "minimum": 100, "maximum": 2147483647 }, "billingPeriod": { "type": "string", "description": "Plan billing mode. A monthly value does not by itself prove recurring payments are enabled.", "enum": [ "one_time", "monthly" ], "default": "one_time" }, "gstPercent": { "type": "number", "minimum": 0, "maximum": 28, "description": "Tax percentage recorded for the plan; default in this reference is 18." }, "taxInclusive": { "type": "boolean", "description": "Whether the stated amount includes tax; defaults true." }, "externalRef": { "type": "string", "description": "Optional reference in your ERP." } }, "required": [ "name", "pricePaise" ], "additionalProperties": true }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Plan ID.", "format": "uuid" }, "tenantId": { "type": "string", "description": "Owning vendor ID.", "format": "uuid" }, "name": { "type": "string", "description": "Plan name." }, "durationDays": { "type": "integer", "description": "Membership duration." }, "pricePaise": { "type": "integer", "description": "Amount in integer INR paise; 100 paise equals INR 1.", "minimum": 100, "maximum": 2147483647 }, "currency": { "type": "string", "description": "Currency; INR in the documented checkout." }, "billingPeriod": { "type": "string", "description": "one_time or monthly." }, "isActive": { "type": "boolean", "description": "Whether this plan is currently published." }, "checkoutUrl": { "type": "string", "description": "Hosted checkout link, subject to vendor and plan availability.", "format": "uri" } }, "additionalProperties": true }, "PlanUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Replacement name." }, "durationDays": { "type": "integer", "description": "Positive duration.", "minimum": 1 }, "pricePaise": { "type": "integer", "description": "Amount in integer INR paise; 100 paise equals INR 1.", "minimum": 100, "maximum": 2147483647 }, "gstPercent": { "type": "number", "minimum": 0, "maximum": 28 }, "taxInclusive": { "type": "boolean", "description": "Whether tax is included." }, "isActive": { "type": "boolean", "description": "Publishing requires production_active vendor approval." } }, "additionalProperties": true }, "Membership": { "type": "object", "properties": { "id": { "type": "string", "description": "Membership ID.", "format": "uuid" }, "planId": { "type": "string", "description": "Plan ID.", "format": "uuid" }, "planName": { "type": "string", "description": "Plan display name." }, "status": { "type": "string", "description": "Membership state." }, "validFrom": { "type": "string", "description": "Validity start.", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "description": "Validity end.", "format": "date-time", "nullable": true }, "amountPaise": { "type": "integer", "description": "Purchase amount in paise.", "nullable": true }, "createdAt": { "type": "string", "description": "Creation time.", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "TerminalInput": { "type": "object", "properties": { "label": { "type": "string", "description": "Device label, e.g. Reception.", "maxLength": 150 }, "serialNumber": { "type": "string", "description": "Optional custom serial. If omitted, the service generates one." }, "hardwareModel": { "type": "string", "description": "Hardware model." }, "firmwareVersion": { "type": "string", "description": "Firmware version." } }, "additionalProperties": true }, "Terminal": { "type": "object", "properties": { "id": { "type": "string", "description": "Terminal ID.", "format": "uuid" }, "label": { "type": "string", "description": "Device name." }, "serialNumber": { "type": "string", "description": "Registered terminal serial; an identifier, not a secret." }, "status": { "type": "string", "description": "Device state." }, "isRevoked": { "type": "boolean", "description": "Revocation flag." }, "hardwareModel": { "type": "string", "description": "Model." }, "lastSeen": { "type": "string", "description": "Last check-in.", "format": "date-time", "nullable": true }, "totalRequests": { "type": "integer", "description": "Recorded requests." } }, "additionalProperties": true }, "TerminalUpdate": { "type": "object", "properties": { "label": { "type": "string", "description": "Device label.", "maxLength": 150 }, "status": { "type": "string", "description": "Requested state.", "enum": [ "active", "offline", "suspended", "revoked" ] }, "hardwareModel": { "type": "string", "description": "Device model." } }, "additionalProperties": true }, "CheckoutLinkInput": { "type": "object", "properties": { "tenantPlanId": { "type": "string", "description": "An active plan belonging to the vendor.", "format": "uuid" } }, "required": [ "tenantPlanId" ], "additionalProperties": true }, "CheckoutLink": { "type": "object", "properties": { "linkId": { "type": "string", "description": "Link reference. The owner route may return the plan ID in this field; treat it as opaque.", "format": "uuid" }, "token": { "type": "string", "description": "Hosted checkout token. Do not log it." }, "url": { "type": "string", "description": "Hosted checkout URL.", "format": "uri" }, "expiresAt": { "type": "string", "description": "Server-returned availability hint. Plan and vendor checks still apply." } }, "additionalProperties": true }, "CheckoutInput": { "type": "object", "properties": { "checkoutToken": { "type": "string", "description": "Token from a supported hosted checkout link." }, "acceptedTerms": { "type": "boolean", "enum": [ true ], "description": "Must be true for a new purchase." }, "acceptedTermsVersion": { "type": "string", "description": "Use the version returned by checkout-link retrieval." }, "couponCode": { "type": "string", "description": "Optional coupon code." } }, "required": [ "checkoutToken", "acceptedTerms", "acceptedTermsVersion" ], "additionalProperties": true }, "Purchase": { "type": "object", "properties": { "membershipId": { "type": "string", "description": "Original membership/purchase reference.", "format": "uuid" }, "orderId": { "type": "string", "description": "Provider order reference.", "nullable": true }, "subscriptionId": { "type": "string", "description": "Provider subscription reference, where enabled.", "nullable": true }, "keyId": { "type": "string", "description": "Public provider checkout key, not the provider secret." }, "amountPaise": { "type": "integer", "description": "Amount in integer INR paise; 100 paise equals INR 1.", "minimum": 100, "maximum": 2147483647 }, "currency": { "type": "string", "description": "INR." }, "durationDays": { "type": "integer", "description": "Snapshotted duration." }, "planName": { "type": "string", "description": "Snapshotted name." }, "billingPeriod": { "type": "string", "description": "Server-returned billing mode." }, "status": { "type": "string", "description": "Current purchase state." }, "pendingExpiresAt": { "type": "string", "description": "Pending-purchase expiry, returned by resume.", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "PaymentProof": { "type": "object", "properties": { "razorpay_payment_id": { "type": "string", "description": "Provider payment ID." }, "razorpay_order_id": { "type": "string", "description": "Original provider order, for an order payment." }, "razorpay_subscription_id": { "type": "string", "description": "Original subscription, for a subscription payment." }, "razorpay_signature": { "type": "string", "description": "Provider signature from the supported checkout callback." } }, "required": [ "razorpay_payment_id", "razorpay_signature" ], "additionalProperties": true }, "TapInput": { "type": "object", "properties": { "cardUid": { "type": "string", "description": "Raw card read, if using a registered NFC reader. Keep private." }, "qrPayload": { "type": "string", "description": "Alternative QR payload. At least one of cardUid or qrPayload is required." }, "timestamp": { "type": "string", "description": "Optional ISO time reported by the terminal. Server time controls entitlement.", "format": "date-time" } }, "additionalProperties": true }, "Subscriber": { "type": "object", "properties": { "memberId": { "type": "string", "description": "Member reference.", "format": "uuid" }, "name": { "type": "string", "description": "Display name, when supplied.", "nullable": true }, "photoUrl": { "type": "string", "description": "Photo URL, when supplied.", "nullable": true }, "membershipStatus": { "type": "string", "description": "Membership state." }, "planName": { "type": "string", "description": "Plan name." }, "tenantPlanId": { "type": "string", "description": "Plan reference.", "format": "uuid", "nullable": true }, "expiryDate": { "type": "string", "description": "Expiry when supplied.", "format": "date-time", "nullable": true }, "validUntil": { "type": "string", "description": "Validity when supplied.", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "TapResult": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Access outcome; use alongside decision." }, "decision": { "type": "string", "description": "Operational outcome.", "enum": [ "allow", "deny" ] }, "decisionReason": { "type": "string", "description": "Reason such as active, expired, no_membership_for_vendor or member_not_found." }, "status": { "type": "string", "description": "Membership/lookup status." }, "subscriber": { "allOf": [ { "$ref": "#/components/schemas/Subscriber" } ], "nullable": true }, "terminal": { "allOf": [ { "$ref": "#/components/schemas/Terminal" } ], "nullable": true }, "billing": { "type": "object", "properties": { "billedPaise": { "type": "integer", "description": "Recorded usage amount in paise." }, "costRupees": { "type": "number", "description": "Display amount; not a commercial agreement." }, "costDisplay": { "type": "string", "description": "Formatted usage amount." } }, "additionalProperties": true }, "latencyMs": { "type": "integer", "description": "Server evaluation time." }, "timestamp": { "type": "string", "description": "Server evaluation time.", "format": "date-time" }, "logId": { "type": "string", "description": "Log reference.", "format": "uuid", "nullable": true } }, "required": [ "verified", "decision", "decisionReason" ], "additionalProperties": true }, "ConsentInput": { "type": "object", "properties": { "granted": { "type": "boolean", "description": "true grants the listed fields; false revokes access." }, "purpose": { "type": "string", "description": "Supported consent purpose.", "enum": [ "membership_verification" ] }, "fields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "membership_status", "valid_until", "display_name", "photo" ] }, "description": "Request only the fields needed for the stated purpose." } }, "required": [ "granted", "purpose", "fields" ], "additionalProperties": true }, "KeyMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Credential metadata ID.", "format": "uuid" }, "keyPrefix": { "type": "string", "description": "Display-safe prefix; never the full credential." }, "label": { "type": "string", "description": "Credential label." }, "scopes": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string", "description": "live or sandbox." }, "revokedAt": { "type": "string", "description": "Revocation timestamp.", "format": "date-time", "nullable": true }, "lastUsedAt": { "type": "string", "description": "Last recorded use.", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "SandboxTenantInput": { "type": "object", "properties": { "legalName": { "type": "string", "description": "Synthetic organization name for an isolated sandbox." }, "displayName": { "type": "string", "description": "Sandbox display name." }, "contactEmail": { "type": "string", "description": "Controlled test email.", "format": "email" } }, "required": [ "legalName", "displayName", "contactEmail" ], "additionalProperties": true }, "SandboxPlanInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Plan name." }, "durationDays": { "type": "integer", "description": "Duration, 1–366 days.", "minimum": 1, "maximum": 366 }, "pricePaise": { "type": "integer", "description": "Amount in integer INR paise; 100 paise equals INR 1.", "minimum": 100, "maximum": 2147483647 }, "gracePeriodDays": { "type": "integer", "description": "Nonnegative grace period.", "minimum": 0, "default": 0 }, "externalRef": { "type": "string", "description": "Optional external reference." } }, "required": [ "name", "durationDays", "pricePaise" ], "additionalProperties": true }, "SandboxVerifyInput": { "type": "object", "properties": { "userId": { "type": "string", "description": "Test member ID; or supply a valid cardToken.", "format": "uuid" }, "cardToken": { "type": "string", "description": "Alternative supported test card token." }, "terminalId": { "type": "string", "description": "Optional nonrevoked terminal belonging to this tenant.", "format": "uuid" }, "tenantPlanId": { "type": "string", "description": "Optional plan filter.", "format": "uuid" } }, "additionalProperties": true } } } }