{ "openapi": "3.1.0", "info": { "title": "SMeta Gateway API", "version": "0.2.0", "description": "Noncustodial USDT TRC20 invoicing and reconciliation. Buyers pay the merchant wallet directly; the gateway never holds funds or private keys, never broadcasts transactions and charges no commission (network fees still apply). Invoices are confirmed from verified TRON mainnet transfers. Use decimal strings and server-only API credentials. The identification adjustment is paid to the merchant, not the platform." }, "servers": [ { "url": "/api/v1", "description": "Next.js origin reverse-proxied to NestJS" }, { "url": "http://localhost:4000/api/v1", "description": "Local NestJS development API" } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "tags": [ { "name": "System", "description": "Service health and public configuration" }, { "name": "Authentication", "description": "Merchant owner sessions" }, { "name": "Account", "description": "Merchant profile and dashboard snapshot" }, { "name": "Wallets", "description": "Public TRON receiving addresses" }, { "name": "Invoices", "description": "Exact-amount invoices" }, { "name": "Checkout", "description": "Payer-safe checkout" }, { "name": "API keys", "description": "Server credentials" }, { "name": "Ledger", "description": "Operational ledger export" }, { "name": "Webhooks", "description": "Signed event endpoints and deliveries" }, { "name": "Support", "description": "Support tickets, public contact form and support inbox" } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "Service health and gateway mode", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "live_payments_enabled": { "const": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "tags": [ "System" ] } }, "/config": { "get": { "operationId": "getPublicConfig", "summary": "Public client configuration such as the captcha site key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "captcha": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "provider": { "const": "turnstile" }, "site_key": { "type": "string" } }, "required": [ "provider", "site_key" ] } ] } }, "required": [ "captcha" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "description": "captcha is null when Cloudflare Turnstile is not configured; otherwise send captcha_token with sign-in, registration and contact requests.", "tags": [ "System" ] } }, "/support/contact": { "post": { "operationId": "contactSupport", "summary": "Send a message to support without an account", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "reference": { "type": "string" }, "status": { "const": "open" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Captcha verification is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "description": "Creates a ticket that the support team answers by email. Only the reference is returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "category": { "enum": [ "general", "payments", "technical", "account", "other" ], "default": "general" }, "message": { "type": "string", "minLength": 1, "maxLength": 5000 }, "captcha_token": { "type": "string", "description": "Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use.", "maxLength": 2048 } }, "required": [ "name", "email", "subject", "message" ] } } } }, "tags": [ "Support" ] } }, "/support/tickets": { "get": { "operationId": "listSupportTickets", "summary": "List your support tickets", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicket" }, "maxItems": 200 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "tags": [ "Support" ] }, "post": { "operationId": "createSupportTicket", "summary": "Open a support ticket", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 150 }, "category": { "enum": [ "general", "payments", "technical", "account", "other" ], "default": "general" }, "message": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "subject", "message" ] } } } }, "tags": [ "Support" ] } }, "/support/tickets/{id}": { "get": { "operationId": "getSupportTicket", "summary": "Read one of your tickets with its messages", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "tags": [ "Support" ] } }, "/support/tickets/{id}/messages": { "post": { "operationId": "replySupportTicket", "summary": "Reply to your ticket; a closed ticket reopens", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "message" ] } } } }, "tags": [ "Support" ] } }, "/support/tickets/{id}/close": { "post": { "operationId": "closeSupportTicket", "summary": "Close your ticket", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "tags": [ "Support" ] } }, "/support/inbox": { "get": { "operationId": "listSupportInbox", "summary": "Support team: list every ticket, open first", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicket" }, "maxItems": 300 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "description": "Requires a session for an account listed in SUPPORT_STAFF_EMAILS.", "tags": [ "Support" ] } }, "/support/inbox/{id}": { "get": { "operationId": "getSupportInboxTicket", "summary": "Support team: read a ticket with contact details", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "tags": [ "Support" ] } }, "/support/inbox/{id}/messages": { "post": { "operationId": "answerSupportTicket", "summary": "Support team: reply to a merchant ticket", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "message" ] } } } }, "description": "Contact-form tickets return 409 email_reply_required because the visitor has no account.", "tags": [ "Support" ] } }, "/support/inbox/{id}/status": { "post": { "operationId": "setSupportTicketStatus", "summary": "Support team: set ticket status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportThread" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Ticket ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "open", "answered", "closed" ] } }, "required": [ "status" ] } } } }, "tags": [ "Support" ] } }, "/auth/register": { "post": { "operationId": "register", "summary": "Register a merchant and set an HttpOnly session cookie", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Captcha verification is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12, "maxLength": 128, "format": "password" }, "captcha_token": { "type": "string", "description": "Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use.", "maxLength": 2048 }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "email", "password" ] } } } }, "tags": [ "Authentication" ] } }, "/auth/login": { "post": { "operationId": "login", "summary": "Sign in and set an HttpOnly session cookie", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Captcha verification is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "format": "password" }, "captcha_token": { "type": "string", "description": "Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use.", "maxLength": 2048 } }, "required": [ "email", "password" ] } } } }, "tags": [ "Authentication" ] } }, "/auth/logout": { "post": { "operationId": "logout", "summary": "Clear the merchant session cookie", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "tags": [ "Authentication" ] } }, "/me": { "get": { "operationId": "getDashboard", "summary": "Merchant account, ledger and operational dashboard", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "tags": [ "Account" ] }, "patch": { "operationId": "updateMerchant", "summary": "Update merchant display name", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } }, "tags": [ "Account" ] } }, "/wallets": { "get": { "operationId": "listWallets", "summary": "List merchant receiving addresses", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Wallets" ] }, "post": { "operationId": "createWallet", "summary": "Register a checksummed TRON address; ownership remains unverified", "responses": { "200": { "description": "Existing address", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } } } } } }, "201": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$" } }, "required": [ "label", "address" ] } } } }, "tags": [ "Wallets" ] } }, "/invoices": { "get": { "operationId": "listInvoices", "summary": "List the latest 500 invoices for this merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "maxItems": 500 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Invoices" ] }, "post": { "operationId": "createInvoice", "summary": "Allocate a unique exact payable amount for 90 days", "responses": { "200": { "description": "Identical idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelope" } } } }, "201": { "description": "Invoice allocated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelope" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Amount allocation is global for (network, token contract, receiving address, final payable micro-units), including merchants sharing an address. Reservations outlive invoice expiry. Historical amount reuse is assigned review status. The invoice is confirmed only when a verified TRON transfer of exactly payable_amount reaches wallet_address between creation and expiry.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Persist with the order. Identical retries return the same invoice; changed details return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoice" } } } }, "tags": [ "Invoices" ] } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Retrieve an invoice belonging to this merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Invoice ID" } ], "tags": [ "Invoices" ] } }, "/checkout/{token}": { "get": { "operationId": "getCheckout", "summary": "Read payer-safe checkout details using its capability token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/CheckoutInvoice" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" }, "description": "Checkout capability token from checkout_url" } ], "tags": [ "Checkout" ] } }, "/api-keys": { "post": { "operationId": "createApiKey", "summary": "Create an API key; secret is shown once", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "secret": { "type": "string" }, "warning": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "expires_in_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650, "examples": [ 90 ], "description": "Days until the key expires. Omit or send null for a key that never expires." } }, "required": [ "name" ] } } } }, "tags": [ "API keys" ] } }, "/api-keys/{id}/roll": { "post": { "operationId": "rollApiKey", "summary": "Replace a key with a new secret of the same name, scopes and lifetime", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "secret": { "type": "string" }, "warning": { "type": "string" }, "replaced_key_id": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "API key ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "description": "The old key is revoked in the same transaction. The new secret is shown once.", "tags": [ "API keys" ] } }, "/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke a merchant API key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "API key ID" } ], "tags": [ "API keys" ] } }, "/ledger.csv": { "get": { "operationId": "exportLedger", "summary": "Export the operational ledger", "responses": { "200": { "description": "CSV includes separate base, adjustment and payable columns; not a statutory accounting report.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Ledger" ] } }, "/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a public HTTPS callback; signing secret is shown once", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "secret": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "description": "Port 443 only. Local/private targets, IP literals, credentials, URL fragments and redirects are rejected. DNS is resolved and checked again at delivery time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url" ] } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/{id}": { "delete": { "operationId": "disableWebhook", "summary": "Disable an endpoint and cancel outstanding deliveries", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Webhook ID" } ], "tags": [ "Webhooks" ] } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a signed webhook.test event", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Webhook ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/deliveries/{id}/retry": { "post": { "operationId": "retryWebhook", "summary": "Retry a failed or pending delivery", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or invalid origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, exhausted amount pool or manual review required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "sessionCookie": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Delivery ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "tags": [ "Webhooks" ] } } }, "webhooks": { "invoiceEvent": { "post": { "operationId": "receiveInvoiceEvent", "summary": "Receive a signed gateway event at your configured URL", "security": [], "description": "Verify HMAC-SHA256(secret, timestamp + \".\" + original raw body). The signature header is sha256=. Reject timestamps outside your five-minute window and deduplicate event IDs. Each retry is freshly signed. GET the saved invoice with your server key and reconcile it before fulfilling once. invoice.confirmed includes the matched on-chain transaction.", "parameters": [ { "in": "header", "name": "X-SMeta-Event-Id", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-SMeta-Timestamp", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Unix seconds" }, { "in": "header", "name": "X-SMeta-Signature", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmedEvent" }, { "$ref": "#/components/schemas/Event" } ] } } } }, "responses": { "200": { "description": "Persisted successfully or already processed. Any 2xx acknowledges delivery." }, "400": { "description": "Invalid event" }, "401": { "description": "Invalid or stale signature" }, "503": { "description": "Temporary failure; retry delivery" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "smg_", "description": "Merchant server API key. Scopes: invoices:read, invoices:write, ledger:read. Never expose in browser code." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "smg_session", "description": "HttpOnly merchant owner session; used by the first-party dashboard. Write requests must pass allowed-origin checks." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." } }, "required": [ "error", "mode" ] }, "Merchant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "support_staff": { "type": "boolean", "description": "True when this account is listed in SUPPORT_STAFF_EMAILS and may use the support inbox." } }, "required": [ "id", "name", "email", "mode" ] }, "SupportTicket": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string", "description": "Human-friendly reference such as SMG-1A2B3C4D5E." }, "subject": { "type": "string" }, "category": { "enum": [ "general", "payments", "technical", "account", "other" ], "default": "general" }, "status": { "enum": [ "open", "answered", "closed" ], "description": "open: waiting for support; answered: support replied; closed: resolved." }, "source": { "enum": [ "dashboard", "contact" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "description": "Support inbox only." }, "email": { "type": "string", "description": "Support inbox only.", "format": "email" }, "merchant_id": { "type": [ "string", "null" ], "description": "Support inbox only. Null for public contact messages." }, "merchant_name": { "type": [ "string", "null" ], "description": "Support inbox only." } }, "required": [ "id", "reference", "subject", "category", "status", "source", "created_at", "updated_at" ] }, "SupportMessage": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "enum": [ "customer", "staff" ] }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "author", "body", "created_at" ] }, "SupportThread": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/SupportTicket" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SupportMessage" } } }, "required": [ "ticket", "messages" ] }, "Wallet": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "address": { "type": "string" }, "network": { "const": "tron-mainnet" }, "verified": { "const": false }, "verification_status": { "const": "unverified" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "label", "address", "network", "verified", "verification_status", "created_at" ] }, "CheckoutInvoice": { "type": "object", "properties": { "id": { "type": "string" }, "base_amount": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "adjustment": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "payable_amount": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "wallet_address": { "type": "string" }, "status": { "enum": [ "pending", "confirmed", "expired", "review" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "reserved_until": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ], "description": "TRON transaction hash of the matched USDT transfer (64 hex characters)." }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "network": { "const": "tron-mainnet" }, "token": { "const": "USDT" }, "token_contract": { "const": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }, "amount_reuse_review": { "type": "boolean" }, "merchant_name": { "type": "string", "description": "Merchant business display name." } }, "required": [ "id", "base_amount", "adjustment", "payable_amount", "wallet_address", "status", "mode", "merchant_name" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "base_amount": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "adjustment": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "payable_amount": { "type": "string", "description": "Exact USDT decimal string, six fractional digits in responses. Never a floating point number.", "pattern": "^[0-9]+\\.[0-9]{6}$", "examples": [ "49.953821" ] }, "wallet_address": { "type": "string" }, "status": { "enum": [ "pending", "confirmed", "expired", "review" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "reserved_until": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ], "description": "TRON transaction hash of the matched USDT transfer (64 hex characters)." }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "network": { "const": "tron-mainnet" }, "token": { "const": "USDT" }, "token_contract": { "const": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }, "amount_reuse_review": { "type": "boolean" }, "checkout_url": { "type": "string", "format": "uri" }, "checkout_token": { "type": "string", "description": "Capability token. Treat checkout URLs as confidential invoice links." }, "merchant_order_id": { "type": "string" }, "wallet_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "id", "base_amount", "adjustment", "payable_amount", "wallet_address", "status", "mode", "merchant_order_id", "wallet_id", "metadata" ] }, "CreateInvoice": { "type": "object", "properties": { "merchant_order_id": { "type": "string", "description": "Unique per merchant. Reuse the original idempotency key for retries.", "minLength": 1, "maxLength": 120 }, "amount": { "type": "string", "description": "Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment.", "pattern": "^(0|[1-9][0-9]{0,9})(\\.[0-9]{1,6})?$", "examples": [ "49.95" ] }, "wallet_id": { "type": "string", "description": "ID of a wallet registered to this merchant.", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "metadata": { "type": "object", "additionalProperties": true, "description": "JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata." }, "expires_in_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 20 } }, "required": [ "merchant_order_id", "amount", "wallet_id" ] }, "InvoiceEnvelope": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "idempotent_replay": { "type": "boolean" } }, "required": [ "invoice" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First characters of the secret, for identification only." }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "scopes": { "type": "array", "items": { "enum": [ "invoices:read", "invoices:write", "ledger:read" ] } }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null when the key never expires." }, "expired": { "type": "boolean" } }, "required": [ "id", "name", "prefix", "mode", "scopes" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" } }, "required": [ "id", "url", "active" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_id": { "type": "string" }, "status": { "enum": [ "pending", "sending", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "webhook_id", "event_id", "status", "attempts" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "enum": [ "invoice.created", "invoice.confirmed", "invoice.expired", "invoice.review", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "created_at", "mode", "data" ] }, "ConfirmedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "const": "invoice.confirmed" }, "created_at": { "type": "string", "format": "date-time" }, "mode": { "const": "live", "description": "Invoices are confirmed from verified TRON mainnet transfers." }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "transaction": { "type": "object", "properties": { "tx_hash": { "type": "string" }, "event_index": { "type": "integer" }, "from_address": { "type": "string" }, "block_number": { "type": "integer" }, "block_timestamp": { "type": "string", "format": "date-time" } }, "required": [ "tx_hash", "event_index", "from_address", "block_number", "block_timestamp" ] } }, "required": [ "invoice" ] } }, "required": [ "id", "type", "created_at", "mode", "data" ] }, "Dashboard": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "stats": { "type": "object", "additionalProperties": true } }, "required": [ "merchant", "wallets", "invoices", "events", "api_keys", "webhooks", "deliveries", "stats" ] } } } }