{ "openapi": "3.0.1", "info": { "title": "LCStripeApi", "description": "Leffel Consulting payments platform (Finix; tenants are Finix sub-merchants / merchants of record). Errors are returned as RFC 7807 problem+json.", "contact": { "name": "Leffel Consulting" }, "version": "v1" }, "paths": { "/admin/tenants": { "post": { "tags": [ "Admin" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/keys": { "post": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueKeyRequest" } } } }, "responses": { "200": { "description": "Success" } } }, "get": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/account-links": { "post": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/account-links/{portalUserId}": { "delete": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "portalUserId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/account-links": { "get": { "tags": [ "Admin" ], "parameters": [ { "name": "portalUserId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/keys/{keyId}/revoke": { "post": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/reconciliation": { "get": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/revenue": { "get": { "tags": [ "Admin" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "tenantId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/readiness": { "get": { "tags": [ "Admin" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success" } } } }, "/contact": { "post": { "tags": [ "Contact" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/v1/disputes": { "get": { "tags": [ "Disputes" ], "summary": "List disputes", "description": "Chargebacks with state and any respond-by deadline. Newest first.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/disputes/{id}/evidence": { "post": { "tags": [ "Disputes" ], "summary": "Upload dispute evidence", "description": "Attach one evidence file (multipart 'file'; JPEG/PNG/PDF ≤1MB) to contest a dispute.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/disputes/{id}/submit": { "post": { "tags": [ "Disputes" ], "summary": "Submit dispute response", "description": "Submit the uploaded evidence for review; the dispute moves to responded.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/onboarding/status": { "get": { "tags": [ "Onboarding" ], "summary": "Get account readiness", "description": "Charges-enabled, payouts-enabled, reasons/requirements, and PCI status. Add ?refresh=true to re-pull from Finix.", "parameters": [ { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/onboarding": { "post": { "tags": [ "Onboarding" ], "summary": "Create an onboarding form", "description": "Start a Finix hosted onboarding form; returns the onboardingUrl to send the merchant to.", "responses": { "200": { "description": "Success" } } } }, "/v1/onboarding/form/{formId}": { "get": { "tags": [ "Onboarding" ], "summary": "Read + finalize an onboarding form", "description": "Reads the form's status and attaches the provisioned merchant once complete (idempotent).", "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a payment", "description": "Charge a Finix.js token (or a stored instrument) to the tenant's merchant. Requires an Idempotency-Key header; when using finixToken, buyer is required. Card settles synchronously, ACH returns processing.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } }, "get": { "tags": [ "Payments" ], "summary": "List payments", "description": "List/search this tenant's payments, newest first. Filter with from, to (UTC ISO) and status; limit caps the page (≤200) and hasMore signals the window held more.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/payments/{id}/refund": { "post": { "tags": [ "Payments" ], "summary": "Refund a payment", "description": "Full or partial reversal. Guarded to a refundable state and the remaining refundable balance; Idempotency-Key optional.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/v1/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get a payment", "description": "Fetch the current ledger record for an lcPaymentId.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List payouts", "description": "Settlements to the merchant's bank — net, fees, and date. Newest first.", "responses": { "200": { "description": "Success" } } } }, "/portal/provision": { "post": { "tags": [ "Portal" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalProvisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/portal/accounts": { "get": { "tags": [ "Portal" ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/readiness": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/keys": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } }, "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueKeyRequest" } } } }, "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/keys/{keyId}/revoke": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/metrics": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/export": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "format", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/events": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/payouts": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/disputes": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/disputes/{disputeId}/evidence": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/disputes/{disputeId}/submit": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/compliance": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } }, "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignComplianceRequest" } } } }, "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/onboarding": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/onboarding/finalize": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeOnboardingRequest" } } } }, "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/test-payment": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalTestPaymentRequest" } } } }, "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/test-payment/{lcPaymentId}/refund": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lcPaymentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/webhook": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } }, "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWebhookRequest" } } } }, "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/webhook/rotate-secret": { "post": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/tenants/{id}/webhook/deliveries": { "get": { "tags": [ "Portal" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Success" } } } }, "/pricing/quote": { "post": { "tags": [ "Pricing" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/pricing/assign": { "post": { "tags": [ "Pricing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/admin/tenants/{id}/pricing": { "get": { "tags": [ "Pricing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/portal/support/ai/status": { "get": { "tags": [ "Support" ], "responses": { "200": { "description": "Success" } } } }, "/portal/support/ai": { "post": { "tags": [ "Support" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportAskBody" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/health": { "get": { "tags": [ "System" ], "responses": { "200": { "description": "Success" } } } }, "/v1/meta": { "get": { "tags": [ "System" ], "summary": "Service + Finix.js config", "description": "Public (no auth): the Finix.js application id, environment, and API version your frontend needs. No secrets.", "responses": { "200": { "description": "Success" } } } }, "/v1/terminal/readers": { "post": { "tags": [ "Terminal" ], "summary": "Register a reader", "description": "Register a PAX reader to the tenant's merchant.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterReaderRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } }, "get": { "tags": [ "Terminal" ], "summary": "List readers", "responses": { "200": { "description": "Success" } } } }, "/v1/terminal/readers/{id}": { "get": { "tags": [ "Terminal" ], "summary": "Get a reader", "description": "Add ?connection=true to include the live Open/Closed connection state.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connection", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/terminal/readers/{id}/activate": { "post": { "tags": [ "Terminal" ], "summary": "Activate a reader", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/terminal/readers/{id}/deactivate": { "post": { "tags": [ "Terminal" ], "summary": "Deactivate a reader", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" } } } }, "/v1/payments/terminal": { "post": { "tags": [ "Terminal" ], "summary": "Start an in-person sale", "description": "Card-present charge on a reader. Requires an Idempotency-Key; settles asynchronously (processing).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalPaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Success" } } } }, "/webhooks/finix": { "post": { "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success" } } } } }, "components": { "schemas": { "AssignRequest": { "type": "object", "properties": { "avgTicketCents": { "type": "integer", "format": "int64" }, "monthlyVolumeCents": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "BuyerInfo": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ContactRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "subject": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreatePaymentRequest": { "type": "object", "properties": { "amountCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "nullable": true }, "finixToken": { "type": "string", "nullable": true }, "finixInstrumentId": { "type": "string", "nullable": true }, "buyer": { "$ref": "#/components/schemas/BuyerInfo" }, "orderRef": { "type": "string", "nullable": true }, "customerRef": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "branch": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CreateTenantRequest": { "type": "object", "properties": { "tenantId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "processorMerchantId": { "type": "string", "nullable": true }, "fee": { "$ref": "#/components/schemas/FeeConfig" }, "callbackUrl": { "type": "string", "nullable": true }, "callbackSigningSecret": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FeeConfig": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/FeeMode" }, "percentBps": { "type": "integer", "format": "int32" }, "flatCents": { "type": "integer", "format": "int64" }, "minCents": { "type": "integer", "format": "int64" }, "maxCents": { "type": "integer", "format": "int64" }, "achFlatCents": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "FeeMode": { "enum": [ 0, 1, 2 ], "type": "integer", "format": "int32" }, "FinalizeOnboardingRequest": { "type": "object", "properties": { "formId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "IssueKeyRequest": { "type": "object", "properties": { "label": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LinkAccountRequest": { "type": "object", "properties": { "portalUserId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PortalProvisionRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PortalTestPaymentRequest": { "type": "object", "properties": { "finixToken": { "type": "string", "nullable": true }, "amountCents": { "type": "integer", "format": "int64", "nullable": true }, "currency": { "type": "string", "nullable": true }, "buyer": { "$ref": "#/components/schemas/BuyerInfo" } }, "additionalProperties": false }, "QuoteRequest": { "type": "object", "properties": { "avgTicketCents": { "type": "integer", "format": "int64" }, "monthlyVolumeCents": { "type": "integer", "format": "int64" }, "retailPercentBps": { "type": "integer", "format": "int32", "nullable": true }, "retailPerTxnCents": { "type": "integer", "format": "int64", "nullable": true } }, "additionalProperties": false }, "RefundRequest": { "type": "object", "properties": { "amountCents": { "type": "integer", "format": "int64", "nullable": true }, "reason": { "type": "string", "nullable": true }, "refundApplicationFee": { "type": "boolean" } }, "additionalProperties": false }, "RegisterReaderRequest": { "type": "object", "properties": { "model": { "type": "string", "nullable": true }, "serialNumber": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SetWebhookRequest": { "type": "object", "properties": { "callbackUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SignComplianceRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SupportAskBody": { "type": "object", "properties": { "message": { "type": "string", "nullable": true } }, "additionalProperties": false }, "TerminalPaymentRequest": { "type": "object", "properties": { "readerId": { "type": "string", "nullable": true }, "amountCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "nullable": true }, "orderRef": { "type": "string", "nullable": true }, "customerRef": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Per-tenant API key issued by LC.", "name": "X-Api-Key", "in": "header" }, "AdminKey": { "type": "apiKey", "description": "Admin key for /admin/* (key issuance/rotation). Separate from the tenant key.", "name": "X-Admin-Key", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ] }