{ "openapi": "3.1.0", "info": { "title": "VeilNebula API", "version": "0.1.0", "summary": "Crypto-only payment gateway: hosted checkout, signed webhooks, ledger-derived balances, payouts and refunds.", "description": "VeilNebula accepts crypto payments over this API or through a hosted checkout page, and reports state changes over signed webhooks. Merchant identity is never verified — there is no KYC or KYB step — and the wallet half of the product is non-custodial.\n\nWhat a given deployment actually does depends on its configuration, so read GET /v1/services before integrating. Its `mode` field reports whether the published payment-method catalog is projected from the SANDBOX or the LIVE unit registry (PAYMENT_CATALOG_ENVIRONMENT), and its `boundaries` block reports which money paths are switched on. Deposit detection is gated by CHAIN_OBSERVATION_ENABLED. Outbound payout/refund broadcast and balance sweeps are gated by PAYOUT_BROADCAST_ENABLED, PAYOUT_SWEEP_ENABLED and SWEEP_ENABLED, all off by default; while they are off, payout and refund operations write ledger entries and emit completion webhooks without broadcasting any chain transaction.\n\nNot offered on any deployment: fiat acquiring, fiat conversion or fiat off-ramp; KYT/AML transaction screening; a contractual uptime SLA; and transaction mixing, anonymisation or any other privacy service. Blockchains are public — not asking who a merchant is does not hide who they are." }, "servers": [ { "url": "https://api.176-97-210-16.sslip.io", "description": "Deployed API" }, { "url": "http://localhost:4000", "description": "Local API" } ], "tags": [ { "name": "Reference" }, { "name": "Authentication" }, { "name": "Merchant self-service" }, { "name": "Admin provisioning" }, { "name": "Quotes" }, { "name": "Payments" }, { "name": "Payment links" }, { "name": "Checkout" }, { "name": "Webhooks" }, { "name": "Balances" }, { "name": "Swaps" }, { "name": "Reports" }, { "name": "Static wallets" }, { "name": "Sandbox transfers" }, { "name": "Sandbox jobs" } ], "paths": { "/checkout/{invoiceId}": { "get": { "tags": [ "Checkout" ], "summary": "Fetch public checkout state", "operationId": "getCheckout", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "responses": { "200": { "description": "Checkout invoice, methods, and active attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } } } } }, "/checkout/{invoiceId}/select-method": { "post": { "tags": [ "Checkout" ], "summary": "Select a sandbox payment method", "operationId": "selectCheckoutMethod", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectPaymentMethodRequest" } } } }, "responses": { "201": { "description": "Checkout state with active payment attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } } } } }, "/health": { "get": { "tags": [ "Reference" ], "summary": "Health check", "operationId": "healthCheck", "responses": { "200": { "description": "API health status", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service" ], "properties": { "status": { "type": "string", "const": "ok" }, "service": { "type": "string", "example": "nebula-api" } } } } } } } } }, "/pay/{paymentLinkId}": { "get": { "tags": [ "Payment links" ], "summary": "Fetch public reusable payment-link checkout state", "operationId": "getPaymentLinkCheckout", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkId" } ], "responses": { "200": { "description": "Reusable sandbox payment-link metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPaymentLink" } } } } } }, "post": { "tags": [ "Payment links" ], "summary": "Create a sandbox invoice from a reusable payment link", "operationId": "createPaymentFromPaymentLink", "parameters": [ { "$ref": "#/components/parameters/PaymentLinkId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentFromLinkRequest" } } } }, "responses": { "201": { "description": "Sandbox invoice created from the reusable payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkInvoice" } } } } } } }, "/v1/admin/merchants": { "get": { "tags": [ "Admin provisioning" ], "summary": "List sandbox merchants", "operationId": "listAdminMerchants", "security": [ { "AdminApiKey": [] } ], "responses": { "200": { "description": "Recent merchants", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Merchant" } } } } } } }, "post": { "tags": [ "Admin provisioning" ], "summary": "Create a sandbox merchant", "operationId": "createAdminMerchant", "security": [ { "AdminApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Sandbox" } } } } } }, "responses": { "201": { "description": "Created merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } } } } }, "/v1/admin/merchants/{merchantId}/projects": { "get": { "tags": [ "Admin provisioning" ], "summary": "List projects for a merchant", "operationId": "listAdminMerchantProjects", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantId" } ], "responses": { "200": { "description": "Recent projects for the merchant", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } }, "post": { "tags": [ "Admin provisioning" ], "summary": "Create a sandbox project", "operationId": "createAdminMerchantProject", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } }, "responses": { "201": { "description": "Created project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/v1/admin/payment-jobs/projects/{projectId}/run-webhooks": { "post": { "tags": [ "Sandbox jobs" ], "summary": "Run due webhook delivery jobs for one project", "operationId": "runProjectWebhooks", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "201": { "description": "Job run summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentJobsSummary" } } } } } } }, "/v1/admin/payment-jobs/run-due": { "post": { "tags": [ "Sandbox jobs" ], "summary": "Run due invoice expiry and webhook jobs", "operationId": "runPaymentJobs", "security": [ { "AdminApiKey": [] } ], "responses": { "201": { "description": "Job run summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentJobsSummary" } } } } } } }, "/v1/admin/projects/{projectId}/api-keys": { "get": { "tags": [ "Admin provisioning" ], "summary": "List project API keys", "operationId": "listAdminProjectApiKeys", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Project API keys without raw secrets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "post": { "tags": [ "Admin provisioning" ], "summary": "Create a project API key", "operationId": "createAdminProjectApiKey", "description": "The raw API key is returned only once.", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } } } } }, "/v1/admin/projects/{projectId}/api-keys/{apiKeyId}/revoke": { "post": { "tags": [ "Admin provisioning" ], "summary": "Revoke a project API key", "operationId": "revokeAdminProjectApiKey", "security": [ { "AdminApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "name": "apiKeyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Revoked API key metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Create a merchant session", "operationId": "loginMerchant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "201": { "description": "Created merchant session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/v1/auth/signup": { "post": { "tags": [ "Authentication" ], "summary": "Create a merchant user, merchant, and default project", "operationId": "signupMerchant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "201": { "description": "Created merchant session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } } } } }, "/v1/balances": { "get": { "tags": [ "Balances" ], "summary": "List ledger-derived balances", "operationId": "listBalances", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Merchant balances.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } } } } }, "/v1/exchange-rates": { "get": { "tags": [ "Reference" ], "summary": "Get a live exchange rate", "operationId": "getExchangeRate", "security": [], "parameters": [ { "name": "asset", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" }, "example": "BTC" }, { "name": "quote", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" }, "example": "USD" } ], "responses": { "200": { "description": "Live provider-backed exchange-rate observation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRate" } } } } } } }, "/v1/me": { "get": { "tags": [ "Merchant self-service" ], "summary": "Fetch the current merchant user", "operationId": "getCurrentMerchantUser", "security": [ { "MerchantSession": [] } ], "responses": { "200": { "description": "Current merchant user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentMerchantUserResponse" } } } } } } }, "/v1/merchant/merchants/{merchantId}/projects": { "get": { "tags": [ "Merchant self-service" ], "summary": "List projects for a merchant", "operationId": "listMerchantProjects", "security": [ { "MerchantSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantId" } ], "responses": { "200": { "description": "Projects for the merchant", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantProject" } } } } } } }, "post": { "tags": [ "Merchant self-service" ], "summary": "Create a merchant project", "operationId": "createMerchantProject", "security": [ { "MerchantSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantProjectRequest" } } } }, "responses": { "201": { "description": "Created project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantProject" } } } } } } }, "/v1/merchant/merchants/{merchantId}/projects/{projectId}/api-keys": { "post": { "tags": [ "Merchant self-service" ], "summary": "Create a project API key", "operationId": "createMerchantProjectApiKey", "description": "The raw API key is returned only once.", "security": [ { "MerchantSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantId" }, { "$ref": "#/components/parameters/ProjectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantApiKeyRequest" } } } }, "responses": { "201": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedMerchantApiKey" } } } } } } }, "/v1/mock-chain/static-wallet-topups": { "post": { "tags": [ "Sandbox jobs" ], "summary": "Simulate a static wallet top-up", "operationId": "createMockStaticWalletTopUp", "description": "Admin/dev-only endpoint for sandbox demos. It records a completed mock static-wallet top-up, posts ledger entries, updates wallet totals, and queues static-wallet webhooks. It does not monitor or broadcast live blockchain transactions.", "security": [ { "AdminApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaticWalletTopUpRequest" } } } }, "responses": { "201": { "description": "Recorded sandbox static-wallet top-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticWalletTopUp" } } } } } } }, "/v1/mock-chain/transactions": { "post": { "tags": [ "Sandbox jobs" ], "summary": "Simulate an incoming chain transaction", "operationId": "createMockChainTransaction", "description": "Admin/dev-only endpoint for sandbox demos. It records mock-chain activity, updates payment status, posts ledger entries, and queues payment webhooks.", "security": [ { "AdminApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMockChainTransactionRequest" } } } }, "responses": { "201": { "description": "Recorded mock-chain transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockChainTransaction" } } } } } } }, "/v1/payment-links": { "get": { "tags": [ "Payment links" ], "summary": "List reusable sandbox payment links", "operationId": "listPaymentLinks", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Recent reusable sandbox payment links.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "post": { "tags": [ "Payment links" ], "summary": "Create a reusable sandbox payment link", "description": "Creates a reusable hosted sandbox link that can mint checkout invoices for one crypto asset/network pair. Production/live settlement remains pending.", "operationId": "createPaymentLink", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" } } } }, "responses": { "201": { "description": "Created reusable sandbox payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "/v1/payment-links/{paymentLinkId}": { "get": { "tags": [ "Payment links" ], "summary": "Fetch one reusable sandbox payment link", "operationId": "getPaymentLink", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PaymentLinkId" } ], "responses": { "200": { "description": "Reusable sandbox payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "/v1/payment-links/{paymentLinkId}/disable": { "post": { "tags": [ "Payment links" ], "summary": "Disable a reusable sandbox payment link", "operationId": "disablePaymentLink", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PaymentLinkId" } ], "responses": { "200": { "description": "Disabled reusable sandbox payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "/v1/payments": { "get": { "tags": [ "Payments" ], "summary": "List project invoices", "operationId": "listPayments", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Recent invoices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create a crypto invoice", "operationId": "createPayment", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } } }, "responses": { "201": { "description": "Created invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } } }, "/v1/payments/{paymentId}": { "get": { "tags": [ "Payments" ], "summary": "Fetch one invoice", "operationId": "getPayment", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PaymentId" } ], "responses": { "200": { "description": "Invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } } }, "/v1/payments/{paymentId}/sandbox/simulate-paid": { "post": { "tags": [ "Payments" ], "summary": "Simulate a paid sandbox invoice for the authenticated project", "description": "Project-key facade for sandbox design partners. The invoice must belong to the authenticated project and have an active checkout attempt selected. Disabled in production.", "operationId": "simulateSandboxPayment", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PaymentId" } ], "responses": { "201": { "description": "Sandbox payment simulation recorded for the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockChainTransaction" } } } } } } }, "/v1/payouts": { "get": { "tags": [ "Sandbox transfers" ], "summary": "List sandbox payouts", "operationId": "listPayouts", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Recent sandbox payouts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "post": { "tags": [ "Sandbox transfers" ], "summary": "Create a simulated sandbox payout", "operationId": "createPayout", "description": "Completes immediately in sandbox and queues payout.completed for subscribed webhook endpoints. It does not broadcast a live blockchain transaction.", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutRequest" } } } }, "responses": { "201": { "description": "Completed sandbox payout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "/v1/payouts/{transferId}": { "get": { "tags": [ "Sandbox transfers" ], "summary": "Fetch one sandbox payout", "operationId": "getPayout", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/TransferId" } ], "responses": { "200": { "description": "Sandbox payout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "/v1/quotes/fees": { "get": { "tags": [ "Quotes" ], "summary": "Preview deterministic sandbox invoice fees", "operationId": "quoteFees", "description": "This is a sandbox crypto fee preview, not a live exchange-rate quote and not a fiat conversion quote.", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "amountMinor", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/MinorAmount" }, "example": "10000" }, { "name": "currencyCode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AssetCode" }, "example": "USDT" }, { "name": "settlementAssetCode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AssetCode" }, "example": "USDT" } ], "responses": { "200": { "description": "Fee quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeQuote" } } } } } } }, "/v1/refunds": { "get": { "tags": [ "Sandbox transfers" ], "summary": "List sandbox refunds", "operationId": "listRefunds", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Recent sandbox refunds.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "post": { "tags": [ "Sandbox transfers" ], "summary": "Create a simulated sandbox refund", "operationId": "createRefund", "description": "Completes immediately in sandbox and queues refund.completed for subscribed webhook endpoints. It does not broadcast a live blockchain transaction.", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" } } } }, "responses": { "201": { "description": "Completed sandbox refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "/v1/refunds/{transferId}": { "get": { "tags": [ "Sandbox transfers" ], "summary": "Fetch one sandbox refund", "operationId": "getRefund", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/TransferId" } ], "responses": { "200": { "description": "Sandbox refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantTransfer" } } } } } } }, "/v1/reports/balances.csv": { "get": { "tags": [ "Reports" ], "summary": "Export ledger balances CSV", "operationId": "exportBalancesReportCsv", "description": "Exports the authenticated project's merchant ledger accounts as a CSV attachment. Each row is one account with its balance summed from its entries, in minor units.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "CSV attachment with one row per ledger account.", "headers": { "Content-Disposition": { "description": "Attachment filename intent.", "schema": { "type": "string" }, "example": "attachment; filename=\"nebula-balances.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "examples": [ "accountId,assetCode,type,name,balanceMinor\nacct_1,USDT,MERCHANT_PAYABLE,Merchant payable USDT,96500000" ] } } } } } } }, "/v1/reports/payment-links.csv": { "get": { "tags": [ "Reports" ], "summary": "Export payment links CSV", "operationId": "exportPaymentLinksReportCsv", "description": "Exports recent payment links for the authenticated project as a CSV attachment.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "CSV attachment with sandbox payment-link rows.", "headers": { "Content-Disposition": { "description": "Attachment filename intent.", "schema": { "type": "string" }, "example": "attachment; filename=\"nebula-payment-links.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "examples": [ "id,externalId,title,status,assetCode,networkCode,amountMinor,maxUses,usedCount,invoiceCount,expiresAt,createdAt,updatedAt\nplink_1,menu_link,Menu link,active,USDT,TRON,10000,10,2,2,,2026-06-09T00:00:00.000Z,2026-06-09T00:05:00.000Z" ] } } } } } } }, "/v1/reports/payments.csv": { "get": { "tags": [ "Reports" ], "summary": "Export payments CSV", "operationId": "exportPaymentsReportCsv", "description": "Exports recent payment invoices for the authenticated project as a CSV attachment.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "CSV attachment with sandbox payment rows.", "headers": { "Content-Disposition": { "description": "Attachment filename intent.", "schema": { "type": "string" }, "example": "attachment; filename=\"nebula-payments.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "examples": [ "id,externalId,status,amountMinor,currencyCode,settlementAssetCode,paymentLinkId,processingFeeMinor,networkFeeReserveMinor,riskReserveMinor,platformMarginMinor,totalFeeMinor,netAmountMinor,createdAt,updatedAt\ninvoice_1,order_1001,paid,10000,USDT,USDT,,100,0,0,100,200,9800,2026-06-09T00:00:00.000Z,2026-06-09T00:05:00.000Z" ] } } } } } } }, "/v1/reports/summary": { "get": { "tags": [ "Reports" ], "summary": "Get reporting summary", "operationId": "getReportsSummary", "description": "Ledger-derived reporting summary for the authenticated crypto-only project.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Reconciliation summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportsSummary" } } } } } } }, "/v1/reports/transfers.csv": { "get": { "tags": [ "Reports" ], "summary": "Export transfers CSV", "operationId": "exportTransfersReportCsv", "description": "Exports recent payouts and refunds for the authenticated project as a CSV attachment.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "CSV attachment with sandbox transfer rows.", "headers": { "Content-Disposition": { "description": "Attachment filename intent.", "schema": { "type": "string" }, "example": "attachment; filename=\"nebula-transfers.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "examples": [ "id,type,status,invoiceId,externalId,assetCode,networkCode,amountMinor,networkFeeMinor,simulatedTxHash,completedAt,createdAt,updatedAt\ntransfer_1,refund,completed,invoice_1,refund_1,USDT,TRON,2000,5,sandbox_refund_tx,2026-06-09T00:05:00.000Z,2026-06-09T00:00:00.000Z,2026-06-09T00:05:00.000Z" ] } } } } } } }, "/v1/reports/webhooks.csv": { "get": { "tags": [ "Reports" ], "summary": "Export webhook deliveries CSV", "operationId": "exportWebhooksReportCsv", "description": "Exports recent webhook deliveries for the authenticated project as a CSV attachment.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "CSV attachment with sandbox webhook delivery rows.", "headers": { "Content-Disposition": { "description": "Attachment filename intent.", "schema": { "type": "string" }, "example": "attachment; filename=\"nebula-webhooks.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string", "examples": [ "id,endpointId,endpointUrl,invoiceId,eventType,status,attemptCount,lastResponseStatus,lastError,createdAt,updatedAt\ndelivery_1,endpoint_1,https://merchant.example/webhooks,invoice_1,payment.paid,delivered,1,200,,2026-06-09T00:00:00.000Z,2026-06-09T00:05:00.000Z" ] } } } } } } }, "/v1/services": { "get": { "tags": [ "Reference" ], "summary": "List deployment service metadata", "operationId": "listServices", "responses": { "200": { "description": "Supported payment methods, statuses, events, headers, and sandbox boundaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceReference" } } } } } } }, "/v1/static-wallets": { "get": { "tags": [ "Static wallets" ], "summary": "List sandbox static wallets", "operationId": "listStaticWallets", "description": "Lists reusable sandbox customer/order wallets for the authenticated project. These are not live deposit wallets.", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Recent sandbox static wallets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StaticWallet" } } } } } } }, "post": { "tags": [ "Static wallets" ], "summary": "Create a sandbox static wallet", "operationId": "createStaticWallet", "description": "Creates a reusable sandbox static wallet address for crypto-to-crypto pilot testing. The address is mock-only and does not monitor live chains.", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaticWalletRequest" } } } }, "responses": { "201": { "description": "Created sandbox static wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticWallet" } } } } } } }, "/v1/static-wallets/{walletId}": { "get": { "tags": [ "Static wallets" ], "summary": "Fetch one sandbox static wallet", "operationId": "getStaticWallet", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sandbox static wallet details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticWallet" } } } } } } }, "/v1/static-wallets/{walletId}/block": { "post": { "tags": [ "Static wallets" ], "summary": "Block a sandbox static wallet", "operationId": "blockStaticWallet", "description": "Blocks further sandbox mock top-ups for a static wallet. This is a sandbox control, not a live chain blocklist.", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Blocked sandbox static wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticWallet" } } } } } } }, "/v1/static-wallets/{walletId}/topups": { "get": { "tags": [ "Static wallets" ], "summary": "List sandbox static wallet top-ups", "operationId": "listStaticWalletTopUps", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent completed sandbox top-ups for this static wallet.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StaticWalletTopUp" } } } } } } } }, "/v1/static-wallets/{walletId}/unblock": { "post": { "tags": [ "Static wallets" ], "summary": "Unblock a sandbox static wallet", "operationId": "unblockStaticWallet", "description": "Re-enables sandbox mock top-ups for a static wallet.", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Unblocked sandbox static wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaticWallet" } } } } } } }, "/v1/swaps": { "post": { "tags": [ "Swaps" ], "summary": "Execute a sandbox balance swap", "operationId": "executeSwap", "description": "Executes only when the authenticated project environment exposes eligible units. LIVE swaps remain disabled until funded inventory admission is available.", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapExecuteInput" } } } }, "responses": { "201": { "description": "Executed sandbox swap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapResult" } } } } } } }, "/v1/swaps/page": { "get": { "tags": [ "Swaps" ], "summary": "List cursor-paginated swap history", "operationId": "listSwapsPage", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Swap history page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapListPageResponse" } } } } } } }, "/v1/swaps/quote": { "get": { "tags": [ "Swaps" ], "summary": "Quote an exact directed unit swap", "operationId": "quoteSwap", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "fromAsset", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" } }, { "name": "fromNetworkCode", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "toAsset", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" } }, { "name": "toNetworkCode", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Directed quote with exact source and target unit metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuote" } } } } } } }, "/v1/swaps/units": { "get": { "tags": [ "Swaps" ], "summary": "List swap-eligible canonical units", "operationId": "listSwapUnits", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Authoritative unit catalog for the project environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapUnitsResponse" } } } } } } }, "/v1/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Recent deliveries.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } } }, "/v1/webhooks/deliveries/run-due": { "post": { "tags": [ "Webhooks" ], "summary": "Run due webhook deliveries for the authenticated project", "operationId": "runDueWebhookDeliveries", "security": [ { "ProjectApiKey": [] } ], "responses": { "201": { "description": "Delivery job summary for this project only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliverySummary" } } } } } } }, "/v1/webhooks/deliveries/{deliveryId}/resend": { "post": { "tags": [ "Webhooks" ], "summary": "Queue a resend for a terminal delivery", "operationId": "resendWebhookDelivery", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/DeliveryId" } ], "responses": { "201": { "description": "Fresh pending delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "/v1/webhooks/endpoints": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhookEndpoints", "security": [ { "ProjectApiKey": [] } ], "responses": { "200": { "description": "Webhook endpoints without secrets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "operationId": "createWebhookEndpoint", "description": "Webhook URLs must target public http or https hosts. The signing secret is returned only once.", "security": [ { "ProjectApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "Created webhook endpoint with signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } } } } }, "/v1/webhooks/endpoints/{endpointId}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a signed webhook.test delivery", "operationId": "testWebhookEndpoint", "security": [ { "ProjectApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "201": { "description": "Delivered or queued test delivery record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } } }, "components": { "securitySchemes": { "ProjectApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "MerchantSession": { "type": "http", "scheme": "bearer" }, "AdminApiKey": { "type": "apiKey", "in": "header", "name": "x-admin-api-key" } }, "parameters": { "DeliveryId": { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } }, "EndpointId": { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string" } }, "InvoiceId": { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "MerchantId": { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, "PaymentId": { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "PaymentLinkId": { "name": "paymentLinkId", "in": "path", "required": true, "schema": { "type": "string" } }, "ProjectId": { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, "TransferId": { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string" } } }, "schemas": { "ApiKeyScope": { "type": "string", "enum": [ "payments:*", "payments:read", "payments:write" ] }, "AssetCode": { "type": "string", "pattern": "^[A-Z0-9]{2,16}$", "examples": [ "USDT", "BTC", "ETH" ] }, "MinorAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "10000" ] }, "ExchangeRate": { "type": "object", "required": [ "assetCode", "quoteCurrency", "price", "priceMicros", "providerName", "observedAt" ], "properties": { "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "quoteCurrency": { "$ref": "#/components/schemas/AssetCode" }, "price": { "type": "number", "exclusiveMinimum": 0 }, "priceMicros": { "$ref": "#/components/schemas/MinorAmount" }, "providerName": { "type": "string", "minLength": 1 }, "observedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "IsoDateTime": { "type": "string", "format": "date-time" }, "NullableIsoDateTime": { "anyOf": [ { "$ref": "#/components/schemas/IsoDateTime" }, { "type": "null" } ] }, "NullableString": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "SignupRequest": { "type": "object", "required": [ "email", "password", "merchantName" ], "properties": { "email": { "type": "string", "format": "email", "example": "owner@merchant.example" }, "password": { "type": "string", "minLength": 12, "format": "password", "example": "correct-horse-battery-staple" }, "merchantName": { "type": "string", "minLength": 1, "pattern": "\\S", "example": "Acme Sandbox" }, "projectName": { "type": "string", "example": "Acme Store" } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "owner@merchant.example" }, "password": { "type": "string", "format": "password", "example": "correct-horse-battery-staple" } } }, "MerchantMembership": { "type": "object", "required": [ "merchantId", "role" ], "properties": { "merchantId": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "DEVELOPER", "FINANCE", "SUPPORT", "READ_ONLY" ] } } }, "AuthResponse": { "type": "object", "required": [ "token", "user", "memberships", "expiresAt" ], "properties": { "token": { "type": "string", "description": "Merchant session bearer token." }, "user": { "type": "object", "required": [ "id", "email" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMembership" } }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CurrentMerchantUserResponse": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "object", "required": [ "id", "email", "memberships" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMembership" } } } } } }, "Merchant": { "type": "object", "required": [ "id", "name", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "example": "active" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S", "example": "Acme Store" }, "callbackUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "example": "https://merchant.example/webhooks/veilnebula" }, "returnUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "example": "https://merchant.example/thanks" } } }, "Project": { "type": "object", "required": [ "id", "merchantId", "name", "status", "callbackUrl", "returnUrl", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "merchantId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "example": "active" }, "callbackUrl": { "$ref": "#/components/schemas/NullableString" }, "returnUrl": { "$ref": "#/components/schemas/NullableString" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S", "example": "Sandbox integration" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "example": [ "payments:*" ] } } }, "ApiKey": { "type": "object", "required": [ "id", "projectId", "name", "scopes", "lastUsedAt", "revokedAt", "createdAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" } }, "lastUsedAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "revokedAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreatedApiKey": { "type": "object", "required": [ "id", "projectId", "name", "scopes", "rawKey", "createdAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" } }, "rawKey": { "type": "string", "example": "ncp_sandbox_replace_me" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateMerchantProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S", "example": "Acme Store" }, "callbackUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "example": "https://merchant.example/webhooks/veilnebula" }, "returnUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "example": "https://merchant.example/thanks" } } }, "MerchantProject": { "type": "object", "required": [ "id", "merchantId", "name", "status", "callbackUrl", "returnUrl", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "merchantId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "example": "ACTIVE" }, "callbackUrl": { "$ref": "#/components/schemas/NullableString" }, "returnUrl": { "$ref": "#/components/schemas/NullableString" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateMerchantApiKeyRequest": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S", "example": "Sandbox integration" }, "scopes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "example": [ "payments:*" ] } } }, "CreatedMerchantApiKey": { "type": "object", "required": [ "id", "projectId", "name", "scopes", "rawKey", "createdAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" } }, "rawKey": { "type": "string", "example": "ncp_sandbox_replace_me" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "FeeQuote": { "type": "object", "required": [ "mode", "amountMinor", "currencyCode", "settlementAssetCode", "processingFeeMinor", "networkFeeReserveMinor", "riskReserveMinor", "platformMarginMinor", "totalFeeMinor", "netAmountMinor", "quoteExpiresAt", "expiresAt" ], "properties": { "mode": { "type": "string", "const": "sandbox" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currencyCode": { "$ref": "#/components/schemas/AssetCode" }, "settlementAssetCode": { "$ref": "#/components/schemas/AssetCode" }, "processingFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "riskReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "platformMarginMinor": { "$ref": "#/components/schemas/MinorAmount" }, "totalFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "netAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "quoteExpiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreatePaymentRequest": { "type": "object", "required": [ "amountMinor", "currencyCode" ], "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currencyCode": { "$ref": "#/components/schemas/AssetCode" }, "settlementAssetCode": { "$ref": "#/components/schemas/AssetCode" }, "description": { "type": "string", "example": "Order #1001" }, "externalId": { "type": "string", "example": "order_1001" }, "idempotencyKey": { "type": "string", "example": "order_1001" }, "successUrl": { "type": "string", "format": "uri" }, "cancelUrl": { "type": "string", "format": "uri" }, "paymentLinkId": { "type": "string", "description": "Reusable sandbox payment link that created or owns this invoice." } }, "examples": [ { "amountMinor": "10000", "currencyCode": "USDT", "settlementAssetCode": "USDT", "description": "Order #1001", "externalId": "order_1001", "idempotencyKey": "order_1001" } ] }, "Payment": { "type": "object", "required": [ "id", "projectId", "merchantId", "idempotencyKey", "externalId", "amountMinor", "currencyCode", "settlementAssetCode", "status", "description", "checkoutUrl", "successUrl", "cancelUrl", "paymentLinkId", "processingFeeMinor", "networkFeeReserveMinor", "riskReserveMinor", "platformMarginMinor", "totalFeeMinor", "netAmountMinor", "quoteExpiresAt", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "idempotencyKey": { "$ref": "#/components/schemas/NullableString" }, "externalId": { "$ref": "#/components/schemas/NullableString" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currencyCode": { "$ref": "#/components/schemas/AssetCode" }, "settlementAssetCode": { "$ref": "#/components/schemas/AssetCode" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "description": { "$ref": "#/components/schemas/NullableString" }, "checkoutUrl": { "type": "string", "format": "uri" }, "successUrl": { "$ref": "#/components/schemas/NullableString" }, "cancelUrl": { "$ref": "#/components/schemas/NullableString" }, "paymentLinkId": { "$ref": "#/components/schemas/NullableString" }, "processingFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "riskReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "platformMarginMinor": { "$ref": "#/components/schemas/MinorAmount" }, "totalFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "netAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "quoteExpiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreatePaymentLinkRequest": { "type": "object", "required": [ "amountMinor", "assetCode", "networkCode" ], "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "title": { "type": "string", "example": "Sandbox USDT checkout" }, "description": { "type": "string", "example": "Reusable sandbox checkout link" }, "externalId": { "type": "string", "example": "link_usdt_tron_100" }, "idempotencyKey": { "type": "string", "example": "payment-link:usdt-tron-100" }, "successUrl": { "type": "string", "format": "uri" }, "cancelUrl": { "type": "string", "format": "uri" }, "maxUses": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" } }, "examples": [ { "amountMinor": "10000", "assetCode": "USDT", "networkCode": "TRON", "title": "Sandbox order link", "description": "Reusable USDT/TRON sandbox checkout", "idempotencyKey": "payment-link:usdt-tron-100" } ] }, "PaymentLink": { "type": "object", "required": [ "id", "projectId", "merchantId", "idempotencyKey", "externalId", "title", "description", "assetCode", "networkCode", "amountMinor", "paymentLinkUrl", "successUrl", "cancelUrl", "status", "maxUses", "usedCount", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "idempotencyKey": { "$ref": "#/components/schemas/NullableString" }, "externalId": { "$ref": "#/components/schemas/NullableString" }, "title": { "$ref": "#/components/schemas/NullableString" }, "description": { "$ref": "#/components/schemas/NullableString" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "paymentLinkUrl": { "type": "string", "format": "uri" }, "successUrl": { "$ref": "#/components/schemas/NullableString" }, "cancelUrl": { "$ref": "#/components/schemas/NullableString" }, "status": { "$ref": "#/components/schemas/PaymentLinkStatus" }, "maxUses": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483647 }, { "type": "null" } ] }, "usedCount": { "type": "integer", "minimum": 0 }, "expiresAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "PaymentLinkStatus": { "type": "string", "enum": [ "active", "disabled", "expired" ] }, "PaymentLinkCheckout": { "type": "object", "required": [ "paymentLink", "paymentMethods" ], "properties": { "paymentLink": { "$ref": "#/components/schemas/PaymentLink" }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "PublicPaymentLink": { "type": "object", "required": [ "id", "title", "description", "assetCode", "networkCode", "amountMinor", "paymentLinkUrl", "successUrl", "cancelUrl", "status", "maxUses", "usedCount", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "title": { "$ref": "#/components/schemas/NullableString" }, "description": { "$ref": "#/components/schemas/NullableString" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "paymentLinkUrl": { "type": "string", "format": "uri" }, "successUrl": { "$ref": "#/components/schemas/NullableString" }, "cancelUrl": { "$ref": "#/components/schemas/NullableString" }, "status": { "$ref": "#/components/schemas/PaymentLinkStatus" }, "maxUses": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483647 }, { "type": "null" } ] }, "usedCount": { "type": "integer", "minimum": 0 }, "expiresAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreatePaymentFromLinkRequest": { "type": "object", "properties": { "externalId": { "type": "string", "example": "order_1001" } } }, "PaymentLinkInvoice": { "type": "object", "required": [ "paymentLinkId", "checkoutUrl", "paymentLink", "invoice", "activeAttempt" ], "properties": { "paymentLinkId": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri" }, "paymentLink": { "$ref": "#/components/schemas/PublicPaymentLink" }, "invoice": { "$ref": "#/components/schemas/PaymentLinkCreatedInvoice" }, "activeAttempt": { "$ref": "#/components/schemas/PaymentAttempt" } } }, "PaymentLinkCreatedInvoice": { "type": "object", "required": [ "id", "amountMinor", "currencyCode", "settlementAssetCode", "status", "checkoutUrl", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currencyCode": { "$ref": "#/components/schemas/AssetCode" }, "settlementAssetCode": { "$ref": "#/components/schemas/AssetCode" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "checkoutUrl": { "type": "string", "format": "uri" }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "InvoiceStatus": { "type": "string", "enum": [ "new", "pending", "confirming", "paid", "partially_paid", "overpaid", "expired", "cancelled", "failed", "refunded" ] }, "PaymentMethod": { "type": "object", "required": [ "assetCode", "networkCode", "displayName", "requiredConfirmations" ], "properties": { "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "displayName": { "type": "string", "example": "USDT TRC20" }, "requiredConfirmations": { "type": "integer", "minimum": 1 } } }, "SelectPaymentMethodRequest": { "type": "object", "required": [ "assetCode", "networkCode" ], "properties": { "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" } } }, "PaymentAttempt": { "type": "object", "required": [ "id", "assetCode", "networkCode", "depositAddress", "expectedAmountMinor", "receivedAmountMinor", "confirmations", "requiredConfirmations", "txHash", "status" ], "properties": { "id": { "type": "string" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string" }, "depositAddress": { "type": "string" }, "expectedAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "receivedAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "confirmations": { "type": "integer", "minimum": 0 }, "requiredConfirmations": { "type": "integer", "minimum": 1 }, "txHash": { "$ref": "#/components/schemas/NullableString" }, "status": { "type": "string", "example": "pending" } } }, "PublicCheckoutInvoice": { "type": "object", "required": [ "id", "amountMinor", "currencyCode", "settlementAssetCode", "status", "description", "checkoutUrl", "processingFeeMinor", "networkFeeReserveMinor", "riskReserveMinor", "platformMarginMinor", "totalFeeMinor", "netAmountMinor", "quoteExpiresAt", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "currencyCode": { "$ref": "#/components/schemas/AssetCode" }, "settlementAssetCode": { "$ref": "#/components/schemas/AssetCode" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "description": { "$ref": "#/components/schemas/NullableString" }, "checkoutUrl": { "type": "string", "format": "uri" }, "processingFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "riskReserveMinor": { "$ref": "#/components/schemas/MinorAmount" }, "platformMarginMinor": { "$ref": "#/components/schemas/MinorAmount" }, "totalFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "netAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "quoteExpiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "expiresAt": { "$ref": "#/components/schemas/IsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "Checkout": { "type": "object", "required": [ "invoice", "paymentMethods", "activeAttempt" ], "properties": { "invoice": { "$ref": "#/components/schemas/PublicCheckoutInvoice" }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "activeAttempt": { "anyOf": [ { "$ref": "#/components/schemas/PaymentAttempt" }, { "type": "null" } ] } } }, "WebhookEvent": { "type": "string", "enum": [ "webhook.test", "payment.pending", "payment.confirming", "payment.paid", "payment.partially_paid", "payment.overpaid", "payment.expired", "payout.completed", "refund.completed", "static_wallet.created", "static_wallet.blocked", "static_wallet.unblocked", "static_wallet.topup.completed" ] }, "CreateWebhookEndpointRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://merchant.example/webhooks/veilnebula" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "example": [ "payment.pending", "payment.paid", "payout.completed", "refund.completed" ] } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "projectId", "url", "enabled", "events", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreatedWebhookEndpoint": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string" } } } ] }, "WebhookDelivery": { "type": "object", "required": [ "id", "endpointId", "endpointUrl", "invoiceId", "eventType", "status", "attemptCount", "nextAttemptAt", "lastResponseStatus", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "endpointUrl": { "type": "string", "format": "uri" }, "invoiceId": { "$ref": "#/components/schemas/NullableString" }, "eventType": { "$ref": "#/components/schemas/WebhookEvent" }, "status": { "type": "string", "enum": [ "pending", "delivered", "retrying", "failed" ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "nextAttemptAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "lastResponseStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastError": { "$ref": "#/components/schemas/NullableString" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "BalanceResponse": { "type": "object", "required": [ "merchantId", "projectId", "balances" ], "properties": { "merchantId": { "type": "string" }, "projectId": { "type": "string" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } }, "Balance": { "type": "object", "required": [ "accountId", "assetCode", "unitId", "networkCode", "decimals", "type", "name", "balanceMinor" ], "properties": { "accountId": { "type": "string" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "unitId": { "$ref": "#/components/schemas/NullableString" }, "networkCode": { "$ref": "#/components/schemas/NullableString" }, "decimals": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "type": { "type": "string", "example": "merchant_payable" }, "name": { "type": "string" }, "balanceMinor": { "type": "string", "pattern": "^-?[0-9]+$" } } }, "SwapUnitOption": { "type": "object", "required": [ "unitId", "assetCode", "networkCode", "decimals", "minAmountMinor", "maxAmountMinor" ], "properties": { "unitId": { "type": "string" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 }, "minAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "maxAmountMinor": { "$ref": "#/components/schemas/MinorAmount" } } }, "SwapUnitsResponse": { "type": "object", "required": [ "environment", "units" ], "properties": { "environment": { "type": "string", "enum": [ "SANDBOX", "LIVE" ] }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/SwapUnitOption" } } } }, "SwapQuote": { "type": "object", "required": [ "fromAsset", "fromUnitId", "fromNetworkCode", "fromDecimals", "toAsset", "toUnitId", "toNetworkCode", "toDecimals", "priceMicros", "observedAt" ], "properties": { "fromAsset": { "$ref": "#/components/schemas/AssetCode" }, "fromUnitId": { "type": "string" }, "fromNetworkCode": { "type": "string" }, "fromDecimals": { "type": "integer", "minimum": 0 }, "toAsset": { "$ref": "#/components/schemas/AssetCode" }, "toUnitId": { "type": "string" }, "toNetworkCode": { "type": "string" }, "toDecimals": { "type": "integer", "minimum": 0 }, "priceMicros": { "$ref": "#/components/schemas/MinorAmount" }, "observedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "SwapExecuteInput": { "type": "object", "required": [ "fromAsset", "fromNetworkCode", "toAsset", "toNetworkCode", "amountMinor" ], "properties": { "fromAsset": { "$ref": "#/components/schemas/AssetCode" }, "fromNetworkCode": { "type": "string" }, "toAsset": { "$ref": "#/components/schemas/AssetCode" }, "toNetworkCode": { "type": "string" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "SwapResult": { "type": "object", "required": [ "id", "fromAsset", "fromUnitId", "fromNetworkCode", "fromDecimals", "toAsset", "toUnitId", "toNetworkCode", "toDecimals", "fromAmountMinor", "toAmountMinor", "priceMicros", "spreadBps", "executedAt" ], "properties": { "id": { "type": "string" }, "fromAsset": { "$ref": "#/components/schemas/AssetCode" }, "fromUnitId": { "type": "string" }, "fromNetworkCode": { "type": "string" }, "fromDecimals": { "type": "integer", "minimum": 0 }, "toAsset": { "$ref": "#/components/schemas/AssetCode" }, "toUnitId": { "type": "string" }, "toNetworkCode": { "type": "string" }, "toDecimals": { "type": "integer", "minimum": 0 }, "fromAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "toAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "priceMicros": { "$ref": "#/components/schemas/MinorAmount" }, "spreadBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "executedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "SwapListItem": { "type": "object", "required": [ "id", "fromAsset", "fromUnitId", "fromNetworkCode", "fromDecimals", "toAsset", "toUnitId", "toNetworkCode", "toDecimals", "fromAmountMinor", "toAmountMinor", "spreadCapturedMinor", "executedAt" ], "properties": { "id": { "type": "string" }, "fromAsset": { "$ref": "#/components/schemas/AssetCode" }, "fromUnitId": { "type": "string" }, "fromNetworkCode": { "type": "string" }, "fromDecimals": { "type": "integer", "minimum": 0 }, "toAsset": { "$ref": "#/components/schemas/AssetCode" }, "toUnitId": { "type": "string" }, "toNetworkCode": { "type": "string" }, "toDecimals": { "type": "integer", "minimum": 0 }, "fromAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "toAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "spreadCapturedMinor": { "$ref": "#/components/schemas/MinorAmount" }, "executedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "SwapListPageResponse": { "type": "object", "required": [ "data", "nextCursor", "hasMore" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SwapListItem" } }, "nextCursor": { "$ref": "#/components/schemas/NullableString" }, "hasMore": { "type": "boolean" } } }, "ReportsCountAndAmountBucket": { "type": "object", "required": [ "count", "amountMinor" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "amountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } }, "ReportsCountAndAmountMap": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ReportsCountAndAmountBucket" } }, "ReportsPaymentsSummary": { "type": "object", "required": [ "total", "byStatus", "byAsset" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "byStatus": { "$ref": "#/components/schemas/ReportsCountAndAmountMap" }, "byAsset": { "$ref": "#/components/schemas/ReportsCountAndAmountMap" } } }, "ReportsPaymentLinksSummary": { "type": "object", "required": [ "total", "active", "disabled", "expired", "usedCount" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "disabled": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "usedCount": { "type": "integer", "minimum": 0 } } }, "ReportsTransfersSummary": { "type": "object", "required": [ "total", "payouts", "refunds", "byStatus" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "payouts": { "$ref": "#/components/schemas/ReportsCountAndAmountBucket" }, "refunds": { "$ref": "#/components/schemas/ReportsCountAndAmountBucket" }, "byStatus": { "$ref": "#/components/schemas/ReportsCountAndAmountMap" } } }, "ReportsWebhooksSummary": { "type": "object", "required": [ "total", "delivered", "retrying", "failed", "pending" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "delivered": { "type": "integer", "minimum": 0 }, "retrying": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 } } }, "ReportsBalanceSummary": { "type": "object", "required": [ "assetCode", "type", "balanceMinor" ], "properties": { "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "type": { "type": "string", "example": "project_reconciliation" }, "balanceMinor": { "type": "string", "pattern": "^-?[0-9]+$" } } }, "ReportsSummary": { "type": "object", "required": [ "sandboxOnly", "generatedAt", "projectId", "merchantId", "payments", "paymentLinks", "transfers", "webhooks", "balances" ], "properties": { "sandboxOnly": { "type": "boolean", "description": "Whether this deployment publishes the SANDBOX payment-method catalog (PAYMENT_CATALOG_ENVIRONMENT). Read off the same deployment setting as `mode` on GET /v1/services; it is not a fixed property of the API." }, "generatedAt": { "$ref": "#/components/schemas/IsoDateTime" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "payments": { "$ref": "#/components/schemas/ReportsPaymentsSummary" }, "paymentLinks": { "$ref": "#/components/schemas/ReportsPaymentLinksSummary" }, "transfers": { "$ref": "#/components/schemas/ReportsTransfersSummary" }, "webhooks": { "$ref": "#/components/schemas/ReportsWebhooksSummary" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/ReportsBalanceSummary" } } } }, "CreatePayoutRequest": { "type": "object", "required": [ "amountMinor", "assetCode", "destinationAddress" ], "properties": { "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "destinationAddress": { "type": "string" }, "externalId": { "type": "string" }, "idempotencyKey": { "type": "string" } } }, "CreateRefundRequest": { "type": "object", "required": [ "invoiceId", "amountMinor", "destinationAddress" ], "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkCode": { "type": "string", "example": "TRON" }, "destinationAddress": { "type": "string" }, "externalId": { "type": "string" }, "idempotencyKey": { "type": "string" } } }, "MerchantTransfer": { "type": "object", "required": [ "id", "projectId", "merchantId", "invoiceId", "type", "status", "assetCode", "networkCode", "amountMinor", "networkFeeMinor", "destinationAddress", "externalId", "idempotencyKey", "simulatedTxHash", "ledgerTransactionId", "completedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "invoiceId": { "$ref": "#/components/schemas/NullableString" }, "type": { "type": "string", "enum": [ "payout", "refund" ] }, "status": { "type": "string", "enum": [ "requested", "completed", "failed", "cancelled" ] }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "$ref": "#/components/schemas/NullableString" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "networkFeeMinor": { "$ref": "#/components/schemas/MinorAmount" }, "destinationAddress": { "type": "string" }, "externalId": { "$ref": "#/components/schemas/NullableString" }, "idempotencyKey": { "$ref": "#/components/schemas/NullableString" }, "simulatedTxHash": { "$ref": "#/components/schemas/NullableString" }, "ledgerTransactionId": { "$ref": "#/components/schemas/NullableString" }, "completedAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateMockChainTransactionRequest": { "type": "object", "required": [ "invoiceId", "attemptId", "txHash", "amountMinor", "confirmations" ], "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string" }, "txHash": { "type": "string" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "confirmations": { "type": "integer", "minimum": 0 } } }, "MockChainTransaction": { "type": "object", "additionalProperties": true, "required": [ "id", "invoiceId", "attemptId", "txHash", "amountMinor", "receivedAmountMinor", "confirmations", "attemptStatus" ], "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string" }, "txHash": { "type": "string" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "receivedAmountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "confirmations": { "type": "integer" }, "attemptStatus": { "type": "string", "example": "paid" } } }, "PaymentJobsSummary": { "type": "object", "required": [ "expiredInvoices", "webhookDeliveriesQueued", "webhookDeliveries", "skippedDueToLock" ], "properties": { "expiredInvoices": { "type": "integer", "minimum": 0 }, "webhookDeliveriesQueued": { "type": "integer", "minimum": 0 }, "webhookDeliveries": { "$ref": "#/components/schemas/WebhookDeliverySummary" }, "skippedDueToLock": { "type": "boolean" } } }, "WebhookDeliverySummary": { "type": "object", "required": [ "delivered", "retrying", "failed" ], "properties": { "delivered": { "type": "integer", "minimum": 0 }, "retrying": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } }, "ServiceReference": { "type": "object", "required": [ "mode", "paymentMethods", "invoiceStatuses", "webhookEvents", "transferTypes", "transferStatuses", "staticWalletStatuses", "api", "boundaries" ], "properties": { "mode": { "type": "string", "const": "sandbox" }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "invoiceStatuses": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceStatus" } }, "webhookEvents": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "transferTypes": { "type": "array", "items": { "type": "string", "enum": [ "payout", "refund" ] } }, "transferStatuses": { "type": "array", "items": { "type": "string", "enum": [ "requested", "completed", "failed", "cancelled" ] } }, "api": { "type": "object", "required": [ "requestSignatureHeaders", "webhookSignatureHeaders" ], "properties": { "requestSignatureHeaders": { "type": "array", "items": { "type": "string" }, "example": [ "x-ncp-timestamp", "x-ncp-signature" ] }, "webhookSignatureHeaders": { "type": "array", "items": { "type": "string" }, "example": [ "x-novacrypta-timestamp", "x-novacrypta-signature", "x-novacrypta-delivery-id", "x-novacrypta-event-id" ] } } }, "boundaries": { "type": "object", "required": [ "liveFunds", "custody", "livePayouts", "liveRefunds", "kytAml", "productionSla" ], "properties": { "liveFunds": { "type": "boolean", "const": false }, "custody": { "type": "boolean", "const": false }, "livePayouts": { "type": "boolean", "const": false }, "liveRefunds": { "type": "boolean", "const": false }, "kytAml": { "type": "boolean", "const": false }, "productionSla": { "type": "boolean", "const": false } } }, "staticWalletStatuses": { "type": "array", "items": { "type": "string", "enum": [ "active", "blocked", "archived" ] } } } }, "CreateStaticWalletRequest": { "type": "object", "required": [ "assetCode", "networkCode", "customerRef" ], "properties": { "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "customerRef": { "type": "string", "example": "customer_1001" }, "externalId": { "type": "string", "example": "merchant_wallet_1001" }, "label": { "type": "string", "example": "Customer 1001 USDT top-up wallet" }, "idempotencyKey": { "type": "string", "example": "static-wallet:customer_1001:USDT:TRON" } } }, "StaticWallet": { "type": "object", "required": [ "id", "projectId", "merchantId", "externalId", "customerRef", "label", "assetCode", "networkCode", "address", "adapterMode", "status", "totalReceivedMinor", "lastTopUpAt", "idempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "externalId": { "$ref": "#/components/schemas/NullableString" }, "customerRef": { "type": "string" }, "label": { "$ref": "#/components/schemas/NullableString" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "address": { "type": "string", "example": "sandbox_static_usdt_tron_..." }, "adapterMode": { "type": "string", "enum": [ "mock", "production" ] }, "status": { "type": "string", "enum": [ "active", "blocked", "archived" ] }, "totalReceivedMinor": { "$ref": "#/components/schemas/MinorAmount" }, "lastTopUpAt": { "$ref": "#/components/schemas/NullableIsoDateTime" }, "idempotencyKey": { "$ref": "#/components/schemas/NullableString" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } }, "CreateStaticWalletTopUpRequest": { "type": "object", "required": [ "walletId", "txHash", "amountMinor", "confirmations" ], "properties": { "walletId": { "type": "string" }, "txHash": { "type": "string", "description": "Sandbox transaction hash. Replaying the same walletId and txHash with the same amount returns the existing top-up; a different amount is rejected.", "example": "sandbox_static_wallet_tx_1001" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "confirmations": { "type": "integer", "minimum": 0 } } }, "StaticWalletTopUp": { "type": "object", "required": [ "id", "walletId", "projectId", "merchantId", "assetCode", "networkCode", "txHash", "amountMinor", "confirmations", "status", "ledgerTransactionId", "webhookDeliveriesQueued", "completedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "walletId": { "type": "string" }, "projectId": { "type": "string" }, "merchantId": { "type": "string" }, "assetCode": { "$ref": "#/components/schemas/AssetCode" }, "networkCode": { "type": "string", "example": "TRON" }, "txHash": { "type": "string" }, "amountMinor": { "$ref": "#/components/schemas/MinorAmount" }, "confirmations": { "type": "integer" }, "status": { "type": "string", "const": "completed" }, "ledgerTransactionId": { "$ref": "#/components/schemas/NullableString" }, "webhookDeliveriesQueued": { "type": "integer", "minimum": 0, "description": "Number of webhook deliveries queued for this call. Idempotent replay of an existing top-up returns 0." }, "completedAt": { "$ref": "#/components/schemas/IsoDateTime" }, "createdAt": { "$ref": "#/components/schemas/IsoDateTime" }, "updatedAt": { "$ref": "#/components/schemas/IsoDateTime" } } } } } }