{ "openapi": "3.1.0", "info": { "title": "newTicketing Developer API", "version": "1.0.0", "description": "OpenAPI contract for the authenticated developer platform endpoints under /api/v1. This initial spec covers onboarding, API key lifecycle, linked-profile commerce, and the Phase 5 payment/refund/modification flows.", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://api.newticketing.test", "description": "Example developer API host" } ], "tags": [ { "name": "Developer Onboarding", "description": "Developer registration and email verification endpoints." }, { "name": "Developer Account", "description": "Authenticated developer account profile management endpoints." }, { "name": "Developer API Keys", "description": "Sandbox and live key lifecycle endpoints, including rotation and status management." }, { "name": "Developer Commerce", "description": "Linked-profile cart and order operations for developer integrations." }, { "name": "Developer Payments", "description": "Phase 5 payment settlement, refund, and order modification billing endpoints." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/developer/register": { "post": { "security": [], "tags": [ "Developer Onboarding" ], "summary": "Register a developer account", "operationId": "registerDeveloper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperRegistrationRequest" } } } }, "responses": { "201": { "description": "Developer account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperRegistrationResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/developer/verify-email": { "get": { "security": [], "tags": [ "Developer Onboarding" ], "summary": "Verify a developer email token", "operationId": "verifyDeveloperEmail", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification succeeded or was accepted with a sandbox key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperVerificationResponse" } } } }, "403": { "description": "Verification completed but live access was rejected by risk checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperVerificationResponse" } } } }, "422": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DeveloperVerificationResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } } } }, "/api/v1/developer/me": { "get": { "tags": [ "Developer Account" ], "summary": "Get the authenticated developer profile", "description": "Required scope: account.read", "operationId": "getDeveloperProfile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Developer profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperProfileResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Developer Account" ], "summary": "Update the authenticated developer profile", "description": "Required scope: account.write", "operationId": "updateDeveloperProfile", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/keys": { "get": { "tags": [ "Developer API Keys" ], "summary": "List developer API keys", "description": "Required scope: keys.read", "operationId": "listDeveloperApiKeys", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Developer API Keys" ], "summary": "Create a developer API key", "description": "Required scope: keys.write", "operationId": "createDeveloperApiKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/keys/{apiKey}/activate": { "patch": { "tags": [ "Developer API Keys" ], "summary": "Activate a developer API key", "description": "Required scope: keys.write", "operationId": "activateDeveloperApiKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "API key activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/keys/{apiKey}/deactivate": { "patch": { "tags": [ "Developer API Keys" ], "summary": "Deactivate a developer API key", "description": "Required scope: keys.write", "operationId": "deactivateDeveloperApiKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "API key deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/keys/{apiKey}/rotate": { "post": { "tags": [ "Developer API Keys" ], "summary": "Rotate a developer API key", "description": "Required scope: keys.write", "operationId": "rotateDeveloperApiKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "API key rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/keys/{apiKey}": { "delete": { "tags": [ "Developer API Keys" ], "summary": "Delete a developer API key", "description": "Required scope: keys.write", "operationId": "deleteDeveloperApiKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "API key deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/carts": { "post": { "tags": [ "Developer Commerce" ], "summary": "Create or fetch a cart by token", "description": "Required scope: cart.write", "operationId": "createDeveloperCart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCartRequest" } } } }, "responses": { "201": { "description": "Cart ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/carts/{cartToken}": { "get": { "tags": [ "Developer Commerce" ], "summary": "Get cart details", "description": "Required scope: cart.read", "operationId": "getDeveloperCart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CartToken" } ], "responses": { "200": { "description": "Cart details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" } } } }, "/api/v1/carts/{cartToken}/items": { "post": { "tags": [ "Developer Commerce" ], "summary": "Add items to a cart", "description": "Required scope: cart.write", "operationId": "addItemsToDeveloperCart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CartToken" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCartItemsRequest" } } } }, "responses": { "200": { "description": "Cart updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/carts/{cartToken}/items/{cartItem}": { "delete": { "tags": [ "Developer Commerce" ], "summary": "Remove an item from a cart", "description": "Required scope: cart.write", "operationId": "removeItemFromDeveloperCart", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CartToken" }, { "$ref": "#/components/parameters/CartItemId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart item removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" } } } }, "/api/v1/orders": { "post": { "tags": [ "Developer Commerce" ], "summary": "Create an order from a cart", "description": "Required scope: orders.write. Supports legacy stripe_payment_method_id and the Phase 5 structured payment payload for Stripe, Square, or externally reported settlements.", "operationId": "createDeveloperOrder", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "examples": { "externalSettlement": { "summary": "External payment reporting during order creation", "value": { "cart_token": "13d8c225-c7fe-4cc4-a14b-719b7ebd127d", "first_name": "Chris", "last_name": "Dev", "email": "api-order@example.com", "delivery_method": "email", "payment": { "mode": "external", "provider": "external", "external_transaction_id": "ext_txn_001", "payment_method_type": "card", "payment_method_brand": "visa", "payment_method_last4": "4242" } } }, "directSquareCardOnFile": { "summary": "Direct Square card-on-file charge", "value": { "cart_token": "13d8c225-c7fe-4cc4-a14b-719b7ebd127d", "first_name": "Taylor", "last_name": "Partner", "email": "billing@example.com", "delivery_method": "email", "payment": { "mode": "direct", "provider": "square", "customer_id": "sq_customer_123", "card_id": "ccof:card_123", "credentials": { "access_token": "square-live-access-token", "location_id": "L8890HQ" } } } } } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/orders/{orderNumber}": { "get": { "tags": [ "Developer Commerce" ], "summary": "Get an order by order number", "description": "Required scope: orders.read", "operationId": "getDeveloperOrder", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OrderNumber" } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" } } } }, "/api/v1/payments/external-report": { "post": { "tags": [ "Developer Payments" ], "summary": "Record an externally processed settlement", "description": "Required scope: payments.write. Use this when the charge happened outside the API but you still need order-linked settlement artifacts and metering-visible payment records.", "operationId": "recordExternalSettlement", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalSettlementRequest" }, "examples": { "squareExternalSettlement": { "value": { "order_number": "ORD-20260422-1001", "amount": 3.5, "provider": "square", "external_transaction_id": "sq_report_001", "payment_method_type": "card", "payment_method_brand": "mastercard", "payment_method_last4": "5454" } } } } } }, "responses": { "201": { "description": "External settlement recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/orders/{orderNumber}/refunds": { "post": { "tags": [ "Developer Payments" ], "summary": "Refund a developer order", "description": "Required scope: refunds.write. Supports direct provider refunds or external refund evidence.", "operationId": "refundDeveloperOrder", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OrderNumber" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" }, "examples": { "externalRefund": { "value": { "amount": 10, "payment_id": 44, "provider": "external", "mode": "external", "external_refund_id": "ext_refund_001" } } } } } }, "responses": { "201": { "description": "Refund recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMutationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/orders/{orderNumber}/modifications/settle": { "post": { "tags": [ "Developer Payments" ], "summary": "Settle an order modification delta", "description": "Required scope: orders.modify. Positive deltas create additional charges; negative deltas create refunds.", "operationId": "settleOrderModification", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/OrderNumber" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderModificationSettlementRequest" }, "examples": { "positiveDeltaWithExternalEvidence": { "value": { "delta_amount": 5, "reason": "Seat reassignment surcharge", "payment": { "mode": "external", "provider": "external", "external_transaction_id": "mod_txn_001" } } } } } } }, "responses": { "201": { "description": "Modification settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderModificationSettlementResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/ProfileNotLinked" }, "422": { "$ref": "#/components/responses/ValidationError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "parameters": { "ApiKeyId": { "name": "apiKey", "in": "path", "required": true, "schema": { "type": "integer" } }, "CartToken": { "name": "cartToken", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 120 } }, "CartItemId": { "name": "cartItem", "in": "path", "required": true, "schema": { "type": "integer" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional key used for safe retries on mutating requests. Replays the original JSON response when the same operation key is reused.", "schema": { "type": "string", "maxLength": 255 } }, "OrderNumber": { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "Forbidden": { "description": "Authenticated but missing scope or blocked by business rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ProfileNotLinked": { "description": "Developer account is not linked to a profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "This developer account is not linked to a profile yet. Ask an admin to assign a profile before using commerce endpoints." } } } }, "Unauthorized": { "description": "Missing or invalid bearer key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "schemas": { "AddCartItemsRequest": { "type": "object", "required": [ "event_id", "items" ], "properties": { "event_id": { "type": "integer" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CartItemInput" } } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "type", "status", "prefix", "scopes", "created_at", "rotated_from_id" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "revoked" ] }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "rotated_from_id": { "type": [ "integer", "null" ] } } }, "ApiKeyListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "ApiKeyMutationResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ApiKey" } } }, "Cart": { "type": "object", "required": [ "token", "profile_id", "promo_code_id", "item_count", "subtotal", "items", "updated_at" ], "properties": { "token": { "type": "string" }, "profile_id": { "type": "integer" }, "promo_code_id": { "type": [ "integer", "null" ] }, "item_count": { "type": "integer" }, "subtotal": { "type": "number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CartItem": { "type": "object", "required": [ "id", "event_id", "ticket_type_id", "event_date_id", "quantity", "unit_price", "gratuity", "line_total", "event_name", "ticket_type_name" ], "properties": { "id": { "type": "integer" }, "event_id": { "type": "integer" }, "ticket_type_id": { "type": "integer" }, "event_date_id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" }, "gratuity": { "type": "number" }, "line_total": { "type": "number" }, "event_name": { "type": [ "string", "null" ] }, "ticket_type_name": { "type": [ "string", "null" ] } } }, "CartItemInput": { "type": "object", "required": [ "ticket_type_id", "quantity" ], "properties": { "ticket_type_id": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "event_date_id": { "type": [ "integer", "null" ] } } }, "CartMutationResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Cart" } } }, "CartResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Cart" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [ "*" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CreateApiKeyResponse": { "type": "object", "required": [ "message", "data", "plain_key" ], "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ApiKey" }, "plain_key": { "type": "string" } } }, "CreateCartRequest": { "type": "object", "properties": { "cart_token": { "type": "string", "maxLength": 120 } } }, "CreateOrderRequest": { "type": "object", "required": [ "cart_token", "first_name", "last_name", "email", "delivery_method" ], "properties": { "cart_token": { "type": "string", "maxLength": 120 }, "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 20 }, "delivery_method": { "type": "string", "enum": [ "email", "sms" ] }, "gratuity": { "type": "number", "minimum": 0, "maximum": 999.99 }, "subscribe": { "type": "boolean" }, "stripe_payment_method_id": { "type": [ "string", "null" ], "description": "Legacy platform Stripe payment method input for existing storefront-style integrations." }, "payment": { "$ref": "#/components/schemas/PaymentPayload" } } }, "DeveloperAccount": { "type": "object", "required": [ "id", "company_name", "website_url", "contact_email", "contact_phone", "verification_status", "sandbox_access", "live_access", "risk_level", "email_verified_at", "profile_id", "linked_profile" ], "properties": { "id": { "type": "integer" }, "company_name": { "type": "string" }, "website_url": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "contact_phone": { "type": [ "string", "null" ] }, "verification_status": { "type": "string" }, "sandbox_access": { "type": "boolean" }, "live_access": { "type": "boolean" }, "risk_level": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "profile_id": { "type": [ "integer", "null" ] }, "linked_profile": { "oneOf": [ { "$ref": "#/components/schemas/LinkedProfile" }, { "type": "null" } ] } } }, "DeveloperProfileResponse": { "type": "object", "required": [ "developer", "api_mode", "api_keys" ], "properties": { "developer": { "$ref": "#/components/schemas/DeveloperAccount" }, "api_mode": { "type": [ "string", "null" ], "enum": [ "sandbox", "live", null ] }, "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "DeveloperProfileUpdateRequest": { "type": "object", "properties": { "company_name": { "type": "string", "maxLength": 255 }, "website_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 30 } } }, "DeveloperRegistrationRequest": { "type": "object", "required": [ "first_name", "last_name", "email", "password", "password_confirmation", "company_name" ], "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "format": "password", "description": "At least 8 characters, mixed case, and numeric." }, "password_confirmation": { "type": "string", "format": "password" }, "company_name": { "type": "string", "maxLength": 255 }, "website_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 255 } } }, "DeveloperRegistrationResponse": { "type": "object", "required": [ "message", "developer_id", "email" ], "properties": { "message": { "type": "string" }, "developer_id": { "type": "integer" }, "email": { "type": "string", "format": "email" } } }, "DeveloperVerificationResponse": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "sandbox_key": { "type": [ "string", "null" ] } } }, "ErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ExternalSettlementRequest": { "type": "object", "required": [ "order_number", "amount", "provider", "external_transaction_id" ], "properties": { "order_number": { "type": "string" }, "amount": { "type": "number", "minimum": 0.01 }, "provider": { "type": "string", "enum": [ "stripe", "square", "external" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "usd" }, "external_transaction_id": { "type": "string", "maxLength": 255 }, "customer_id": { "type": [ "string", "null" ], "maxLength": 255 }, "payment_method_type": { "type": [ "string", "null" ], "maxLength": 50 }, "payment_method_brand": { "type": [ "string", "null" ], "maxLength": 50 }, "payment_method_last4": { "type": [ "string", "null" ], "maxLength": 4 }, "cardholder_name": { "type": [ "string", "null" ], "maxLength": 120 }, "note": { "type": [ "string", "null" ], "maxLength": 255 }, "reference": { "type": [ "string", "null" ], "maxLength": 255 } } }, "LinkedProfile": { "type": "object", "required": [ "id", "name", "subdomain" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "subdomain": { "type": "string" } } }, "MessageResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "Order": { "type": "object", "required": [ "id", "order_number", "status", "delivery_method", "customer", "totals", "refund_status", "tickets", "payments", "created_at" ], "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "delivery_method": { "type": "string", "enum": [ "email", "sms" ] }, "customer": { "$ref": "#/components/schemas/OrderCustomer" }, "totals": { "$ref": "#/components/schemas/OrderTotals" }, "refund_status": { "type": [ "string", "null" ] }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTicket" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRecord" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrderCustomer": { "type": "object", "required": [ "first_name", "last_name", "email", "phone" ], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] } } }, "OrderModificationSettlementRequest": { "type": "object", "required": [ "delta_amount", "reason", "payment" ], "properties": { "delta_amount": { "type": "number", "not": { "const": 0 } }, "reason": { "type": "string", "maxLength": 255 }, "payment": { "$ref": "#/components/schemas/PaymentPayloadForModification" } } }, "OrderModificationSettlementResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "type": "object", "required": [ "order_number", "grand_total", "payment" ], "properties": { "order_number": { "type": "string" }, "grand_total": { "type": "number" }, "payment": { "$ref": "#/components/schemas/PaymentRecord" } } } } }, "OrderMutationResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Order" } } }, "OrderResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } }, "OrderTicket": { "type": "object", "required": [ "id", "booking_code", "event_id", "event_name", "ticket_type_id", "ticket_type_name", "price", "status", "refund_status" ], "properties": { "id": { "type": "integer" }, "booking_code": { "type": "string" }, "event_id": { "type": "integer" }, "event_name": { "type": [ "string", "null" ] }, "ticket_type_id": { "type": "integer" }, "ticket_type_name": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "status": { "type": "string" }, "refund_status": { "type": [ "string", "null" ] } } }, "OrderTotals": { "type": "object", "required": [ "subtotal", "tax_total", "fee_total", "gratuity_total", "discount_total", "grand_total" ], "properties": { "subtotal": { "type": "number" }, "tax_total": { "type": "number" }, "fee_total": { "type": "number" }, "gratuity_total": { "type": "number" }, "discount_total": { "type": "number" }, "grand_total": { "type": "number" } } }, "PaymentCredentials": { "type": "object", "properties": { "secret_key": { "type": "string", "description": "Developer-provided Stripe secret key for direct charges and refunds." }, "access_token": { "type": "string", "description": "Developer-provided Square access token for direct charges and refunds." }, "location_id": { "type": "string", "description": "Square location identifier used with direct Square calls." } } }, "PaymentMutationResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/PaymentRecord" } } }, "PaymentPayload": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "platform", "direct", "external" ] }, "provider": { "type": "string", "enum": [ "stripe", "square", "external" ] }, "credentials": { "$ref": "#/components/schemas/PaymentCredentials" }, "payment_method_id": { "type": "string" }, "customer_id": { "type": "string" }, "source_id": { "type": "string" }, "card_id": { "type": "string" }, "external_transaction_id": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "payment_method_type": { "type": "string", "maxLength": 50 }, "payment_method_brand": { "type": "string", "maxLength": 50 }, "payment_method_last4": { "type": "string", "maxLength": 4 }, "cardholder_name": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 255 } } }, "PaymentPayloadForModification": { "allOf": [ { "$ref": "#/components/schemas/PaymentPayload" }, { "type": "object", "required": [ "provider" ] } ] }, "PaymentRecord": { "type": "object", "required": [ "id", "amount", "currency", "status", "type", "provider", "external_transaction_id", "processed_externally" ], "properties": { "id": { "type": "integer" }, "amount": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "type": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "external_transaction_id": { "type": [ "string", "null" ] }, "processed_externally": { "type": "boolean" } } }, "RefundRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "minimum": 0.01 }, "payment_id": { "type": "integer" }, "provider": { "type": "string", "enum": [ "stripe", "square", "external" ] }, "mode": { "type": "string", "enum": [ "direct", "external" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "credentials": { "$ref": "#/components/schemas/PaymentCredentials" }, "external_transaction_id": { "type": "string", "maxLength": 255 }, "external_refund_id": { "type": "string", "maxLength": 255 }, "note": { "type": "string", "maxLength": 255 } } }, "ValidationErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }