{"openapi":"3.1.0","info":{"title":"Payvenax API","version":"1.0.0","description":"OpenAPI contract for public payment creation/status APIs and merchant operations."},"servers":[{"url":"https://testnet-api.payvenax.com/api/v1","description":"Versioned API"}],"tags":[{"name":"Authentication"},{"name":"Public Payments"},{"name":"Merchant Payments"},{"name":"Ledger"},{"name":"Settlements"},{"name":"Webhooks"},{"name":"Health"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"OpsEndpointBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ops-token","description":"Required for operational endpoints when OPS_ENDPOINTS_AUTH_TOKEN is configured."},"OpsEndpointHeaderAuth":{"type":"apiKey","in":"header","name":"x-ops-token","description":"Alternative ops endpoint token header for probes that cannot send bearer auth."}},"schemas":{"BalanceSummary":{"type":"object","properties":{"grossPaid":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"available":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"availableBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"pendingBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedForPayouts":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"feeBreakdown":{"type":"object","properties":{"collectionFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"payoutFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"platformFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"unclassifiedFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."}}},"totalFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalPaidOut":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}},"Checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"CheckoutSessionResponse":{"type":"object","properties":{"message":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["AWAITING_SELECTION","QUOTED","FINALIZED","EXPIRED"]},"availableOptions":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"displayName":{"type":"string","example":"USDT / TRC20"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}}},"paymentId":{"type":"string","format":"uuid","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"finalizedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"payment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}},"errorId":{"type":"string"},"requestId":{"type":"string","nullable":true}}},"FinalizeQuoteResponse":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"LedgerEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"entryType":{"type":"string","example":"PAYMENT_CREDIT"},"direction":{"type":"string","enum":["CREDIT","DEBIT"]},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceType":{"type":"string","example":"payment"},"sourceId":{"type":"string"},"auditLogId":{"type":"string","nullable":true},"grossPaidAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"pendingBalanceAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedForPayoutsAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalFeesAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalPaidOutAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"availableAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"metadata":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"MerchantOnboardingChecklist":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"KYB_APPROVED"},"action":{"nullable":true,"type":"object","properties":{"href":{"type":"string"},"label":{"type":"string"}}},"blocking":{"type":"boolean"},"category":{"type":"string","enum":["ADMIN_REVIEW","RECOMMENDED","REQUIRED_ACTION","SYSTEM_CHECK"]},"details":{"type":"object"},"message":{"type":"string"},"owner":{"type":"string","enum":["ADMIN","MERCHANT","SYSTEM"]},"recommended":{"type":"boolean"},"severity":{"type":"string","enum":["BLOCKING","INFO","RECOMMENDED","REQUIRED"]},"status":{"type":"string","enum":["FAIL","PASS","WARN"]},"visibleToMerchant":{"type":"boolean"}}}},"generatedAt":{"type":"string","format":"date-time"},"merchant":{"type":"object","properties":{"callbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"webhookSecretConfigured":{"type":"boolean"},"webhookSecretPreview":{"type":"string","nullable":true},"webhookNextSecretConfigured":{"type":"boolean"},"webhookNextSecretPreview":{"type":"string","nullable":true},"webhookNextSecretActivatesAt":{"type":"string","format":"date-time","nullable":true}}},"overallStatus":{"type":"string","enum":["BLOCKED","READY","REVIEW_REQUIRED"]},"summary":{"type":"object","properties":{"fail":{"type":"integer"},"pass":{"type":"integer"},"total":{"type":"integer"},"warn":{"type":"integer"}}}}},"MerchantOpsSummary":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"webhooks":{"type":"object","properties":{"deadLetter":{"type":"integer"},"dueRetries":{"type":"integer"},"failed":{"type":"integer"},"latestDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","example":"payment.paid"},"url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"requestId":{"type":"string","nullable":true},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"requestId":{"type":"string","nullable":true},"responseBodyPreview":{"type":"string","nullable":true},"responseHeaders":{"type":"object"}}},"retry":{"type":"object","properties":{"canRetry":{"type":"boolean"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"}}},"pending":{"type":"integer"},"statuses":{"type":"object"},"successful":{"type":"integer"},"total":{"type":"integer"}}}}},"MessageResponse":{"type":"object","properties":{"message":{"type":"string"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"PaymentQuoteResponse":{"type":"object","properties":{"message":{"type":"string"},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"PasswordResetCompletionRequest":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string"},"password":{"type":"string","format":"password","minLength":10,"description":"Must satisfy the merchant password policy."}}},"PasswordResetRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}},"PasswordResetRequestResponse":{"type":"object","properties":{"message":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","description":"Returned for accepted reset requests without revealing whether the account exists."}}},"PublicPaymentResponse":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"checkoutUrl":{"type":"string","format":"uri","deprecated":true,"description":"Backward-compatible alias for checkout.url."},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}}},"PayoutRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"ARBITRUM"},"walletAddress":{"type":"string"},"note":{"type":"string","nullable":true},"status":{"type":"string","example":"PENDING"},"createdAt":{"type":"string","format":"date-time"}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","example":"payment.paid"},"url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"requestId":{"type":"string","nullable":true},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"requestId":{"type":"string","nullable":true},"responseBodyPreview":{"type":"string","nullable":true},"responseHeaders":{"type":"object"}}},"retry":{"type":"object","properties":{"canRetry":{"type":"boolean"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/health/live":{"get":{"tags":["Health"],"summary":"Liveness check","responses":{"200":{"description":"Service is live"}}}},"/auth/forgot-password":{"post":{"tags":["Authentication"],"summary":"Request merchant password reset instructions","description":"Always returns a generic success message for valid email-shaped requests to avoid account enumeration.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Password reset request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","description":"Returned for accepted reset requests without revealing whether the account exists."}}}}}},"400":{"description":"Email is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}},"errorId":{"type":"string"},"requestId":{"type":"string","nullable":true}}}}}},"429":{"description":"Too many password reset requests"}}}},"/auth/reset-password":{"post":{"tags":["Authentication"],"summary":"Complete a merchant password reset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string"},"password":{"type":"string","format":"password","minLength":10,"description":"Must satisfy the merchant password policy."}}}}}},"responses":{"200":{"description":"Password reset completed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"description":"Invalid token, expired token, or password policy failure","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}},"errorId":{"type":"string"},"requestId":{"type":"string","nullable":true}}}}}},"429":{"description":"Too many password reset attempts"}}}},"/health/ready":{"get":{"tags":["Health"],"summary":"Readiness check","description":"Operational readiness probe. Production deployments require an ops endpoint token.","security":[{"OpsEndpointBearerAuth":[]},{"OpsEndpointHeaderAuth":[]}],"responses":{"200":{"description":"Service is ready"},"401":{"description":"Ops endpoint authentication required"},"503":{"description":"Service is not ready"}}}},"/public/payments/create":{"post":{"tags":["Public Payments"],"summary":"Create a checkout payment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"default":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"default":"TRC20","description":"Payment asset network. Supported pairs are USDT/TRC20, USDT/ERC20, USDC/ERC20, USDT/BEP20, ETH/BEP20, USDT/ARBITRUM, USDC/ARBITRUM, ETH/ARBITRUM, USDT/BASE, USDC/BASE, TRX/TRON, ETH/ERC20, ETH/BASE, BNB/BEP20, ARB/ARBITRUM, SOL/SOLANA, and USDC/SOLANA. ERC20 verification requires backend Ethereum RPC configuration; BEP20 verification requires backend BSC RPC configuration; ARBITRUM verification requires backend Arbitrum RPC configuration; BASE verification requires backend Base RPC configuration; SOLANA verification requires backend Solana RPC configuration."},"orderId":{"type":"string","maxLength":80},"customerEmail":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Payment created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"checkoutUrl":{"type":"string","format":"uri","deprecated":true,"description":"Backward-compatible alias for checkout.url."},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid payment request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"API key scope denied"},"409":{"description":"Duplicate order or idempotency conflict"}}}},"/public/payments/{paymentId}":{"get":{"tags":["Public Payments"],"summary":"Get hosted checkout payment details","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment details","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"checkoutUrl":{"type":"string","format":"uri","deprecated":true,"description":"Backward-compatible alias for checkout.url."},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Payment not found"}}}},"/public/checkout-sessions":{"post":{"tags":["Public Payments"],"summary":"Create a fiat checkout session","description":"Creates a fiat-denominated checkout session without creating a blockchain payment. A payment is created only after a locked quote is finalized.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","sourceCurrency"],"properties":{"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"orderId":{"type":"string","maxLength":80},"customerEmail":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["AWAITING_SELECTION","QUOTED","FINALIZED","EXPIRED"]},"availableOptions":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"displayName":{"type":"string","example":"USDT / TRC20"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}}},"paymentId":{"type":"string","format":"uuid","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"finalizedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"payment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}}}},"400":{"description":"Invalid checkout session request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"API key scope denied"},"409":{"description":"Duplicate order"}}}},"/public/checkout-sessions/{sessionId}":{"get":{"tags":["Public Payments"],"summary":"Get fiat checkout session details","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Checkout session details","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"status":{"type":"string","enum":["AWAITING_SELECTION","QUOTED","FINALIZED","EXPIRED"]},"availableOptions":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"displayName":{"type":"string","example":"USDT / TRC20"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}}},"paymentId":{"type":"string","format":"uuid","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"finalizedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"payment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}}}},"404":{"description":"Checkout session not found"}}}},"/public/checkout-sessions/{sessionId}/quotes":{"post":{"tags":["Public Payments"],"summary":"Create a locked payment quote","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currency","network"],"properties":{"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}}}}},"responses":{"201":{"description":"Payment quote created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Missing asset/network selection"},"409":{"description":"Unsupported asset/network or finalized session"},"410":{"description":"Checkout session expired"},"503":{"description":"Quote rate provider unavailable"}}}},"/public/checkout-sessions/{sessionId}/finalize":{"post":{"tags":["Public Payments"],"summary":"Finalize a locked quote into a payment","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quoteId"],"properties":{"quoteId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Payment created from quote","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"sourceAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceCurrency":{"type":"string","enum":["TRY","USD","EUR","GBP"]},"targetCurrency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"targetNetwork":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"exchangeRate":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"targetAmount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"rateProvider":{"type":"string","example":"coingecko"},"rateSource":{"type":"string","enum":["live"]},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"]},"lockedUntil":{"type":"string","format":"date-time"},"consumedAt":{"type":"string","format":"date-time","nullable":true},"paymentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Missing quote id"},"404":{"description":"Quote not found"},"409":{"description":"Quote already consumed or session finalized"},"410":{"description":"Quote or checkout session expired"}}}},"/public/payments/status/{paymentId}":{"get":{"tags":["Public Payments"],"summary":"Get payment status by payment id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment status","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"checkoutUrl":{"type":"string","format":"uri","deprecated":true,"description":"Backward-compatible alias for checkout.url."},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Payment not found"}}}},"/public/payments/status":{"get":{"tags":["Public Payments"],"summary":"Get payment status by order id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"orderId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payment status","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"checkout":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"paymentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"}}},"checkoutUrl":{"type":"string","format":"uri","deprecated":true,"description":"Backward-compatible alias for checkout.url."},"payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Payment not found"}}}},"/payments":{"get":{"tags":["Merchant Payments"],"summary":"List merchant payments","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"webhookStatus","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant payments","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}}},"totalCount":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}},"/payments/{paymentId}":{"get":{"tags":["Merchant Payments"],"summary":"Get merchant payment detail","security":[{"BearerAuth":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment details","content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"mode":{"type":"string","enum":["LIVE","TEST"],"example":"LIVE"},"orderId":{"type":"string","nullable":true},"customerEmail":{"type":"string","nullable":true},"walletAddress":{"type":"string","example":"T..."},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","UNDERPAID","EXPIRED_PAID_REVIEW"]},"txHash":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"webhookEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","example":"payment.paid"},"url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"requestId":{"type":"string","nullable":true},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"requestId":{"type":"string","nullable":true},"responseBodyPreview":{"type":"string","nullable":true},"responseHeaders":{"type":"object"}}},"retry":{"type":"object","properties":{"canRetry":{"type":"boolean"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"}}}},"timeline":{"type":"array","items":{"type":"object"}}}}]}}}}}},"404":{"description":"Payment not found"}}}},"/merchant/ledger":{"get":{"tags":["Ledger"],"summary":"List immutable ledger entries","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"entryType","in":"query","schema":{"type":"string"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["ALL","CREDIT","DEBIT"]}},{"name":"sourceType","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Ledger entries","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"entryType":{"type":"string","example":"PAYMENT_CREDIT"},"direction":{"type":"string","enum":["CREDIT","DEBIT"]},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"sourceType":{"type":"string","example":"payment"},"sourceId":{"type":"string"},"auditLogId":{"type":"string","nullable":true},"grossPaidAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"pendingBalanceAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedForPayoutsAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalFeesAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalPaidOutAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"availableAfter":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"metadata":{"type":"object","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"totalCount":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}},"/merchant/settlements":{"get":{"tags":["Settlements"],"summary":"Get merchant balance and payout overview","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Settlement overview","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"grossPaid":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"available":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"availableBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"pendingBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedBalance":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"reservedForPayouts":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"feeBreakdown":{"type":"object","properties":{"collectionFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"},"payoutFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"platformFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"unclassifiedFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."}}},"totalFees":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"totalPaidOut":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"TRC20"}}},"payoutRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"ARBITRUM"},"walletAddress":{"type":"string"},"note":{"type":"string","nullable":true},"status":{"type":"string","example":"PENDING"},"createdAt":{"type":"string","format":"date-time"}}}},"payoutLimits":{"type":"object"}}}}}}}}},"/merchant/payout-requests":{"post":{"tags":["Settlements"],"summary":"Create payout request","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","walletAddress"],"properties":{"amount":{"type":"string","example":"25.5","description":"Decimal money value serialized as a string to avoid precision loss."},"currency":{"type":"string","enum":["USDT","USDC","TRX","ETH","BNB","SOL","ARB"],"example":"USDT"},"network":{"type":"string","enum":["TRC20","TRON","ERC20","BEP20","ARBITRUM","BASE","SOLANA"],"example":"ARBITRUM"},"walletAddress":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"201":{"description":"Payout request created"},"400":{"description":"Invalid payout request"},"409":{"description":"Balance, limit, or whitelist conflict"}}}},"/merchant/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook delivery events","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Webhook events","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","example":"payment.paid"},"url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"requestId":{"type":"string","nullable":true},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"requestId":{"type":"string","nullable":true},"responseBodyPreview":{"type":"string","nullable":true},"responseHeaders":{"type":"object"}}},"retry":{"type":"object","properties":{"canRetry":{"type":"boolean"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"/merchant/ops-summary":{"get":{"tags":["Webhooks"],"summary":"Get merchant operations summary","description":"Returns only webhook delivery status and retry signals scoped to the authenticated merchant.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Merchant operations summary","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"summary":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"webhooks":{"type":"object","properties":{"deadLetter":{"type":"integer"},"dueRetries":{"type":"integer"},"failed":{"type":"integer"},"latestDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","example":"payment.paid"},"url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["PENDING","SUCCESS","FAILED"]},"attempts":{"type":"integer"},"maxAttempts":{"type":"integer"},"requestId":{"type":"string","nullable":true},"lastStatusCode":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"requestId":{"type":"string","nullable":true},"responseBodyPreview":{"type":"string","nullable":true},"responseHeaders":{"type":"object"}}},"retry":{"type":"object","properties":{"canRetry":{"type":"boolean"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"}}},"pending":{"type":"integer"},"statuses":{"type":"object"},"successful":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}}}}},"/merchant/onboarding/checklist":{"get":{"tags":["Merchant Payments"],"summary":"Get authenticated merchant onboarding checklist","description":"Returns the pilot go-live readiness checks for the authenticated merchant, including KYB, legal, API, webhook, payout, risk, balance, and sandbox signals.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Merchant onboarding checklist","content":{"application/json":{"schema":{"type":"object","properties":{"checklist":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"KYB_APPROVED"},"action":{"nullable":true,"type":"object","properties":{"href":{"type":"string"},"label":{"type":"string"}}},"blocking":{"type":"boolean"},"category":{"type":"string","enum":["ADMIN_REVIEW","RECOMMENDED","REQUIRED_ACTION","SYSTEM_CHECK"]},"details":{"type":"object"},"message":{"type":"string"},"owner":{"type":"string","enum":["ADMIN","MERCHANT","SYSTEM"]},"recommended":{"type":"boolean"},"severity":{"type":"string","enum":["BLOCKING","INFO","RECOMMENDED","REQUIRED"]},"status":{"type":"string","enum":["FAIL","PASS","WARN"]},"visibleToMerchant":{"type":"boolean"}}}},"generatedAt":{"type":"string","format":"date-time"},"merchant":{"type":"object","properties":{"callbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"webhookSecretConfigured":{"type":"boolean"},"webhookSecretPreview":{"type":"string","nullable":true},"webhookNextSecretConfigured":{"type":"boolean"},"webhookNextSecretPreview":{"type":"string","nullable":true},"webhookNextSecretActivatesAt":{"type":"string","format":"date-time","nullable":true}}},"overallStatus":{"type":"string","enum":["BLOCKED","READY","REVIEW_REQUIRED"]},"summary":{"type":"object","properties":{"fail":{"type":"integer"},"pass":{"type":"integer"},"total":{"type":"integer"},"warn":{"type":"integer"}}}}},"message":{"type":"string"}}}}}},"401":{"description":"Missing or invalid merchant session"},"404":{"description":"Merchant not found"}}}},"/payments/{paymentId}/webhooks/{webhookId}/retry":{"post":{"tags":["Webhooks"],"summary":"Retry a failed or pending webhook delivery","security":[{"BearerAuth":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook retry attempted"},"400":{"description":"Retry is not allowed"},"404":{"description":"Webhook not found"}}}}}}