{"openapi":"3.0.0","paths":{"/api/v1/admin/fees/rules":{"get":{"operationId":"AdminFeesController_listRules","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Fee rules fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Fees"]},"post":{"operationId":"AdminFeesController_createRule","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeeRuleDto"}}}},"responses":{"201":{"description":"Fee rule created successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Fees"]}},"/api/v1/admin/fees/quote":{"post":{"operationId":"AdminFeesController_quote","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeQuoteDto"}}}},"responses":{"200":{"description":"Fee quote calculated successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Fees"]}},"/api/v1/merchants/me/api-keys":{"get":{"operationId":"MerchantsController_listOwnApiKeys","parameters":[],"responses":{"200":{"description":"Merchant API keys listed successfully.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchants"]},"post":{"operationId":"MerchantsController_createOwnApiKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyDto"}}}},"responses":{"201":{"description":"Merchant API key created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchants"]}},"/api/v1/merchants/me/api-keys/{apiKeyId}/revoke":{"post":{"operationId":"MerchantsController_revokeOwnApiKey","parameters":[{"name":"apiKeyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeMerchantApiKeyDto"}}}},"responses":{"201":{"description":"Merchant API key revoked successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchants"]}},"/api/v1/merchants":{"post":{"operationId":"MerchantsController_createMerchant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantDto"}}}},"responses":{"201":{"description":"Merchant created successfully.","content":{"application/json":{"schema":{"type":"object","required":["publicId","code","name","status","createdAt","updatedAt"],"properties":{"publicId":{"type":"string","example":"mrc_123"},"code":{"type":"string","example":"merchant_store"},"name":{"type":"string","example":"Merchant Store"},"legalName":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"planCode":{"type":"string","nullable":true},"metadataJson":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Merchants"]}},"/api/v1/merchants/{merchantId}/api-keys":{"post":{"operationId":"MerchantsController_createApiKey","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyDto"}}}},"responses":{"201":{"description":"Merchant API key created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Merchants"]}},"/api/v1/merchants/{merchantId}/api-keys/rotate":{"post":{"operationId":"MerchantsController_rotateApiKey","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyDto"}}}},"responses":{"201":{"description":"Merchant API key rotated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Merchants"]}},"/api/v1/merchants/api-keys/{apiKeyId}/revoke":{"post":{"operationId":"MerchantsController_revokeApiKey","parameters":[{"name":"apiKeyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeMerchantApiKeyDto"}}}},"responses":{"201":{"description":"Merchant API key revoked successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","name","keyPrefix","scopes","fullAccess","lastUsedAt","expiresAt","revokedAt","createdAt"],"properties":{"id":{"type":"string","example":"mk_live_123"},"name":{"type":"string","example":"Production integration"},"keyPrefix":{"type":"string","example":"zpk_live_abc"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"example":["invoice:read","invoice:write"]},"fullAccess":{"type":"boolean","example":false},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"plaintext":{"type":"string","writeOnly":true,"description":"Returned once at creation and never returned again.","example":"zpk_live_secret_returned_once"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Merchants"]}},"/api/v1/payments/methods":{"get":{"operationId":"PaymentsController_listMethods","parameters":[],"responses":{"200":{"description":"Enabled payment methods listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]}},"/api/v1/payments":{"get":{"operationId":"PaymentsController_listPayments","parameters":[{"name":"search","required":false,"in":"query","description":"Search merchant-scoped payment, invoice reference, TXID or receiving address.","schema":{"maxLength":120,"type":"string"}},{"name":"invoiceId","required":false,"in":"query","schema":{"example":"invoice-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentStatus"}},{"name":"methodType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentMethodType"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USD","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"providerCode","required":false,"in":"query","schema":{"example":"native_tron","type":"string"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include sandbox provider records explicitly. Live merchant history excludes them by default.","schema":{"default":false,"type":"boolean"}},{"name":"createdFrom","required":false,"in":"query","schema":{"example":"2026-05-01T00:00:00.000Z","type":"string"}},{"name":"createdTo","required":false,"in":"query","schema":{"example":"2026-05-06T23:59:59.999Z","type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the previous page.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":50,"type":"number"}}],"responses":{"200":{"description":"Merchant payment history fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":1},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]},"post":{"operationId":"PaymentsController_registerPayment","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPaymentDto"}}}},"responses":{"201":{"description":"Payment registered successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]}},"/api/v1/payments/export":{"get":{"operationId":"PaymentsController_exportPayments","parameters":[{"name":"search","required":false,"in":"query","description":"Search merchant-scoped payment, invoice reference, TXID or receiving address.","schema":{"maxLength":120,"type":"string"}},{"name":"invoiceId","required":false,"in":"query","schema":{"example":"invoice-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentStatus"}},{"name":"methodType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentMethodType"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USD","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"providerCode","required":false,"in":"query","schema":{"example":"native_tron","type":"string"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include sandbox provider records explicitly. Live merchant history excludes them by default.","schema":{"default":false,"type":"boolean"}},{"name":"createdFrom","required":false,"in":"query","schema":{"example":"2026-05-01T00:00:00.000Z","type":"string"}},{"name":"createdTo","required":false,"in":"query","schema":{"example":"2026-05-06T23:59:59.999Z","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":5000,"default":5000,"example":5000,"type":"number"}}],"responses":{"200":{"description":"A bounded merchant payment history CSV export with sensitive fields excluded.","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]}},"/api/v1/payments/{id}/detail":{"get":{"operationId":"PaymentsController_getPaymentDetail","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant payment detail, lifecycle timeline and related records fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"invoice":{"type":"object","nullable":true,"description":"Merchant-scoped invoice projection. Includes remaining/overpaid amounts and gatewayStatus for payment exceptions.","additionalProperties":true,"properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"amountExpected":{"type":"string"},"amountReceived":{"type":"string"},"amountRemaining":{"type":"string"},"amountOverpaid":{"type":"string"},"gatewayStatus":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string"},"label":{"type":"string"},"isFinal":{"type":"boolean"},"detail":{"type":"string"}}}}},"cryptoTransaction":{"type":"object","nullable":true,"additionalProperties":true},"refund":{"type":"object","nullable":true,"additionalProperties":true},"dispute":{"type":"object","nullable":true,"additionalProperties":true},"settlement":{"type":"object","nullable":true,"additionalProperties":true},"audit":{"type":"array","items":{"type":"object","additionalProperties":true}},"webhookEvents":{"type":"array","items":{"type":"object","additionalProperties":true}},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]}},"/api/v1/payments/{id}":{"get":{"operationId":"PaymentsController_getPayment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant payment fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Payments"]}},"/api/v1/payments/{id}/status":{"post":{"operationId":"PaymentsAdminController_transitionStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionPaymentStatusDto"}}}},"responses":{"200":{"description":"Payment status updated successfully."}},"security":[{"adminToken":[]}],"tags":["Payments Admin"]}},"/api/v1/ledger/entries":{"get":{"operationId":"LedgerController_listEntries","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"sourceId","required":false,"in":"query","description":"Restrict results to entries generated by one payment or source.","schema":{"example":"payment-public-id","type":"string"}},{"name":"direction","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryDirection"}},{"name":"type","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryType"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryStatus"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"Merchant ledger entries listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","direction","type","status","sourceType","sourceId","currency","amount","postedAt","createdAt"],"properties":{"id":{"type":"string","example":"led_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Merchant Store"},"direction":{"type":"string","example":"credit"},"type":{"type":"string","example":"payment_credit"},"status":{"type":"string","example":"posted"},"sourceType":{"type":"string","example":"payment"},"sourceId":{"type":"string","example":"pay_123"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"9.75"},"description":{"type":"string","nullable":true},"postedAt":{"type":"string","format":"date-time"},"voidedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Ledger"]}},"/api/v1/ledger/balances":{"get":{"operationId":"LedgerController_getBalances","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}}],"responses":{"200":{"description":"Merchant ledger balances fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["merchantId","merchant","currency","credits","debits","available"],"properties":{"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Merchant Store"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"credits":{"type":"string","example":"100.00"},"debits":{"type":"string","example":"10.00"},"available":{"type":"string","example":"90.00"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Ledger"]}},"/api/v1/admin/ledger/entries":{"get":{"operationId":"LedgerAdminController_listEntries","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"sourceId","required":false,"in":"query","description":"Restrict results to entries generated by one payment or source.","schema":{"example":"payment-public-id","type":"string"}},{"name":"direction","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryDirection"}},{"name":"type","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryType"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/LedgerEntryStatus"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"Ledger entries listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","direction","type","status","sourceType","sourceId","currency","amount","postedAt","createdAt"],"properties":{"id":{"type":"string","example":"led_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Merchant Store"},"direction":{"type":"string","example":"credit"},"type":{"type":"string","example":"payment_credit"},"status":{"type":"string","example":"posted"},"sourceType":{"type":"string","example":"payment"},"sourceId":{"type":"string","example":"pay_123"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"9.75"},"description":{"type":"string","nullable":true},"postedAt":{"type":"string","format":"date-time"},"voidedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Ledger Admin"]}},"/api/v1/admin/ledger/balances":{"get":{"operationId":"LedgerAdminController_getBalances","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}}],"responses":{"200":{"description":"Ledger balances fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["merchantId","merchant","currency","credits","debits","available"],"properties":{"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Merchant Store"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"credits":{"type":"string","example":"100.00"},"debits":{"type":"string","example":"10.00"},"available":{"type":"string","example":"90.00"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Ledger Admin"]}},"/api/v1/admin/ledger/reconciliation":{"get":{"operationId":"LedgerAdminController_reconcileLedger","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":2000,"example":500,"type":"number"}}],"responses":{"200":{"description":"Ledger reconciliation report fetched."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Ledger Admin"]}},"/api/v1/admin/ledger/backfill":{"post":{"operationId":"LedgerAdminController_backfillLedger","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackfillLedgerDto"}}}},"responses":{"201":{"description":"Ledger backfill scan executed."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Ledger Admin"]}},"/api/v1/wallets/balances":{"get":{"operationId":"BusinessWalletController_getBalances","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}}],"responses":{"200":{"description":"Business wallet balances fetched successfully."}},"security":[{"merchantApiKey":[]}],"summary":"Return merchant business wallet balances backed by posted ledger entries","tags":["Business Wallet"]}},"/api/v1/admin/webhooks/merchants/{merchantId}/endpoint":{"post":{"operationId":"WebhooksController_configureWebhookEndpoint","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureWebhookEndpointDto"}}}},"responses":{"201":{"description":"Webhook endpoint configured."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/endpoints":{"get":{"operationId":"WebhooksController_listEndpoints","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across endpoint id, URL and description.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook endpoints fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/endpoints/page":{"get":{"operationId":"WebhooksController_listEndpointPage","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across endpoint id, URL and description.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook endpoints fetched with pagination.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":3},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/event-types":{"get":{"operationId":"WebhooksController_listEventTypes","parameters":[],"responses":{"200":{"description":"Supported merchant webhook event types."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/endpoints/{id}/status":{"post":{"operationId":"WebhooksController_updateEndpointStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointStatusDto"}}}},"responses":{"200":{"description":"Webhook endpoint status updated."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/endpoints/{id}/rotate-secret":{"post":{"operationId":"WebhooksController_rotateEndpointSecret","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateWebhookEndpointSecretDto"}}}},"responses":{"201":{"description":"Webhook endpoint secret rotated."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/test":{"post":{"operationId":"WebhooksController_testWebhook","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDto"}}}},"responses":{"201":{"description":"Test webhook delivery queued."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/deliveries":{"get":{"operationId":"WebhooksController_listDeliveries","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}},{"name":"eventType","required":false,"in":"query","schema":{"example":"invoice.status.changed","type":"string"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across delivery id, event and persisted resource references.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook deliveries fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/deliveries/page":{"get":{"operationId":"WebhooksController_listDeliveryPage","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}},{"name":"eventType","required":false,"in":"query","schema":{"example":"invoice.status.changed","type":"string"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across delivery id, event and persisted resource references.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook deliveries fetched with pagination.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","merchantId","endpointId","eventType","signaturePresent","status","attemptCount","maxAttempts","createdAt"],"properties":{"id":{"type":"string","example":"whdel_123"},"merchantId":{"type":"string"},"merchant":{"type":"string"},"endpointId":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"endpointActive":{"type":"boolean"},"eventType":{"type":"string","example":"invoice.status.changed"},"resourceId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"signaturePresent":{"type":"boolean"},"status":{"type":"string","example":"delivered"},"attemptCount":{"type":"integer","example":1},"maxAttempts":{"type":"integer","example":8},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"nextAttemptAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":3},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/admin/webhooks/deliveries/{id}/resend":{"post":{"operationId":"WebhooksController_resendDelivery","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Webhook delivery replay queued."}},"security":[{"adminToken":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/endpoints":{"post":{"operationId":"MerchantWebhooksController_configureWebhookEndpoint","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureWebhookEndpointDto"}}}},"responses":{"201":{"description":"Webhook endpoint configured.","content":{"application/json":{"schema":{"type":"object","required":["endpoint","signingSecret"],"properties":{"endpoint":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when the endpoint is configured."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]},"get":{"operationId":"MerchantWebhooksController_listEndpoints","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across endpoint id, URL and description.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook endpoints fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/endpoints/page":{"get":{"operationId":"MerchantWebhooksController_listEndpointPage","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across endpoint id, URL and description.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Merchant webhook endpoints fetched with pagination.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":3},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/event-types":{"get":{"operationId":"MerchantWebhooksController_listEventTypes","parameters":[],"responses":{"200":{"description":"Supported merchant webhook event types.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["key","type"],"properties":{"key":{"type":"string"},"type":{"type":"string"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/endpoints/{id}/status":{"post":{"operationId":"MerchantWebhooksController_updateEndpointStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointStatusDto"}}}},"responses":{"200":{"description":"Webhook endpoint status updated.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/endpoints/{id}/rotate-secret":{"post":{"operationId":"MerchantWebhooksController_rotateEndpointSecret","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateWebhookEndpointSecretDto"}}}},"responses":{"201":{"description":"Webhook endpoint secret rotated.","content":{"application/json":{"schema":{"type":"object","required":["endpoint","signingSecret"],"properties":{"endpoint":{"type":"object","required":["id","merchantId","url","isActive","subscribedEvents","receivesAllEvents","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"wh_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string"},"merchantCode":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"receivesAllEvents":{"type":"boolean"},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when configured or rotated."}}},"signingSecret":{"type":"string","writeOnly":true,"description":"Returned once when the endpoint secret is rotated."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/test":{"post":{"operationId":"MerchantWebhooksController_testWebhook","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantWebhookTestDto"}}}},"responses":{"201":{"description":"Test webhook delivery queued.","content":{"application/json":{"schema":{"type":"object","required":["queued","deliveryPublicId"],"properties":{"queued":{"type":"boolean","example":true},"deliveryPublicId":{"type":"string","example":"whdel_123"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/deliveries":{"get":{"operationId":"MerchantWebhooksController_listDeliveries","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}},{"name":"eventType","required":false,"in":"query","schema":{"example":"invoice.status.changed","type":"string"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across delivery id, event and persisted resource references.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Webhook deliveries fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","endpointId","eventType","signaturePresent","status","attemptCount","maxAttempts","createdAt"],"properties":{"id":{"type":"string","example":"whdel_123"},"merchantId":{"type":"string"},"merchant":{"type":"string"},"endpointId":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"endpointActive":{"type":"boolean"},"eventType":{"type":"string","example":"invoice.status.changed"},"resourceId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"signaturePresent":{"type":"boolean"},"status":{"type":"string","example":"delivered"},"attemptCount":{"type":"integer","example":1},"maxAttempts":{"type":"integer","example":8},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"nextAttemptAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/deliveries/page":{"get":{"operationId":"MerchantWebhooksController_listDeliveryPage","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}},{"name":"eventType","required":false,"in":"query","schema":{"example":"invoice.status.changed","type":"string"}},{"name":"search","required":false,"in":"query","description":"Merchant-scoped search across delivery id, event and persisted resource references.","schema":{"maxLength":120,"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the paginated endpoint.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Merchant webhook deliveries fetched with pagination.","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","merchantId","endpointId","eventType","signaturePresent","status","attemptCount","maxAttempts","createdAt"],"properties":{"id":{"type":"string","example":"whdel_123"},"merchantId":{"type":"string"},"merchant":{"type":"string"},"endpointId":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"endpointActive":{"type":"boolean"},"eventType":{"type":"string","example":"invoice.status.changed"},"resourceId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"signaturePresent":{"type":"boolean"},"status":{"type":"string","example":"delivered"},"attemptCount":{"type":"integer","example":1},"maxAttempts":{"type":"integer","example":8},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"nextAttemptAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":3},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/webhooks/deliveries/{id}/resend":{"post":{"operationId":"MerchantWebhooksController_resendDelivery","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Webhook delivery replay queued.","content":{"application/json":{"schema":{"type":"object","required":["queued","originalDeliveryId","deliveryPublicId","targetUrl","eventType"],"properties":{"queued":{"type":"boolean","example":true},"originalDeliveryId":{"type":"string"},"deliveryPublicId":{"type":"string"},"targetUrl":{"type":"string","format":"uri"},"eventType":{"type":"string"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Webhooks"]}},"/api/v1/refunds":{"get":{"operationId":"RefundsController_listRefunds","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"paymentId","required":false,"in":"query","schema":{"example":"payment-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/RefundStatus"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include refunds linked to sandbox provider records explicitly.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Refunds listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Refunds"]},"post":{"operationId":"RefundsController_createRefund","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundDto"}}}},"responses":{"201":{"description":"Refund requested successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Refunds"]}},"/api/v1/refunds/{id}":{"get":{"operationId":"RefundsController_getRefund","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Refund detail returned successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Refunds"]}},"/api/v1/admin/refunds":{"get":{"operationId":"RefundsAdminController_listRefunds","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"paymentId","required":false,"in":"query","schema":{"example":"payment-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/RefundStatus"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include refunds linked to sandbox provider records explicitly.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Refunds listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Refunds Admin"]}},"/api/v1/admin/refunds/{id}":{"get":{"operationId":"RefundsAdminController_getRefund","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Refund detail returned successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Refunds Admin"]}},"/api/v1/admin/refunds/{id}/status":{"post":{"operationId":"RefundsAdminController_transitionStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRefundStatusDto"}}}},"responses":{"200":{"description":"Refund status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","requestedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"ref_123"},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerRefundId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"requested"},"reason":{"type":"string","nullable":true},"destinationAddress":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"type":"string","format":"date-time","nullable":true},"processedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Refunds Admin"]}},"/api/v1/disputes":{"get":{"operationId":"DisputesController_listDisputes","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"paymentId","required":false,"in":"query","schema":{"example":"payment-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/DisputeStatus"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include disputes linked to sandbox provider records explicitly.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Disputes listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Disputes"]}},"/api/v1/disputes/{id}":{"get":{"operationId":"DisputesController_getDispute","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Dispute detail returned successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Disputes"]}},"/api/v1/disputes/{id}/evidence":{"post":{"operationId":"DisputesController_submitEvidence","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitDisputeEvidenceDto"}}}},"responses":{"200":{"description":"Dispute evidence submitted successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Disputes"]}},"/api/v1/admin/disputes":{"get":{"operationId":"DisputesAdminController_listDisputes","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"paymentId","required":false,"in":"query","schema":{"example":"payment-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/DisputeStatus"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include disputes linked to sandbox provider records explicitly.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Disputes listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Disputes Admin"]},"post":{"operationId":"DisputesAdminController_createDispute","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDisputeDto"}}}},"responses":{"201":{"description":"Dispute created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Disputes Admin"]}},"/api/v1/admin/disputes/{id}":{"get":{"operationId":"DisputesAdminController_getDispute","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Dispute detail returned successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Disputes Admin"]}},"/api/v1/admin/disputes/{id}/evidence":{"post":{"operationId":"DisputesAdminController_submitEvidence","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitDisputeEvidenceDto"}}}},"responses":{"200":{"description":"Dispute evidence submitted successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Disputes Admin"]}},"/api/v1/admin/disputes/{id}/status":{"post":{"operationId":"DisputesAdminController_transitionStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionDisputeStatusDto"}}}},"responses":{"200":{"description":"Dispute status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","paymentId","invoiceId","amount","status","openedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"dsp_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","nullable":true},"paymentId":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"providerDisputeId":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"needs_response"},"reason":{"type":"string","nullable":true},"evidenceDueAt":{"type":"string","format":"date-time","nullable":true},"evidence":{"type":"object","nullable":true,"additionalProperties":true},"openedAt":{"type":"string","format":"date-time"},"respondedAt":{"type":"string","format":"date-time","nullable":true},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Disputes Admin"]}},"/api/v1/merchant/console":{"get":{"operationId":"MerchantConsoleController_renderConsole","parameters":[],"responses":{"200":{"description":"Browser merchant console shell. Data is loaded through the protected summary endpoint after a merchant session or scoped API key is provided."}},"tags":["Merchant Console"]}},"/api/v1/merchant/console/summary":{"get":{"operationId":"MerchantConsoleController_getSummary","parameters":[{"name":"from","required":false,"in":"query","description":"Inclusive ISO-8601 start. Must be supplied together with to; defaults to 30 days before now.","schema":{"format":"date-time","example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"Exclusive ISO-8601 end. Must be supplied together with from; cannot be in the future.","schema":{"format":"date-time","example":"2026-08-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"Merchant console summary fetched with sections filtered by API key scopes."}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Console"]}},"/dashboard":{"get":{"operationId":"MerchantDashboardController_renderDashboard[0]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/payments":{"get":{"operationId":"MerchantDashboardController_renderDashboard[1]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/invoices":{"get":{"operationId":"MerchantDashboardController_renderDashboard[2]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/payment-links":{"get":{"operationId":"MerchantDashboardController_renderDashboard[3]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/customers":{"get":{"operationId":"MerchantDashboardController_renderDashboard[4]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/products":{"get":{"operationId":"MerchantDashboardController_renderDashboard[5]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/subscriptions":{"get":{"operationId":"MerchantDashboardController_renderDashboard[6]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/balances":{"get":{"operationId":"MerchantDashboardController_renderDashboard[7]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/withdrawals":{"get":{"operationId":"MerchantDashboardController_renderDashboard[8]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/refunds":{"get":{"operationId":"MerchantDashboardController_renderDashboard[9]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/disputes":{"get":{"operationId":"MerchantDashboardController_renderDashboard[10]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/api-keys":{"get":{"operationId":"MerchantDashboardController_renderDashboard[11]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/webhooks":{"get":{"operationId":"MerchantDashboardController_renderDashboard[12]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/integrations":{"get":{"operationId":"MerchantDashboardController_renderDashboard[13]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/developers":{"get":{"operationId":"MerchantDashboardController_renderDashboard[14]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/security":{"get":{"operationId":"MerchantDashboardController_renderDashboard[15]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/team":{"get":{"operationId":"MerchantDashboardController_renderDashboard[16]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/dashboard/settings":{"get":{"operationId":"MerchantDashboardController_renderDashboard[17]","parameters":[],"responses":{"200":{"description":"Merchant dashboard shell. Protected data loads through a merchant browser session or scoped merchant API key."}},"tags":["Merchant Dashboard"]}},"/api/v1/auth/merchant/invitations/accept":{"post":{"operationId":"MerchantAuthController_acceptInvitation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptMerchantInvitationDto"}}}},"responses":{"200":{"description":"Merchant team invitation accepted; sign-in is required next.","content":{"application/json":{"schema":{"type":"object","required":["status","nextStep","merchant","identity"],"properties":{"status":{"type":"string","example":"ok"},"nextStep":{"type":"string","enum":["sign_in"],"example":"sign_in"},"merchant":{"type":"object","required":["id","code","name"],"properties":{"id":{"type":"string","example":"mrc_123"},"code":{"type":"string","example":"merchant_store"},"name":{"type":"string","example":"Merchant Store"}}},"identity":{"type":"object","required":["id","email","role","createdAt"],"properties":{"id":{"type":"string","example":"identity_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin"],"example":"admin"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/password-reset/request":{"post":{"operationId":"MerchantAuthController_requestPasswordReset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantPasswordResetRequestDto"}}}},"responses":{"200":{"description":"Accepts a merchant password-reset request without revealing whether an email exists.","content":{"application/json":{"schema":{"type":"object","required":["status","delivery","message"],"properties":{"status":{"type":"string","example":"accepted"},"delivery":{"type":"string","enum":["accepted","unavailable"],"description":"Deployment-level delivery state. The response never reveals whether the email belongs to an account."},"message":{"type":"string","example":"If an active merchant account matches that email, a reset link will be sent."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/password-reset/confirm":{"post":{"operationId":"MerchantAuthController_confirmPasswordReset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantPasswordResetConfirmDto"}}}},"responses":{"200":{"description":"Consumes a valid one-time password-reset token.","content":{"application/json":{"schema":{"type":"object","required":["status","nextStep","message"],"properties":{"status":{"type":"string","example":"ok"},"nextStep":{"type":"string","example":"sign_in"},"message":{"type":"string","example":"Password updated. Sign in again with your new password."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/login":{"post":{"operationId":"MerchantAuthController_login","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantLoginDto"}}}},"responses":{"200":{"description":"Merchant browser session created.","content":{"application/json":{"schema":{"type":"object","required":["status","expiresAt","merchant","identity"],"properties":{"status":{"type":"string","example":"ok"},"expiresAt":{"type":"string","format":"date-time"},"merchant":{"type":"object","required":["publicId","code","name","status","createdAt","updatedAt"],"properties":{"publicId":{"type":"string","example":"mrc_123"},"code":{"type":"string","example":"merchant_store"},"name":{"type":"string","example":"Merchant Store"},"legalName":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"planCode":{"type":"string","nullable":true},"metadataJson":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"identity":{"type":"object","required":["email","role"],"properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","example":"owner"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/logout":{"post":{"operationId":"MerchantAuthController_logout","parameters":[],"responses":{"200":{"description":"Merchant browser session revoked.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","example":"ok"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/session-state":{"get":{"operationId":"MerchantAuthController_sessionState","parameters":[],"responses":{"200":{"description":"Returns the current browser session when present without treating anonymous state as an error."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/me":{"get":{"operationId":"MerchantAuthController_me","parameters":[],"responses":{"200":{"description":"Current merchant browser identity.","content":{"application/json":{"schema":{"type":"object","required":["status","session"],"properties":{"status":{"type":"string","example":"ok"},"session":{"type":"object","required":["sessionId","identityPublicId","email","role","merchant"],"properties":{"sessionId":{"type":"string"},"identityPublicId":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","example":"owner"},"merchant":{"type":"object","required":["publicId","code","name","status","createdAt","updatedAt"],"properties":{"publicId":{"type":"string","example":"mrc_123"},"code":{"type":"string","example":"merchant_store"},"name":{"type":"string","example":"Merchant Store"},"legalName":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"planCode":{"type":"string","nullable":true},"metadataJson":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/sessions":{"get":{"operationId":"MerchantAuthController_listSessions","parameters":[],"responses":{"200":{"description":"Active merchant browser sessions."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/sessions/revoke-others":{"post":{"operationId":"MerchantAuthController_revokeOtherSessions","parameters":[],"responses":{"200":{"description":"Other merchant browser sessions revoked."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/sessions/{sessionId}":{"delete":{"operationId":"MerchantAuthController_revokeSession","parameters":[{"name":"sessionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant browser session revoked."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/2fa/status":{"get":{"operationId":"MerchantAuthController_twoFactorStatus","parameters":[],"responses":{"200":{"description":"Merchant two-factor capability status."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/2fa/setup":{"post":{"operationId":"MerchantAuthController_setupTwoFactor","parameters":[],"responses":{"200":{"description":"One-time TOTP enrollment material."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/2fa/confirm":{"post":{"operationId":"MerchantAuthController_confirmTwoFactor","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantTwoFactorCodeDto"}}}},"responses":{"200":{"description":"TOTP enabled and recovery codes returned once."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/auth/merchant/2fa/disable":{"post":{"operationId":"MerchantAuthController_disableTwoFactor","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableMerchantTwoFactorDto"}}}},"responses":{"200":{"description":"TOTP disabled after password and second-factor verification."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Merchant Auth"]}},"/api/v1/merchants/{merchantId}/auth-identities":{"post":{"operationId":"MerchantAuthAdminController_createIdentity","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantAuthIdentityDto"}}}},"responses":{"201":{"description":"Merchant browser identity created."},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/api/v1/merchant/settings":{"get":{"operationId":"MerchantSettingsController_getSettings","parameters":[],"responses":{"200":{"description":"Merchant settings fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","merchantId","merchantCode","businessProfile","checkout","branding","notifications","settings"],"properties":{"status":{"type":"string","example":"ok"},"merchantId":{"type":"string","example":"mrc_123"},"merchantCode":{"type":"string","example":"merchant_store"},"currentIdentityId":{"type":"string","nullable":true},"businessProfile":{"type":"object","required":["businessName","legalName"],"properties":{"businessName":{"type":"string","example":"Merchant Store"},"legalName":{"type":"string","nullable":true}}},"checkout":{"type":"object","required":["defaultSuccessUrl","defaultCloseUrl","defaultExpirationSeconds","configuredExpirationSeconds","autoRedirect"],"properties":{"defaultSuccessUrl":{"type":"string","nullable":true,"format":"uri"},"defaultCloseUrl":{"type":"string","nullable":true,"format":"uri"},"defaultExpirationSeconds":{"type":"integer","example":900},"configuredExpirationSeconds":{"type":"integer","nullable":true,"example":900},"autoRedirect":{"type":"boolean","example":false}}},"branding":{"type":"object","required":["brandName","brandAccentColor"],"properties":{"brandName":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true}}},"notifications":{"type":"object","required":["paymentConfirmed","webhookFailures"],"properties":{"paymentConfirmed":{"type":"boolean","example":true},"webhookFailures":{"type":"boolean","example":true}}},"settings":{"type":"object","nullable":true,"required":["id","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"settings_123"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Settings"]},"patch":{"operationId":"MerchantSettingsController_updateSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMerchantSettingsDto"}}}},"responses":{"200":{"description":"Merchant settings updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","merchantId","merchantCode","businessProfile","checkout","branding","notifications","settings"],"properties":{"status":{"type":"string","example":"ok"},"merchantId":{"type":"string","example":"mrc_123"},"merchantCode":{"type":"string","example":"merchant_store"},"currentIdentityId":{"type":"string","nullable":true},"businessProfile":{"type":"object","required":["businessName","legalName"],"properties":{"businessName":{"type":"string","example":"Merchant Store"},"legalName":{"type":"string","nullable":true}}},"checkout":{"type":"object","required":["defaultSuccessUrl","defaultCloseUrl","defaultExpirationSeconds","configuredExpirationSeconds","autoRedirect"],"properties":{"defaultSuccessUrl":{"type":"string","nullable":true,"format":"uri"},"defaultCloseUrl":{"type":"string","nullable":true,"format":"uri"},"defaultExpirationSeconds":{"type":"integer","example":900},"configuredExpirationSeconds":{"type":"integer","nullable":true,"example":900},"autoRedirect":{"type":"boolean","example":false}}},"branding":{"type":"object","required":["brandName","brandAccentColor"],"properties":{"brandName":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true}}},"notifications":{"type":"object","required":["paymentConfirmed","webhookFailures"],"properties":{"paymentConfirmed":{"type":"boolean","example":true},"webhookFailures":{"type":"boolean","example":true}}},"settings":{"type":"object","nullable":true,"required":["id","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"settings_123"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Settings"]}},"/api/v1/merchant/team":{"get":{"operationId":"MerchantTeamController_listMembers","parameters":[],"responses":{"200":{"description":"Merchant team identities listed successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","merchantId","merchantCode","members","invitations","capabilities"],"properties":{"status":{"type":"string","example":"ok"},"merchantId":{"type":"string","example":"mrc_123"},"merchantCode":{"type":"string","example":"merchant_store"},"members":{"type":"array","items":{"type":"object","required":["id","email","role","status","twoFactorEnabled","lastLoginAt","createdAt"],"properties":{"id":{"type":"string","example":"identity_123"},"email":{"type":"string","format":"email","example":"owner@example.com"},"role":{"type":"string","enum":["owner","admin"],"example":"owner"},"status":{"type":"string","enum":["active","disabled"],"example":"active"},"twoFactorEnabled":{"type":"boolean","example":false},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"invitations":{"type":"array","items":{"type":"object","required":["id","email","role","status","expiresAt","acceptedAt","createdAt"],"properties":{"id":{"type":"string","example":"invitation_123"},"email":{"type":"string","format":"email","example":"admin@example.com"},"role":{"type":"string","enum":["admin"],"example":"admin"},"status":{"type":"string","enum":["pending","accepted","expired","revoked"],"example":"pending"},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"capabilities":{"type":"object","required":["invitations","roleChanges","removal"],"properties":{"invitations":{"type":"boolean","example":false},"roleChanges":{"type":"boolean","example":false},"removal":{"type":"boolean","example":false}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/invitations":{"post":{"operationId":"MerchantTeamController_createInvitation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantTeamInvitationDto"}}}},"responses":{"201":{"description":"Merchant team invitation created. The invitation URL is returned only in this response.","content":{"application/json":{"schema":{"type":"object","required":["status","invitation"],"properties":{"status":{"type":"string","example":"ok"},"invitation":{"type":"object","required":["id","email","role","status","expiresAt","acceptedAt","createdAt"],"properties":{"id":{"type":"string","example":"invitation_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin"]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"invitationUrl":{"type":"string","format":"uri-reference","writeOnly":true,"description":"Returned only when creating an invitation. It contains a bearer token and must be delivered securely."},"emailDelivery":{"type":"object","description":"Returned only when creating an invitation. Does not expose provider errors or message content.","required":["status","manualDeliveryRequired"],"properties":{"status":{"type":"string","enum":["sent","disabled","failed"]},"manualDeliveryRequired":{"type":"boolean"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/invitations/{invitationId}/revoke":{"post":{"operationId":"MerchantTeamController_revokeInvitation","parameters":[{"name":"invitationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant team invitation revoked.","content":{"application/json":{"schema":{"type":"object","required":["status","invitation"],"properties":{"status":{"type":"string","example":"ok"},"invitation":{"type":"object","required":["id","email","role","status","expiresAt","acceptedAt","createdAt"],"properties":{"id":{"type":"string","example":"invitation_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin"]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"invitationUrl":{"type":"string","format":"uri-reference","writeOnly":true,"description":"Returned only when creating an invitation. It contains a bearer token and must be delivered securely."},"emailDelivery":{"type":"object","description":"Returned only when creating an invitation. Does not expose provider errors or message content.","required":["status","manualDeliveryRequired"],"properties":{"status":{"type":"string","enum":["sent","disabled","failed"]},"manualDeliveryRequired":{"type":"boolean"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/invitations/{invitationId}/resend":{"post":{"operationId":"MerchantTeamController_resendInvitation","parameters":[{"name":"invitationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Merchant team invitation token rotated and delivery attempted.","content":{"application/json":{"schema":{"type":"object","required":["status","invitation"],"properties":{"status":{"type":"string","example":"ok"},"invitation":{"type":"object","required":["id","email","role","status","expiresAt","acceptedAt","createdAt"],"properties":{"id":{"type":"string","example":"invitation_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin"]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"invitationUrl":{"type":"string","format":"uri-reference","writeOnly":true,"description":"Returned only when creating an invitation. It contains a bearer token and must be delivered securely."},"emailDelivery":{"type":"object","description":"Returned only when creating an invitation. Does not expose provider errors or message content.","required":["status","manualDeliveryRequired"],"properties":{"status":{"type":"string","enum":["sent","disabled","failed"]},"manualDeliveryRequired":{"type":"boolean"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/{memberId}/role":{"patch":{"operationId":"MerchantTeamController_updateRole","parameters":[{"name":"memberId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMerchantTeamRoleDto"}}}},"responses":{"200":{"description":"Merchant team role updated.","content":{"application/json":{"schema":{"type":"object","required":["status","member"],"properties":{"status":{"type":"string","example":"ok"},"member":{"type":"object","required":["id","email","role","status"],"properties":{"id":{"type":"string","example":"identity_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin"]},"status":{"type":"string","enum":["active","disabled"]}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/{memberId}/disable":{"post":{"operationId":"MerchantTeamController_disableMember","parameters":[{"name":"memberId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant team member disabled.","content":{"application/json":{"schema":{"type":"object","required":["status","member"],"properties":{"status":{"type":"string","example":"ok"},"member":{"type":"object","required":["id","email","role","status"],"properties":{"id":{"type":"string","example":"identity_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin"]},"status":{"type":"string","enum":["active","disabled"]}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/team/{memberId}/enable":{"post":{"operationId":"MerchantTeamController_enableMember","parameters":[{"name":"memberId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant team member enabled.","content":{"application/json":{"schema":{"type":"object","required":["status","member"],"properties":{"status":{"type":"string","example":"ok"},"member":{"type":"object","required":["id","email","role","status"],"properties":{"id":{"type":"string","example":"identity_123"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin"]},"status":{"type":"string","enum":["active","disabled"]}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Team"]}},"/api/v1/merchant/customers":{"get":{"operationId":"CustomersController_list","parameters":[{"name":"search","required":false,"in":"query","schema":{"maxLength":120,"example":"buyer@example.com","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"example":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the previous page. It is merchant-scoped and tied to the current search order.","schema":{"maxLength":200,"example":"customer_123","type":"string"}}],"responses":{"200":{"description":"Merchant-scoped canonical customers.","content":{"application/json":{"schema":{"type":"object","required":["status","available","merchantId","merchantCode","count","returnedCount","hasMore","nextCursor","customers"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"merchantId":{"type":"string","example":"mrc_123"},"merchantCode":{"type":"string","example":"merchant_store"},"count":{"type":"integer","example":1},"returnedCount":{"type":"integer","example":1},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true,"example":"customer_123"},"customers":{"type":"array","items":{"type":"object","required":["id","email","name","phone","invoiceCount","subscriptionCount","lastSeenAt","createdAt"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"invoiceCount":{"type":"integer","example":2},"subscriptionCount":{"type":"integer","example":1},"lastSeenAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Customers"]}},"/api/v1/merchant/customers/{publicId}":{"get":{"operationId":"CustomersController_get","parameters":[{"name":"publicId","required":true,"in":"path","schema":{"example":"customer_123","type":"string"}}],"responses":{"200":{"description":"Merchant-scoped customer detail and payment history.","content":{"application/json":{"schema":{"type":"object","required":["status","available","customer"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"customer":{"type":"object","required":["id","email","name","phone","metadata","firstSeenAt","lastSeenAt","createdAt","updatedAt","invoiceCount","paymentCount","subscriptionCount","subscriptions","invoices","payments"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"invoiceCount":{"type":"integer","example":2},"paymentCount":{"type":"integer","example":1},"subscriptionCount":{"type":"integer","example":1},"subscriptions":{"type":"array","items":{"type":"object","required":["id","title","status","interval","intervalCount","amountExpected","currency","assetCode","networkCode","nextInvoiceAt","lastInvoiceAt","cancelledAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"interval":{"type":"string"},"intervalCount":{"type":"integer"},"amountExpected":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"invoices":{"type":"array","items":{"type":"object","required":["id","reference","status","amountExpected","amountReceived","currency","assetCode","networkCode","createdAt"],"properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"amountExpected":{"type":"string"},"amountReceived":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"payments":{"type":"array","items":{"type":"object","required":["id","invoiceId","invoiceReference","amountReceived","currency","assetCode","networkCode","status","txid","confirmedAt","createdAt"],"properties":{"id":{"type":"string"},"invoiceId":{"type":"string"},"invoiceReference":{"type":"string"},"amountReceived":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Customers"]},"patch":{"operationId":"CustomersController_update","parameters":[{"name":"publicId","required":true,"in":"path","schema":{"example":"customer_123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"Merchant customer profile updated without changing its email or history.","content":{"application/json":{"schema":{"type":"object","required":["status","customer"],"properties":{"status":{"type":"string","example":"ok"},"customer":{"type":"object","required":["id","email","name","phone","metadata","updatedAt"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Customers"]}},"/api/v1/merchant/products":{"post":{"operationId":"ProductsController_create","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductDto"}}}},"responses":{"201":{"description":"Merchant product with one-time price created.","content":{"application/json":{"schema":{"type":"object","required":["status","available","product"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"product":{"type":"object","required":["id","name","description","status","metadata","createdAt","updatedAt","prices"],"properties":{"id":{"type":"string","example":"product_123"},"name":{"type":"string","example":"Premium access"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prices":{"type":"array","items":{"type":"object","required":["id","amount","currency","assetCode","networkCode","pricingMode","priceType","version","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"price_123"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"priceType":{"type":"string","example":"one_time"},"version":{"type":"integer","minimum":1,"example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Products"]},"get":{"operationId":"ProductsController_list","parameters":[{"name":"search","required":false,"in":"query","schema":{"maxLength":200,"example":"Premium access","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"example":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the previous page.","schema":{"maxLength":200,"example":"product_123","type":"string"}}],"responses":{"200":{"description":"Merchant products listed.","content":{"application/json":{"schema":{"type":"object","required":["status","available","merchantId","merchantCode","count","returnedCount","hasMore","nextCursor","products"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"merchantId":{"type":"string","example":"mrc_123"},"merchantCode":{"type":"string","example":"merchant_store"},"count":{"type":"integer","example":1},"returnedCount":{"type":"integer","example":1},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true},"products":{"type":"array","items":{"type":"object","required":["id","name","description","status","metadata","createdAt","updatedAt","prices"],"properties":{"id":{"type":"string","example":"product_123"},"name":{"type":"string","example":"Premium access"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prices":{"type":"array","items":{"type":"object","required":["id","amount","currency","assetCode","networkCode","pricingMode","priceType","version","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"price_123"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"priceType":{"type":"string","example":"one_time"},"version":{"type":"integer","minimum":1,"example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Products"]}},"/api/v1/merchant/products/{publicId}/prices":{"post":{"operationId":"ProductsController_addPriceVersion","parameters":[{"name":"publicId","required":true,"in":"path","schema":{"example":"product_123","type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductPriceDto"}}}},"responses":{"201":{"description":"A new immutable one-time price version was created.","content":{"application/json":{"schema":{"type":"object","required":["status","available","product"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"product":{"type":"object","required":["id","name","description","status","metadata","createdAt","updatedAt","prices"],"properties":{"id":{"type":"string","example":"product_123"},"name":{"type":"string","example":"Premium access"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prices":{"type":"array","items":{"type":"object","required":["id","amount","currency","assetCode","networkCode","pricingMode","priceType","version","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"price_123"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"priceType":{"type":"string","example":"one_time"},"version":{"type":"integer","minimum":1,"example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Products"]}},"/api/v1/merchant/products/{publicId}":{"get":{"operationId":"ProductsController_get","parameters":[{"name":"publicId","required":true,"in":"path","schema":{"example":"product_123","type":"string"}}],"responses":{"200":{"description":"Merchant product fetched.","content":{"application/json":{"schema":{"type":"object","required":["status","available","product"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"product":{"type":"object","required":["id","name","description","status","metadata","createdAt","updatedAt","prices"],"properties":{"id":{"type":"string","example":"product_123"},"name":{"type":"string","example":"Premium access"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prices":{"type":"array","items":{"type":"object","required":["id","amount","currency","assetCode","networkCode","pricingMode","priceType","version","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"price_123"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"priceType":{"type":"string","example":"one_time"},"version":{"type":"integer","minimum":1,"example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Products"]}},"/api/v1/merchant/products/{publicId}/archive":{"post":{"operationId":"ProductsController_archive","parameters":[{"name":"publicId","required":true,"in":"path","schema":{"example":"product_123","type":"string"}}],"responses":{"200":{"description":"Merchant product archived.","content":{"application/json":{"schema":{"type":"object","required":["status","available","product"],"properties":{"status":{"type":"string","example":"ok"},"available":{"type":"boolean","example":true},"product":{"type":"object","required":["id","name","description","status","metadata","createdAt","updatedAt","prices"],"properties":{"id":{"type":"string","example":"product_123"},"name":{"type":"string","example":"Premium access"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","nullable":true,"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prices":{"type":"array","items":{"type":"object","required":["id","amount","currency","assetCode","networkCode","pricingMode","priceType","version","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"price_123"},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"priceType":{"type":"string","example":"one_time"},"version":{"type":"integer","minimum":1,"example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Merchant Products"]}},"/api/v1/recurring/plans":{"post":{"operationId":"RecurringPaymentPlansController_createPlan","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecurringPaymentPlanDto"}}}},"responses":{"201":{"description":"Recurring payment plan created.","content":{"application/json":{"schema":{"type":"object","required":["id","title","status","interval","intervalCount","methodType","currency","assetCode","networkCode","amountExpected","pricingMode","invoiceLifetimeSeconds","invoiceAutomationEnabled","automationStatus","warning","customer","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"rplan_123"},"title":{"type":"string","example":"Monthly plan"},"description":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"interval":{"type":"string","example":"monthly"},"intervalCount":{"type":"integer","example":1},"methodType":{"type":"string","example":"usdt_trc20"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00"},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","example":900},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"invoiceAutomationEnabled":{"type":"boolean"},"automationStatus":{"type":"string","example":"scheduler_not_enabled"},"warning":{"type":"string"},"customer":{"type":"object","nullable":true,"required":["id","email","name"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true}}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Recurring Payments"]},"get":{"operationId":"RecurringPaymentPlansController_listPlans","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["active","paused","cancelled","archived"]}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"default":50,"example":50,"type":"number"}}],"responses":{"200":{"description":"Recurring payment plans listed.","content":{"application/json":{"schema":{"type":"object","required":["status","invoiceAutomationEnabled","data","pagination"],"properties":{"status":{"type":"string","example":"ok"},"invoiceAutomationEnabled":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","required":["id","title","status","interval","intervalCount","methodType","currency","assetCode","networkCode","amountExpected","pricingMode","invoiceLifetimeSeconds","invoiceAutomationEnabled","automationStatus","warning","customer","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"rplan_123"},"title":{"type":"string","example":"Monthly plan"},"description":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"interval":{"type":"string","example":"monthly"},"intervalCount":{"type":"integer","example":1},"methodType":{"type":"string","example":"usdt_trc20"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00"},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","example":900},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"invoiceAutomationEnabled":{"type":"boolean"},"automationStatus":{"type":"string","example":"scheduler_not_enabled"},"warning":{"type":"string"},"customer":{"type":"object","nullable":true,"required":["id","email","name"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true}}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["limit","returned"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":1}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Recurring Payments"]}},"/api/v1/recurring/plans/{id}/detail":{"get":{"operationId":"RecurringPaymentPlansController_getPlanDetail","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Recurring payment plan, invoice-generation runs and generated invoice facts fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","plan","invoiceRuns","runSummary","historyLimit"],"properties":{"status":{"type":"string","example":"ok"},"plan":{"type":"object","required":["id","title","status","interval","intervalCount","methodType","currency","assetCode","networkCode","amountExpected","pricingMode","invoiceLifetimeSeconds","invoiceAutomationEnabled","automationStatus","warning","customer","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"rplan_123"},"title":{"type":"string","example":"Monthly plan"},"description":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"interval":{"type":"string","example":"monthly"},"intervalCount":{"type":"integer","example":1},"methodType":{"type":"string","example":"usdt_trc20"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00"},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","example":900},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"invoiceAutomationEnabled":{"type":"boolean"},"automationStatus":{"type":"string","example":"scheduler_not_enabled"},"warning":{"type":"string"},"customer":{"type":"object","nullable":true,"required":["id","email","name"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true}}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"invoiceRuns":{"type":"array","items":{"type":"object","required":["id","scheduleKey","scheduledFor","status","attemptCount","maxAttempts","hasError","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"run_123"},"scheduleKey":{"type":"string"},"scheduledFor":{"type":"string","format":"date-time"},"status":{"type":"string","example":"created"},"attemptCount":{"type":"integer","example":1},"maxAttempts":{"type":"integer","example":3},"hasError":{"type":"boolean"},"invoice":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"invoiceReference":{"type":"string"},"status":{"type":"string"},"amountExpected":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"runSummary":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"historyLimit":{"type":"integer","example":50}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Recurring Payments"]}},"/api/v1/recurring/plans/{id}":{"get":{"operationId":"RecurringPaymentPlansController_getPlan","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Recurring payment plan fetched.","content":{"application/json":{"schema":{"type":"object","required":["id","title","status","interval","intervalCount","methodType","currency","assetCode","networkCode","amountExpected","pricingMode","invoiceLifetimeSeconds","invoiceAutomationEnabled","automationStatus","warning","customer","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"rplan_123"},"title":{"type":"string","example":"Monthly plan"},"description":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"interval":{"type":"string","example":"monthly"},"intervalCount":{"type":"integer","example":1},"methodType":{"type":"string","example":"usdt_trc20"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00"},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","example":900},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"invoiceAutomationEnabled":{"type":"boolean"},"automationStatus":{"type":"string","example":"scheduler_not_enabled"},"warning":{"type":"string"},"customer":{"type":"object","nullable":true,"required":["id","email","name"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true}}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Recurring Payments"]}},"/api/v1/recurring/plans/{id}/status":{"post":{"operationId":"RecurringPaymentPlansController_updatePlanStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringPaymentPlanStatusDto"}}}},"responses":{"200":{"description":"Recurring payment plan status updated.","content":{"application/json":{"schema":{"type":"object","required":["id","title","status","interval","intervalCount","methodType","currency","assetCode","networkCode","amountExpected","pricingMode","invoiceLifetimeSeconds","invoiceAutomationEnabled","automationStatus","warning","customer","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"rplan_123"},"title":{"type":"string","example":"Monthly plan"},"description":{"type":"string","nullable":true},"status":{"type":"string","example":"active"},"interval":{"type":"string","example":"monthly"},"intervalCount":{"type":"integer","example":1},"methodType":{"type":"string","example":"usdt_trc20"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00"},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","example":900},"nextInvoiceAt":{"type":"string","format":"date-time","nullable":true},"lastInvoiceAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"invoiceAutomationEnabled":{"type":"boolean"},"automationStatus":{"type":"string","example":"scheduler_not_enabled"},"warning":{"type":"string"},"customer":{"type":"object","nullable":true,"required":["id","email","name"],"properties":{"id":{"type":"string","example":"customer_123"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true}}},"metadata":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Recurring Payments"]}},"/api/v1/admin/crypto/routes":{"get":{"operationId":"AdminCryptoController_listRoutes","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"default":"open","type":"string","enum":["open","all"]}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}}],"responses":{"200":{"description":"Crypto routes fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List active or historical crypto invoice routes","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/wallet-capacity":{"get":{"operationId":"AdminCryptoController_getWalletCapacity","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto wallet capacity fetched successfully."}},"security":[{"adminToken":[]}],"summary":"Inspect wallet inventory and free routing capacity","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/capabilities":{"get":{"operationId":"AdminCryptoController_listCapabilities","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto capabilities fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List crypto rails and whether they are fully ready or manual-only","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/live-check":{"get":{"operationId":"AdminCryptoController_getLiveCheck","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"1.00","example":"1.00","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}},{"name":"merchantId","required":false,"in":"query","description":"Optional merchant public id. When present, readiness checks are scoped to this merchant and its webhook endpoint.","schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto live check generated successfully."}},"security":[{"adminToken":[]}],"summary":"Run an operator live check for a specific crypto rail","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/live-checks":{"get":{"operationId":"AdminCryptoController_getPrimaryLiveChecks","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"1.00","example":"1.00","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}},{"name":"merchantId","required":false,"in":"query","description":"Optional merchant public id. When present, readiness checks are scoped to this merchant and its webhook endpoint.","schema":{"type":"string"}}],"responses":{"200":{"description":"Primary crypto live checks generated successfully."}},"security":[{"adminToken":[]}],"summary":"Run operator live checks for primary crypto rails","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/watchers":{"get":{"operationId":"AdminCryptoController_listWatchers","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automatic crypto watchers fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List automatic crypto watchers and whether they are enabled","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/watchers/health":{"get":{"operationId":"AdminCryptoController_getWatcherHealth","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automatic crypto watcher health fetched successfully."}},"security":[{"adminToken":[]}],"summary":"Inspect automatic watcher health, cursors and alert signals","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/watchers/cursors":{"get":{"operationId":"AdminCryptoController_listWatcherCursors","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Automatic crypto watcher cursors fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List stored watcher cursors for chains that scan by block cursor","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/prices/quote":{"get":{"operationId":"AdminCryptoController_quotePrice","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}},{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"10.00","example":"10.00","type":"string"}},{"name":"networkCode","required":false,"in":"query","description":"Optional network or rail context for the quote lock, for example BTC, LIGHTNING, TRC20, ERC20, LTC.","schema":{"example":"BTC","type":"string"}},{"name":"priceBufferBps","required":false,"in":"query","schema":{"default":"50","example":"50","type":"string"}}],"responses":{"200":{"description":"Crypto price quote generated successfully."}},"security":[{"adminToken":[]}],"summary":"Preview fiat-to-crypto pricing used by hosted crypto invoices","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/watchers/scan":{"post":{"operationId":"AdminCryptoController_triggerWatcherScan","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerWatcherScanDto"}}}},"responses":{"200":{"description":"Automatic crypto watcher scan executed successfully."}},"security":[{"adminToken":[]}],"summary":"Trigger a manual scan for all enabled watchers or one watcher","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/transactions":{"get":{"operationId":"AdminCryptoController_listTransactions","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/CryptoTransactionStatus"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"invoiceId","required":false,"in":"query","description":"Restrict results to the crypto transaction for one invoice.","schema":{"example":"invoice-public-id","type":"string"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include sandbox provider records for diagnostics. Production views exclude them by default.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"Recent crypto transactions fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List recently detected crypto transactions across watchers","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/providers/btcpay":{"get":{"operationId":"AdminCryptoController_getBtcpayProviderStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"BTCPay Lightning provider status fetched successfully."}},"security":[{"adminToken":[]}],"summary":"Inspect BTCPay Lightning provider configuration and webhooks","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/providers/binance":{"get":{"operationId":"AdminCryptoController_getBinanceProviderStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Binance read-only provider status fetched successfully."}},"security":[{"adminToken":[]}],"summary":"Verify Binance deposit reconciliation safety and network status","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/providers/binance/deposit-inventory":{"get":{"operationId":"AdminCryptoController_getBinanceDepositInventory","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sanitized Binance deposit inventory fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List the current Binance deposit asset and network inventory without enabling rails","tags":["Admin Crypto"]}},"/api/v1/admin/crypto/providers/btcpay/webhook/sync":{"post":{"operationId":"AdminCryptoController_syncBtcpayWebhook","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncBtcpayWebhookDto"}}}},"responses":{"200":{"description":"BTCPay webhook synced successfully."}},"security":[{"adminToken":[]}],"summary":"Create or update the BTCPay webhook to point to this gateway","tags":["Admin Crypto"]}},"/api/v1/crypto/assets":{"get":{"operationId":"CryptoAssetsController_listAssets","parameters":[],"responses":{"200":{"description":"Active crypto assets listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","decimals","isStablecoin","isActive"],"properties":{"code":{"type":"string","example":"USDT"},"name":{"type":"string","example":"Tether USD"},"decimals":{"type":"integer","example":6},"isStablecoin":{"type":"boolean"},"isActive":{"type":"boolean"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Assets"]}},"/api/v1/crypto/capabilities":{"get":{"operationId":"CryptoCapabilitiesController_listCapabilities","parameters":[],"responses":{"200":{"description":"Merchant-facing crypto capabilities listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["assetCode","networkCode","methodType","hostedCheckout","quoteSupported","quoteLockSupported","autoDetectionConfigured","routeKind","status","notes"],"properties":{"assetCode":{"type":"string"},"networkCode":{"type":"string"},"methodType":{"type":"string"},"hostedCheckout":{"type":"boolean"},"quoteSupported":{"type":"boolean"},"quoteLockSupported":{"type":"boolean"},"autoDetectionConfigured":{"type":"boolean"},"routeKind":{"type":"string"},"supportsAmountFingerprint":{"type":"boolean"},"explorerSupported":{"type":"boolean"},"walletDeepLinkSupported":{"type":"boolean"},"status":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Capabilities"]}},"/api/v1/crypto/supported-rails":{"get":{"operationId":"CryptoSupportedRailsController_listSupportedRails","parameters":[],"responses":{"200":{"description":"Supported crypto rails listed successfully.","content":{"application/json":{"schema":{"type":"object","required":["source","sourceUrl","compatibilityModel","generatedAt","summary","rails","cryptomusCompatible"],"properties":{"source":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"compatibilityModel":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"summary":{"type":"object","additionalProperties":true},"rails":{"type":"array","items":{"type":"object","additionalProperties":true}},"cryptomusCompatible":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Return the broad commercial crypto catalog with explicit invoice readiness","tags":["Crypto Supported Rails"]}},"/api/v1/crypto/services":{"get":{"operationId":"CryptoServicesController_listServices","parameters":[{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"1.00","example":"1.00","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}}],"responses":{"200":{"description":"Merchant crypto services generated successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","operatorStatus","generatedAt","merchantId","fiatAmount","fiatCurrency","recommendedService","services"],"properties":{"status":{"type":"string","example":"ready"},"operatorStatus":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"merchantId":{"type":"string"},"fiatAmount":{"type":"string"},"fiatCurrency":{"type":"string"},"recommendedService":{"type":"object","nullable":true,"additionalProperties":true},"services":{"type":"array","items":{"allOf":[{"type":"object","required":["assetCode","networkCode","status","priority","offerToBuyer","buyerLabel","displayLabel","economics","operationalState","blockers","warnings"],"properties":{"assetCode":{"type":"string"},"networkCode":{"type":"string"},"methodType":{"type":"string","nullable":true},"status":{"type":"string","example":"ready"},"priority":{"type":"integer"},"offerToBuyer":{"type":"boolean"},"buyerLabel":{"type":"string"},"displayLabel":{"type":"string"},"economics":{"type":"object","additionalProperties":true},"speedProfile":{"type":"string","nullable":true},"senderFeeProfile":{"type":"string","nullable":true},"routeKind":{"type":"string","nullable":true},"walletDeepLinkSupported":{"type":"boolean"},"explorerSupported":{"type":"boolean"},"quote":{"type":"object","nullable":true,"additionalProperties":true},"operationalState":{"type":"object","additionalProperties":true},"blockers":{"type":"array","items":{"type":"object","additionalProperties":true}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}}}}],"properties":{"isAvailable":{"type":"boolean"},"hostedCheckout":{"type":"boolean"},"quoteSupported":{"type":"boolean"},"cryptomusCompatible":{"type":"object","additionalProperties":true}}}},"cryptomusCompatible":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Return merchant-safe crypto services derived from live readiness checks","tags":["Crypto Services"]}},"/api/v1/crypto/readiness":{"get":{"operationId":"CryptoReadinessController_getReadiness","parameters":[{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"1.00","example":"1.00","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}}],"responses":{"200":{"description":"Merchant crypto readiness generated successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","operatorStatus","generatedAt","merchantId","fiatAmount","fiatCurrency","recommendedRail","summary","rails"],"properties":{"status":{"type":"string","example":"ready"},"operatorStatus":{"type":"string","example":"ready"},"generatedAt":{"type":"string","format":"date-time"},"merchantId":{"type":"string"},"fiatAmount":{"type":"string","example":"10.00"},"fiatCurrency":{"type":"string","example":"USD"},"recommendedRail":{"allOf":[{"type":"object","required":["assetCode","networkCode","status","priority","offerToBuyer","buyerLabel","displayLabel","economics","operationalState","blockers","warnings"],"properties":{"assetCode":{"type":"string"},"networkCode":{"type":"string"},"methodType":{"type":"string","nullable":true},"status":{"type":"string","example":"ready"},"priority":{"type":"integer"},"offerToBuyer":{"type":"boolean"},"buyerLabel":{"type":"string"},"displayLabel":{"type":"string"},"economics":{"type":"object","additionalProperties":true},"speedProfile":{"type":"string","nullable":true},"senderFeeProfile":{"type":"string","nullable":true},"routeKind":{"type":"string","nullable":true},"walletDeepLinkSupported":{"type":"boolean"},"explorerSupported":{"type":"boolean"},"quote":{"type":"object","nullable":true,"additionalProperties":true},"operationalState":{"type":"object","additionalProperties":true},"blockers":{"type":"array","items":{"type":"object","additionalProperties":true}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}}}}],"nullable":true},"summary":{"type":"object","required":["totalRails","offerableRails","readyRails","warningRails","blockedRails"],"properties":{"totalRails":{"type":"integer"},"offerableRails":{"type":"integer"},"readyRails":{"type":"integer"},"warningRails":{"type":"integer"},"blockedRails":{"type":"integer"}}},"rails":{"type":"array","items":{"type":"object","required":["assetCode","networkCode","status","priority","offerToBuyer","buyerLabel","displayLabel","economics","operationalState","blockers","warnings"],"properties":{"assetCode":{"type":"string"},"networkCode":{"type":"string"},"methodType":{"type":"string","nullable":true},"status":{"type":"string","example":"ready"},"priority":{"type":"integer"},"offerToBuyer":{"type":"boolean"},"buyerLabel":{"type":"string"},"displayLabel":{"type":"string"},"economics":{"type":"object","additionalProperties":true},"speedProfile":{"type":"string","nullable":true},"senderFeeProfile":{"type":"string","nullable":true},"routeKind":{"type":"string","nullable":true},"walletDeepLinkSupported":{"type":"boolean"},"explorerSupported":{"type":"boolean"},"quote":{"type":"object","nullable":true,"additionalProperties":true},"operationalState":{"type":"object","additionalProperties":true},"blockers":{"type":"array","items":{"type":"object","additionalProperties":true}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Return merchant-scoped readiness and recommended primary crypto rail","tags":["Crypto Readiness"]}},"/api/v1/crypto/networks":{"get":{"operationId":"CryptoNetworksController_listNetworks","parameters":[],"responses":{"200":{"description":"Active crypto networks listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","confirmationsRequired","isLightning","isActive"],"properties":{"code":{"type":"string","example":"TRC20"},"name":{"type":"string","example":"TRON TRC20"},"confirmationsRequired":{"type":"integer","example":20},"isLightning":{"type":"boolean"},"isActive":{"type":"boolean"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Networks"]}},"/api/v1/crypto/wallets":{"post":{"operationId":"CryptoWalletsController_createWallet","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCryptoWalletDto"}}}},"responses":{"201":{"description":"Crypto wallet created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","providerCode","label","assetCode","networkCode","address","memoTag","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"label":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string"},"memoTag":{"type":"string","nullable":true},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Crypto Wallets"]},"get":{"operationId":"CryptoWalletsController_listWallets","parameters":[{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Crypto wallets listed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","providerCode","label","assetCode","networkCode","address","memoTag","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"label":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string"},"memoTag":{"type":"string","nullable":true},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Crypto Wallets"]}},"/api/v1/wallets/addresses":{"get":{"operationId":"MerchantWalletAddressesController_listAddresses","parameters":[{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/CryptoWalletStatus"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Merchant wallet addresses fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","custodyModel","merchantId","addresses","warning"],"properties":{"status":{"type":"string","example":"ok"},"custodyModel":{"type":"string"},"merchantId":{"type":"string"},"addresses":{"type":"array","items":{"type":"object","required":["id","label","assetCode","networkCode","address","memoTag","providerCode","status","ownershipScope","paymentUri","explorerAddressUrl","walletActionLabel","compatibility","cryptomusCompatible"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string"},"memoTag":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"status":{"type":"string"},"ownershipScope":{"type":"string"},"paymentUri":{"type":"string","nullable":true},"explorerAddressUrl":{"type":"string","nullable":true},"walletActionLabel":{"type":"string","nullable":true},"compatibility":{"type":"object","nullable":true,"additionalProperties":true},"cryptomusCompatible":{"type":"object","additionalProperties":true}}}},"warning":{"type":"string"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Return active merchant-accessible receiving addresses for supported crypto rails","tags":["Business Wallet"]}},"/api/v1/wallets/static":{"post":{"operationId":"MerchantWalletAddressesController_createStaticWallet","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStaticWalletAssignmentDto"}}}},"responses":{"201":{"description":"Static wallet assignment created or replayed safely.","content":{"application/json":{"schema":{"type":"object","required":["id","assetCode","networkCode","externalReference","status","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"externalReference":{"type":"string"},"label":{"type":"string","nullable":true},"status":{"type":"string"},"wallet":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Assign a merchant-owned static receiving address for a concrete crypto rail","tags":["Business Wallet"]},"get":{"operationId":"MerchantWalletAddressesController_listStaticWallets","parameters":[{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":50,"example":50,"type":"number"}}],"responses":{"200":{"description":"Static wallet assignments fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","custodyModel","data","pagination"],"properties":{"status":{"type":"string","example":"ok"},"custodyModel":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["id","assetCode","networkCode","externalReference","status","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"externalReference":{"type":"string"},"label":{"type":"string","nullable":true},"status":{"type":"string"},"wallet":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","required":["returned","limit"],"properties":{"returned":{"type":"integer"},"limit":{"type":"integer"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"List merchant static receiving address assignments","tags":["Business Wallet"]}},"/api/v1/wallets/static/{id}":{"get":{"operationId":"MerchantWalletAddressesController_getStaticWallet","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Static wallet assignment fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","assetCode","networkCode","externalReference","status","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"externalReference":{"type":"string"},"label":{"type":"string","nullable":true},"status":{"type":"string"},"wallet":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Get one merchant static receiving address assignment","tags":["Business Wallet"]}},"/api/v1/wallets/static/{id}/block":{"post":{"operationId":"MerchantWalletAddressesController_blockStaticWallet","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockStaticWalletAssignmentDto"}}}},"responses":{"200":{"description":"Static wallet assignment blocked successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","assetCode","networkCode","externalReference","status","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"externalReference":{"type":"string"},"label":{"type":"string","nullable":true},"status":{"type":"string"},"wallet":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Block a merchant static receiving address assignment","tags":["Business Wallet"]}},"/api/v1/crypto/prices/quote":{"get":{"operationId":"CryptoPricingController_quotePrice","parameters":[{"name":"assetCode","required":false,"in":"query","schema":{"default":"BTC","example":"BTC","type":"string"}},{"name":"fiatCurrency","required":false,"in":"query","schema":{"default":"USD","example":"USD","type":"string"}},{"name":"fiatAmount","required":false,"in":"query","schema":{"default":"10.00","example":"10.00","type":"string"}},{"name":"networkCode","required":false,"in":"query","description":"Optional network or rail context for the quote lock, for example BTC, LIGHTNING, TRC20, ERC20, LTC.","schema":{"example":"BTC","type":"string"}},{"name":"priceBufferBps","required":false,"in":"query","schema":{"default":"50","example":"50","type":"string"}}],"responses":{"200":{"description":"Merchant-facing crypto price quote generated successfully.","content":{"application/json":{"schema":{"type":"object","required":["merchantId","merchantCode","quote","cryptoAmount","quoteId"],"properties":{"merchantId":{"type":"string"},"merchantCode":{"type":"string"},"networkCode":{"type":"string","nullable":true},"cryptoAmount":{"type":"string"},"quoteId":{"type":"string"},"quote":{"type":"object","required":["assetCode","fiatCurrency","medianRate","effectiveRate","bufferBps","sourceCount","sourcePrices","quotedAt","quoteExpiresAt","cacheTtlSeconds"],"properties":{"assetCode":{"type":"string"},"fiatCurrency":{"type":"string"},"medianRate":{"type":"number"},"effectiveRate":{"type":"number"},"bufferBps":{"type":"integer"},"sourceCount":{"type":"integer"},"sourcePrices":{"type":"object","additionalProperties":{"type":"number"}},"quotedAt":{"type":"string","format":"date-time"},"quoteExpiresAt":{"type":"string","format":"date-time"},"cacheTtlSeconds":{"type":"integer"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Pricing"]}},"/api/v1/crypto/invoices":{"post":{"operationId":"CryptoInvoicesController_createInvoice","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCryptoInvoiceDto"}}}},"responses":{"201":{"description":"Crypto invoice created successfully.","content":{"application/json":{"schema":{"type":"object","required":["invoice","instructions","gatewayStatus","checkout"],"properties":{"invoice":{"type":"object","required":["publicId","invoiceReference","status"],"properties":{"publicId":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"pending"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"instructions":{"type":"object","description":"Runtime-backed payment route and wallet instructions.","additionalProperties":true},"gatewayStatus":{"type":"object","required":["code","isFinal"],"properties":{"code":{"type":"string","example":"waiting_payment"},"isFinal":{"type":"boolean","example":false}},"additionalProperties":true},"checkout":{"type":"object","required":["path"],"properties":{"path":{"type":"string"}}},"cryptomusCompatible":{"type":"object","description":"Compatibility fields for existing merchant integrations.","additionalProperties":true}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Invoices"]}},"/api/v1/crypto/invoices/info":{"post":{"operationId":"CryptoInvoicesController_getInvoiceInfo","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoInvoiceInfoDto"}}}},"responses":{"200":{"description":"Crypto invoice information fetched by public id/uuid or merchant order id.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","status","amountExpected","amountReceived","feeAmount","netAmount","assetCode","networkCode","checkout","route","wallet","payments"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"status":{"type":"string","example":"waiting_payment"},"gatewayStatus":{"type":"object","additionalProperties":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"checkout":{"type":"object","additionalProperties":true},"route":{"type":"object","additionalProperties":true},"wallet":{"type":"object","additionalProperties":true},"payments":{"type":"array","items":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"latestPayment":{"allOf":[{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}],"nullable":true},"pricing":{"type":"object","nullable":true,"additionalProperties":true},"amountFingerprint":{"type":"object","nullable":true,"additionalProperties":true},"railEconomics":{"type":"object","additionalProperties":true},"additionalData":{"type":"string","nullable":true},"cryptomusCompatible":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Invoices"]}},"/api/v1/crypto/invoices/{id}/instructions":{"get":{"operationId":"CryptoInvoicesController_getInstructions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto invoice instructions fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["routeId","invoice","wallet","route","network","asset"],"properties":{"routeId":{"type":"string","example":"route_123"},"checkout":{"type":"object","additionalProperties":true},"invoice":{"type":"object","additionalProperties":true},"wallet":{"type":"object","additionalProperties":true},"route":{"type":"object","additionalProperties":true},"network":{"type":"object","additionalProperties":true},"asset":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Invoices"]}},"/api/v1/crypto/invoice-selections":{"post":{"operationId":"CryptoInvoiceSelectionController_create","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCryptoInvoiceDto"}}}},"responses":{"201":{"description":"Multi-rail crypto payment selection created.","content":{"application/json":{"schema":{"type":"object","required":["id","status","invoiceReference","fiatAmount","fiatCurrency","expiresAt","selectionUrl","options"],"properties":{"id":{"type":"string","example":"sel_123"},"status":{"type":"string","example":"open"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"itemName":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"fiatAmount":{"type":"string","example":"100.00"},"fiatCurrency":{"type":"string","example":"USD"},"expiresAt":{"type":"string","format":"date-time"},"selectionUrl":{"type":"string","format":"uri"},"options":{"type":"array","items":{"type":"object","required":["assetCode","networkCode","buyerLabel","cryptoAmount","quoteId","quoteExpiresAt"],"properties":{"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"methodType":{"type":"string","nullable":true},"buyerLabel":{"type":"string","example":"USDT on TRON (TRC20)"},"displayLabel":{"type":"string","example":"USDT on TRON (TRC20)"},"cryptoAmount":{"type":"string","example":"100.00000000"},"fiatCurrency":{"type":"string","example":"USD"},"quoteId":{"type":"string","example":"qp_123"},"quoteExpiresAt":{"type":"string","format":"date-time"},"economics":{"type":"object","additionalProperties":true},"speedProfile":{"type":"string","example":"fast_stablecoin"},"senderFeeProfile":{"type":"string","example":"network_fee_paid_by_sender"},"routeKind":{"type":"string","nullable":true},"walletDeepLinkSupported":{"type":"boolean"},"explorerSupported":{"type":"boolean"}}}},"invoice":{"type":"object","nullable":true,"description":"Present only after a rail was confirmed.","additionalProperties":true}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Invoice Selection"]}},"/api/v1/crypto/invoice-selections/{id}":{"get":{"operationId":"CryptoInvoiceSelectionController_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Public multi-rail crypto selection as JSON or HTML.","content":{"application/json":{"schema":{"type":"object","required":["id","status","invoiceReference","fiatAmount","fiatCurrency","expiresAt","selectionUrl","options"],"properties":{"id":{"type":"string","example":"sel_123"},"status":{"type":"string","example":"open"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"itemName":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"fiatAmount":{"type":"string","example":"100.00"},"fiatCurrency":{"type":"string","example":"USD"},"expiresAt":{"type":"string","format":"date-time"},"selectionUrl":{"type":"string","format":"uri"},"options":{"type":"array","items":{"type":"object","required":["assetCode","networkCode","buyerLabel","cryptoAmount","quoteId","quoteExpiresAt"],"properties":{"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"methodType":{"type":"string","nullable":true},"buyerLabel":{"type":"string","example":"USDT on TRON (TRC20)"},"displayLabel":{"type":"string","example":"USDT on TRON (TRC20)"},"cryptoAmount":{"type":"string","example":"100.00000000"},"fiatCurrency":{"type":"string","example":"USD"},"quoteId":{"type":"string","example":"qp_123"},"quoteExpiresAt":{"type":"string","format":"date-time"},"economics":{"type":"object","additionalProperties":true},"speedProfile":{"type":"string","example":"fast_stablecoin"},"senderFeeProfile":{"type":"string","example":"network_fee_paid_by_sender"},"routeKind":{"type":"string","nullable":true},"walletDeepLinkSupported":{"type":"boolean"},"explorerSupported":{"type":"boolean"}}}},"invoice":{"type":"object","nullable":true,"description":"Present only after a rail was confirmed.","additionalProperties":true}}}},"text/html":{"schema":{"type":"string","description":"Rendered HTML document. The response is not a JSON API payload.","example":"<!doctype html><html lang=\"en\">...</html>"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Crypto Invoice Selection"]}},"/api/v1/crypto/invoice-selections/{id}/confirm":{"post":{"operationId":"CryptoInvoiceSelectionController_confirm","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmCryptoInvoiceSelectionDto"}}}},"responses":{"201":{"description":"Crypto invoice created from a selected rail.","content":{"application/json":{"schema":{"type":"object","required":["invoice","instructions","gatewayStatus","checkout"],"properties":{"invoice":{"type":"object","required":["publicId","invoiceReference","status"],"properties":{"publicId":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"pending"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"instructions":{"type":"object","description":"Runtime-backed payment route and wallet instructions.","additionalProperties":true},"gatewayStatus":{"type":"object","required":["code","isFinal"],"properties":{"code":{"type":"string","example":"waiting_payment"},"isFinal":{"type":"boolean","example":false}},"additionalProperties":true},"checkout":{"type":"object","required":["path"],"properties":{"path":{"type":"string"}}},"cryptomusCompatible":{"type":"object","description":"Compatibility fields for existing merchant integrations.","additionalProperties":true}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Crypto Invoice Selection"]}},"/api/v1/crypto/payment-links":{"post":{"operationId":"CryptoPaymentLinksController_createPaymentLink","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCryptoPaymentLinkDto"}}}},"responses":{"201":{"description":"Crypto payment link created.","content":{"application/json":{"schema":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Payment Links"]},"get":{"operationId":"CryptoPaymentLinksController_listPaymentLinks","parameters":[{"name":"search","required":false,"in":"query","schema":{"maxLength":200,"example":"premium","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"example":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the previous page.","schema":{"maxLength":200,"example":"plink_123","type":"string"}}],"responses":{"200":{"description":"Crypto payment links listed.","content":{"application/json":{"schema":{"type":"object","required":["activeCount","data","pagination"],"properties":{"activeCount":{"type":"integer","example":2},"data":{"type":"array","items":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}},"pagination":{"type":"object","required":["returned","limit","hasMore","nextCursor"],"properties":{"returned":{"type":"integer","example":2},"limit":{"type":"integer","example":50},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Payment Links"]}},"/api/v1/crypto/payment-links/{id}":{"get":{"operationId":"CryptoPaymentLinksController_getPaymentLink","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto payment link fetched.","content":{"application/json":{"schema":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Payment Links"]},"patch":{"operationId":"CryptoPaymentLinksController_updatePaymentLink","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCryptoPaymentLinkDto"}}}},"responses":{"200":{"description":"Crypto payment link presentation and checkout settings updated. Amount, rail, slug and catalog price remain immutable.","content":{"application/json":{"schema":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Payment Links"]}},"/api/v1/crypto/payment-links/{id}/deactivate":{"post":{"operationId":"CryptoPaymentLinksController_deactivatePaymentLink","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Crypto payment link deactivated.","content":{"application/json":{"schema":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Crypto Payment Links"]}},"/api/v1/crypto/payment-links/public/{slug}":{"get":{"operationId":"PublicCryptoPaymentLinksController_getPaymentLink","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Public crypto payment link fetched as JSON or HTML.","content":{"application/json":{"schema":{"type":"object","required":["id","slug","title","status","assetCode","networkCode","amountExpected","pricingMode","createdAt","updatedAt","public"],"properties":{"id":{"type":"string","example":"plink_123"},"slug":{"type":"string","example":"store-order-123"},"title":{"type":"string","example":"Order payment"},"description":{"type":"string","nullable":true},"type":{"type":"string","example":"fixed"},"status":{"type":"string","example":"active"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.00"},"productPriceId":{"type":"string","nullable":true},"pricingMode":{"type":"string","example":"gross"},"invoiceLifetimeSeconds":{"type":"integer","nullable":true,"example":900},"checkout":{"type":"object","description":"Editable checkout presentation settings. Amount, rail, slug and catalog price are immutable after creation.","properties":{"itemName":{"type":"string","nullable":true},"itemDesc":{"type":"string","nullable":true},"itemCode":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"brandLogoUrl":{"type":"string","nullable":true},"brandAccentColor":{"type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"closeUrl":{"type":"string","nullable":true},"autoRedirect":{"type":"boolean"}}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"public":{"type":"object","required":["path","url","createInvoicePath","createInvoiceUrl"],"properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"createInvoicePath":{"type":"string"},"createInvoiceUrl":{"type":"string","format":"uri"}}}}}},"text/html":{"schema":{"type":"string","description":"Rendered HTML document. The response is not a JSON API payload.","example":"<!doctype html><html lang=\"en\">...</html>"}}}}},"tags":["Public Crypto Payment Links"]}},"/api/v1/crypto/payment-links/public/{slug}/invoices":{"post":{"operationId":"PublicCryptoPaymentLinksController_createInvoiceFromPaymentLink","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentLinkInvoiceDto"}}}},"responses":{"201":{"description":"Invoice created from a public crypto payment link.","content":{"application/json":{"schema":{"type":"object","required":["invoice","instructions","gatewayStatus","checkout"],"properties":{"invoice":{"type":"object","required":["publicId","invoiceReference","status"],"properties":{"publicId":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"status":{"type":"string","example":"pending"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"instructions":{"type":"object","description":"Runtime-backed payment route and wallet instructions.","additionalProperties":true},"gatewayStatus":{"type":"object","required":["code","isFinal"],"properties":{"code":{"type":"string","example":"waiting_payment"},"isFinal":{"type":"boolean","example":false}},"additionalProperties":true},"checkout":{"type":"object","required":["path"],"properties":{"path":{"type":"string"}}},"cryptomusCompatible":{"type":"object","description":"Compatibility fields for existing merchant integrations.","additionalProperties":true}}}}}}},"tags":["Public Crypto Payment Links"]}},"/api/v1/checkout/{id}":{"get":{"operationId":"CryptoCheckoutController_renderCheckout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Hosted checkout HTML document rendered successfully.","content":{"text/html":{"schema":{"type":"string","description":"Rendered HTML document. The response is not a JSON API payload.","example":"<!doctype html><html lang=\"en\">...</html>"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Hosted Checkout"]}},"/api/v1/checkout/{id}/status":{"get":{"operationId":"CryptoCheckoutController_getCheckoutStatus","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Hosted checkout status fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["checkoutPath","checkoutUrl","statusPath","statusUrl","resultPath","resultUrl","printPath","printUrl","merchant","branding","invoice","redirect","presentation","payments"],"properties":{"kind":{"type":"string","nullable":true},"checkoutPath":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"statusPath":{"type":"string"},"statusUrl":{"type":"string","format":"uri"},"resultPath":{"type":"string"},"resultUrl":{"type":"string","format":"uri"},"printPath":{"type":"string"},"printUrl":{"type":"string","format":"uri"},"merchant":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string"},"code":{"type":"string"}}},"branding":{"type":"object","additionalProperties":true},"invoice":{"type":"object","additionalProperties":true},"redirect":{"type":"object","additionalProperties":true},"presentation":{"type":"object","additionalProperties":true},"route":{"type":"object","nullable":true,"additionalProperties":true},"transfer":{"type":"object","nullable":true,"additionalProperties":true},"beneficiary":{"type":"object","nullable":true,"additionalProperties":true},"card":{"type":"object","nullable":true,"additionalProperties":true},"payments":{"type":"array","items":{"type":"object","required":["id","status","amountReceived","createdAt"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"amountReceived":{"type":"string"},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"explorerTxUrl":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Hosted Checkout"]}},"/api/v1/checkout/{id}/result":{"get":{"operationId":"CryptoCheckoutController_renderCheckoutResult","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Hosted checkout result HTML document rendered successfully.","content":{"text/html":{"schema":{"type":"string","description":"Rendered HTML document. The response is not a JSON API payload.","example":"<!doctype html><html lang=\"en\">...</html>"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Hosted Checkout"]}},"/api/v1/checkout/{id}/print":{"get":{"operationId":"CryptoCheckoutController_renderPrintableCheckout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Printable checkout HTML document rendered successfully.","content":{"text/html":{"schema":{"type":"string","description":"Rendered HTML document. The response is not a JSON API payload.","example":"<!doctype html><html lang=\"en\">...</html>"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Hosted Checkout"]}},"/api/v1/checkout/{id}/card/sandbox-pay":{"post":{"operationId":"CryptoCheckoutController_submitSandboxCardPayment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostedSandboxCardPaymentDto"}}}},"responses":{"200":{"description":"Sandbox card payment attempt recorded.","content":{"application/json":{"schema":{"type":"object","required":["approved","paymentId","paymentStatus","scenario","message"],"properties":{"approved":{"type":"boolean","example":true},"paymentId":{"type":"string","example":"pay_sandbox_123"},"paymentStatus":{"type":"string","example":"confirmed"},"scenario":{"type":"string","example":"approved"},"message":{"type":"string","example":"Sandbox card payment approved."}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"tags":["Hosted Checkout"]}},"/api/v1/crypto/watchers/detect":{"post":{"operationId":"CryptoWatchersController_detect","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectCryptoTransactionDto"}}}},"responses":{"201":{"description":"Admin HTTP detection is intentionally disabled; automatic watcher/provider adapters own detection."}},"security":[{"adminToken":[]}],"tags":["Crypto Watchers"]}},"/api/v1/crypto/watchers/confirm":{"post":{"operationId":"CryptoWatchersController_confirm","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmCryptoTransactionDto"}}}},"responses":{"200":{"description":"Admin HTTP confirmation is intentionally disabled; automatic watcher/provider adapters own confirmations."}},"security":[{"adminToken":[]}],"tags":["Crypto Watchers"]}},"/api/v1/crypto/sandbox/payments":{"post":{"operationId":"SandboxCryptoController_simulate","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateCryptoPaymentDto"}}}},"responses":{"201":{"description":"Sandbox crypto payment simulated."}},"security":[{"adminToken":[]}],"tags":["Crypto Sandbox"]}},"/api/v1/invoices":{"post":{"operationId":"InvoicesController_createInvoice","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"201":{"description":"Invoice created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]},"get":{"operationId":"InvoicesController_listInvoices","parameters":[{"name":"search","required":false,"in":"query","description":"Search merchant-scoped invoice ID, invoice reference or external reference.","schema":{"maxLength":120,"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/InvoiceStatus"}},{"name":"methodType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentMethodType"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USD","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"providerCode","required":false,"in":"query","schema":{"example":"native_tron","type":"string"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include sandbox provider records explicitly. Live merchant history excludes them by default.","schema":{"default":false,"type":"boolean"}},{"name":"createdFrom","required":false,"in":"query","schema":{"example":"2026-05-01T00:00:00.000Z","type":"string"}},{"name":"createdTo","required":false,"in":"query","schema":{"example":"2026-05-06T23:59:59.999Z","type":"string"}},{"name":"includeArchived","required":false,"in":"query","description":"Include terminal invoices archived by the merchant.","schema":{"default":false,"type":"boolean"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor returned by the previous page.","schema":{"maxLength":512,"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":50,"type":"number"}}],"responses":{"200":{"description":"Merchant invoice history fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["data","statusCounts","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}}}}},"statusCounts":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"pagination":{"type":"object","required":["limit","returned","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","example":50},"returned":{"type":"integer","example":1},"hasMore":{"type":"boolean","example":false},"nextCursor":{"type":"string","nullable":true}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/export":{"get":{"operationId":"InvoicesController_exportInvoices","parameters":[{"name":"search","required":false,"in":"query","description":"Search merchant-scoped invoice ID, invoice reference or external reference.","schema":{"maxLength":120,"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/InvoiceStatus"}},{"name":"methodType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentMethodType"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USD","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"providerCode","required":false,"in":"query","schema":{"example":"native_tron","type":"string"}},{"name":"includeSandbox","required":false,"in":"query","description":"Include sandbox provider records explicitly. Live merchant history excludes them by default.","schema":{"default":false,"type":"boolean"}},{"name":"createdFrom","required":false,"in":"query","schema":{"example":"2026-05-01T00:00:00.000Z","type":"string"}},{"name":"createdTo","required":false,"in":"query","schema":{"example":"2026-05-06T23:59:59.999Z","type":"string"}},{"name":"includeArchived","required":false,"in":"query","description":"Include terminal invoices archived by the merchant.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":5000,"default":5000,"example":5000,"type":"number"}}],"responses":{"200":{"description":"A bounded merchant invoice history CSV export with sensitive fields excluded.","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/{id}/detail":{"get":{"operationId":"InvoicesController_getInvoiceDetail","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant invoice detail, related payment facts and lifecycle timeline fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}},"productPrice":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"pricingMode":{"type":"string"},"priceType":{"type":"string"},"product":{"type":"object","nullable":true,"additionalProperties":true}}},"paymentMethod":{"type":"object","nullable":true,"additionalProperties":true},"route":{"type":"object","nullable":true,"additionalProperties":true,"properties":{"id":{"type":"string"},"assetCode":{"type":"string"},"networkCode":{"type":"string"},"address":{"type":"string"},"memoTag":{"type":"string","nullable":true},"confirmationsRequired":{"type":"integer"},"amountExpected":{"type":"string"},"providerCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"payments":{"type":"array","items":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"refunds":{"type":"array","items":{"type":"object","additionalProperties":true}},"disputes":{"type":"array","items":{"type":"object","additionalProperties":true}},"settlementItems":{"type":"array","items":{"type":"object","additionalProperties":true}},"recurringRuns":{"type":"array","items":{"type":"object","additionalProperties":true}},"audit":{"type":"array","items":{"type":"object","additionalProperties":true}},"timeline":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/{id}":{"get":{"operationId":"InvoicesController_getInvoice","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/{id}/payments":{"get":{"operationId":"InvoicesController_getInvoicePayments","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice payments fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"pay_123"},"invoiceId":{"type":"string","nullable":true},"invoiceReference":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string","example":"10.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"9.75"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"confirmed"},"txid":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"cryptoTxStatus":{"type":"string","nullable":true},"detectedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"reversedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/{id}/cancel":{"post":{"operationId":"InvoicesController_cancelInvoice","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelInvoiceDto"}}}},"responses":{"200":{"description":"Invoice cancelled successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/invoices/{id}/archive":{"post":{"operationId":"InvoicesController_archiveInvoice","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveInvoiceDto"}}}},"responses":{"200":{"description":"Terminal invoice archived successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","invoiceReference","methodType","currency","amountExpected","amountReceived","feeAmount","netAmount","status","createdAt","updatedAt","checkout"],"properties":{"id":{"type":"string","example":"inv_123"},"invoiceReference":{"type":"string","example":"ORDER-1001"},"externalReference":{"type":"string","nullable":true},"methodType":{"type":"string","example":"crypto"},"providerCode":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountExpected":{"type":"string","example":"10.25"},"amountReceived":{"type":"string","example":"0.00"},"feeAmount":{"type":"string","example":"0.25"},"netAmount":{"type":"string","example":"10.00"},"exchangeRate":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"metadata":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkout":{"type":"object","required":["url","statusUrl","resultUrl","printUrl"],"properties":{"url":{"type":"string","format":"uri"},"statusUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"},"printUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"tags":["Invoices"]}},"/api/v1/admin/invoices/expiring":{"get":{"operationId":"AdminInvoiceLifecycleController_listExpiring","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}},{"name":"lookaheadMinutes","required":false,"in":"query","schema":{"minimum":1,"maximum":1440,"example":120,"type":"number"}}],"responses":{"200":{"description":"Expiring invoices fetched successfully."}},"security":[{"adminToken":[]}],"summary":"List open invoices that are overdue or close to expiring","tags":["Admin Invoices"]}},"/api/v1/admin/invoices/expire-due":{"post":{"operationId":"AdminInvoiceLifecycleController_expireDue","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpireDueInvoicesDto"}}}},"responses":{"200":{"description":"Due invoices expired successfully."}},"security":[{"adminToken":[]}],"summary":"Expire due invoices immediately and emit merchant webhooks","tags":["Admin Invoices"]}},"/api/v1/fiat/sandbox/spei/payments":{"post":{"operationId":"SandboxSpeiController_simulate","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateSpeiPaymentDto"}}}},"responses":{"201":{"description":"Sandbox SPEI payment simulated."}},"security":[{"adminToken":[]}],"tags":["Fiat Sandbox"]}},"/api/v1/fiat/sandbox/cards/payments":{"post":{"operationId":"SandboxCardController_simulate","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateCardPaymentDto"}}}},"responses":{"201":{"description":"Sandbox card payment simulated."}},"security":[{"adminToken":[]}],"tags":["Fiat Sandbox"]}},"/api/v1/fiat/invoices/{id}/instructions":{"get":{"operationId":"FiatSpeiInstructionsController_getInstructions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Fiat transfer instructions fetched successfully."}},"security":[{"merchantApiKey":[]}],"tags":["Fiat SPEI"]}},"/api/v1/admin/fiat/providers/stp":{"get":{"operationId":"AdminStpProviderController_getStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"STP provider status fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Fiat Providers"]}},"/api/v1/admin/fiat/providers/stp/accounts":{"get":{"operationId":"AdminStpProviderController_listAccounts","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"currency","required":false,"in":"query","schema":{"example":"MXN","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"STP collection accounts fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Fiat Providers"]},"post":{"operationId":"AdminStpProviderController_registerAccount","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStpFiatAccountDto"}}}},"responses":{"201":{"description":"STP collection account registered successfully."}},"security":[{"adminToken":[]}],"tags":["Fiat Providers"]}},"/api/v1/admin/settlements/summary":{"get":{"operationId":"AdminSettlementsController_getSummary","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"Settlement summary fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["outstanding","recentBatches"],"properties":{"outstanding":{"type":"array","items":{"type":"object","required":["merchantId","merchant","channel","currency","paymentCount","grossAmount","feeAmount","netAmount"],"properties":{"merchantId":{"type":"string"},"merchant":{"type":"string"},"channel":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"paymentCount":{"type":"integer"},"grossAmount":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"}}}},"recentBatches":{"type":"array","items":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Inspect outstanding confirmed payments and recent settlement batches","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/eligible-payments":{"get":{"operationId":"AdminSettlementsController_listEligiblePayments","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"Eligible settlement payments fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","merchant","channel","methodType","currency","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"merchant":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"channel":{"type":"string"},"methodType":{"type":"string"},"currency":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"txid":{"type":"string","nullable":true}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List confirmed payments that are still pending settlement","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/batches":{"get":{"operationId":"AdminSettlementsController_listBatches","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementStatus"}},{"name":"approvalStatus","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementApprovalStatus"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Settlement batches fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement batches with their included payments","tags":["Admin Settlements"]},"post":{"operationId":"AdminSettlementsController_createBatch","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettlementBatchDto"}}}},"responses":{"200":{"description":"Settlement batch created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Create a settlement batch from confirmed unsettled payments","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/executions":{"get":{"operationId":"AdminSettlementsController_listExecutions","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"batchId","required":false,"in":"query","schema":{"example":"settlement-batch-public-id","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementExecutionStatus"}},{"name":"kind","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementExecutionKind"}},{"name":"approvalStatus","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementApprovalStatus"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Settlement executions fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement executions for treasury sweeps or merchant payouts","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/batches/{id}/executions":{"post":{"operationId":"AdminSettlementsController_createExecution","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettlementExecutionDto"}}}},"responses":{"200":{"description":"Settlement execution created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Plan a settlement execution such as treasury sweep or merchant payout","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/batches/{id}/status":{"post":{"operationId":"AdminSettlementsController_transitionBatchStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionSettlementBatchStatusDto"}}}},"responses":{"200":{"description":"Settlement batch status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Advance a settlement batch to processing, settled, failed or cancelled","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/executions/{id}/status":{"post":{"operationId":"AdminSettlementsController_transitionExecutionStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionSettlementExecutionStatusDto"}}}},"responses":{"200":{"description":"Settlement execution status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Advance a settlement execution through broadcasted, confirmed, failed or cancelled","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/batches/{id}/approval":{"post":{"operationId":"AdminSettlementApprovalsController_decideBatchApproval","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideSettlementApprovalDto"}}}},"responses":{"200":{"description":"Settlement batch approval decision registered successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Approve or reject a settlement batch held by approval policy","tags":["Admin Settlement Approvals"]}},"/api/v1/admin/settlements/executions/{id}/approval":{"post":{"operationId":"AdminSettlementApprovalsController_decideExecutionApproval","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideSettlementApprovalDto"}}}},"responses":{"200":{"description":"Settlement execution approval decision registered successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Approve or reject a settlement execution held by approval policy","tags":["Admin Settlement Approvals"]}},"/api/v1/admin/settlements/approval-policies":{"get":{"operationId":"AdminSettlementApprovalPoliciesController_listPolicies","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"subjectType","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementApprovalSubjectType"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Settlement approval policies fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","merchant","name","subjectType","channel","currency","assetCode","networkCode","amountThreshold","requiredRole","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sapol_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"name":{"type":"string","example":"High value approval"},"subjectType":{"type":"string","example":"batch"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountThreshold":{"type":"string","example":"1000.00"},"requiredRole":{"type":"string","example":"ops_admin"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement approval policies by merchant, scope or subject","tags":["Admin Settlement Approval Policies"]},"post":{"operationId":"AdminSettlementApprovalPoliciesController_createPolicy","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettlementApprovalPolicyDto"}}}},"responses":{"200":{"description":"Settlement approval policy created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","name","subjectType","channel","currency","assetCode","networkCode","amountThreshold","requiredRole","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sapol_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"name":{"type":"string","example":"High value approval"},"subjectType":{"type":"string","example":"batch"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountThreshold":{"type":"string","example":"1000.00"},"requiredRole":{"type":"string","example":"ops_admin"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Create a settlement approval policy to hold batches or executions over a threshold","tags":["Admin Settlement Approval Policies"]}},"/api/v1/admin/settlements/approval-policies/{id}/status":{"post":{"operationId":"AdminSettlementApprovalPoliciesController_updateStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettlementApprovalPolicyStatusDto"}}}},"responses":{"200":{"description":"Settlement approval policy updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","name","subjectType","channel","currency","assetCode","networkCode","amountThreshold","requiredRole","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sapol_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"name":{"type":"string","example":"High value approval"},"subjectType":{"type":"string","example":"batch"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amountThreshold":{"type":"string","example":"1000.00"},"requiredRole":{"type":"string","example":"ops_admin"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Activate or deactivate a settlement approval policy","tags":["Admin Settlement Approval Policies"]}},"/api/v1/admin/settlements/destinations":{"get":{"operationId":"AdminSettlementDestinationsController_listDestinations","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Settlement destinations fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","merchant","label","channel","type","currency","assetCode","networkCode","address","memoTag","accountRef","providerCode","custodyType","exchangeCode","addressTagLabel","destinationNotes","isDefault","isActive","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sdst_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"label":{"type":"string","example":"Treasury wallet"},"channel":{"type":"string","example":"crypto"},"type":{"type":"string","example":"crypto_address"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"accountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"custodyType":{"type":"string","nullable":true},"exchangeCode":{"type":"string","nullable":true},"addressTagLabel":{"type":"string","nullable":true},"destinationNotes":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"wallet":{"type":"object","nullable":true,"required":["id","label","address","merchantId"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"},"merchantId":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement destinations available for merchant payouts","tags":["Admin Settlements"]},"post":{"operationId":"AdminSettlementDestinationsController_createDestination","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettlementDestinationDto"}}}},"responses":{"200":{"description":"Settlement destination created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","label","channel","type","currency","assetCode","networkCode","address","memoTag","accountRef","providerCode","custodyType","exchangeCode","addressTagLabel","destinationNotes","isDefault","isActive","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sdst_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"label":{"type":"string","example":"Treasury wallet"},"channel":{"type":"string","example":"crypto"},"type":{"type":"string","example":"crypto_address"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"accountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"custodyType":{"type":"string","nullable":true},"exchangeCode":{"type":"string","nullable":true},"addressTagLabel":{"type":"string","nullable":true},"destinationNotes":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"wallet":{"type":"object","nullable":true,"required":["id","label","address","merchantId"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"},"merchantId":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Create a reusable settlement destination for a merchant","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/destinations/{id}/status":{"post":{"operationId":"AdminSettlementDestinationsController_updateStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettlementDestinationStatusDto"}}}},"responses":{"200":{"description":"Settlement destination status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","label","channel","type","currency","assetCode","networkCode","address","memoTag","accountRef","providerCode","custodyType","exchangeCode","addressTagLabel","destinationNotes","isDefault","isActive","wallet","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sdst_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"label":{"type":"string","example":"Treasury wallet"},"channel":{"type":"string","example":"crypto"},"type":{"type":"string","example":"crypto_address"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"memoTag":{"type":"string","nullable":true},"accountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"custodyType":{"type":"string","nullable":true},"exchangeCode":{"type":"string","nullable":true},"addressTagLabel":{"type":"string","nullable":true},"destinationNotes":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"},"wallet":{"type":"object","nullable":true,"required":["id","label","address","merchantId"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"},"merchantId":{"type":"string","nullable":true}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Activate, deactivate or mark a settlement destination as default","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/profiles":{"get":{"operationId":"AdminSettlementProfilesController_listProfiles","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"merchantId","required":false,"in":"query","schema":{"example":"merchant-public-id","type":"string"}},{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"mode","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementProfileMode"}},{"name":"isActive","required":false,"in":"query","schema":{"example":true,"type":"boolean"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Settlement profiles fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","merchantId","merchant","destinationId","destination","sourceWallet","channel","currency","assetCode","networkCode","mode","executionKind","minNetAmount","maxPaymentsPerBatch","cooldownMinutes","isActive","lastTriggeredAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sprof_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"destinationId":{"type":"string","example":"sdst_123"},"destination":{"type":"object","required":["id","label","type"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"sourceWallet":{"type":"object","nullable":true,"required":["id","label","address"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"mode":{"type":"string","example":"manual_review"},"executionKind":{"type":"string","example":"treasury_sweep"},"minNetAmount":{"type":"string","example":"100.00"},"maxPaymentsPerBatch":{"type":"integer","example":100},"cooldownMinutes":{"type":"integer","example":60},"isActive":{"type":"boolean"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement automation profiles for merchants","tags":["Admin Settlements"]},"post":{"operationId":"AdminSettlementProfilesController_createProfile","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettlementProfileDto"}}}},"responses":{"200":{"description":"Settlement profile created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","destinationId","destination","sourceWallet","channel","currency","assetCode","networkCode","mode","executionKind","minNetAmount","maxPaymentsPerBatch","cooldownMinutes","isActive","lastTriggeredAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sprof_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"destinationId":{"type":"string","example":"sdst_123"},"destination":{"type":"object","required":["id","label","type"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"sourceWallet":{"type":"object","nullable":true,"required":["id","label","address"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"mode":{"type":"string","example":"manual_review"},"executionKind":{"type":"string","example":"treasury_sweep"},"minNetAmount":{"type":"string","example":"100.00"},"maxPaymentsPerBatch":{"type":"integer","example":100},"cooldownMinutes":{"type":"integer","example":60},"isActive":{"type":"boolean"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Create a settlement automation profile with threshold and destination rules","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/profiles/{id}/status":{"post":{"operationId":"AdminSettlementProfilesController_updateStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettlementProfileStatusDto"}}}},"responses":{"200":{"description":"Settlement profile status updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","merchant","destinationId","destination","sourceWallet","channel","currency","assetCode","networkCode","mode","executionKind","minNetAmount","maxPaymentsPerBatch","cooldownMinutes","isActive","lastTriggeredAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sprof_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"destinationId":{"type":"string","example":"sdst_123"},"destination":{"type":"object","required":["id","label","type"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"sourceWallet":{"type":"object","nullable":true,"required":["id","label","address"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"mode":{"type":"string","example":"manual_review"},"executionKind":{"type":"string","example":"treasury_sweep"},"minNetAmount":{"type":"string","example":"100.00"},"maxPaymentsPerBatch":{"type":"integer","example":100},"cooldownMinutes":{"type":"integer","example":60},"isActive":{"type":"boolean"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Activate or deactivate a settlement automation profile","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/profiles/{id}/run":{"post":{"operationId":"AdminSettlementProfilesController_runProfile","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSettlementAutomationDto"}}}},"responses":{"200":{"description":"Settlement profile automation executed successfully.","content":{"application/json":{"schema":{"type":"object","required":["profile","automation"],"properties":{"profile":{"type":"object","required":["id","merchantId","merchant","destinationId","destination","sourceWallet","channel","currency","assetCode","networkCode","mode","executionKind","minNetAmount","maxPaymentsPerBatch","cooldownMinutes","isActive","lastTriggeredAt","createdAt","updatedAt"],"properties":{"id":{"type":"string","example":"sprof_123"},"merchantId":{"type":"string","example":"mrc_123"},"merchant":{"type":"string","example":"Example Merchant"},"destinationId":{"type":"string","example":"sdst_123"},"destination":{"type":"object","required":["id","label","type"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"sourceWallet":{"type":"object","nullable":true,"required":["id","label","address"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"mode":{"type":"string","example":"manual_review"},"executionKind":{"type":"string","example":"treasury_sweep"},"minNetAmount":{"type":"string","example":"100.00"},"maxPaymentsPerBatch":{"type":"integer","example":100},"cooldownMinutes":{"type":"integer","example":60},"isActive":{"type":"boolean"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"automation":{"type":"object","required":["scannedProfiles","executedProfiles","results"],"properties":{"scannedProfiles":{"type":"integer","example":1},"executedProfiles":{"type":"integer","example":0},"results":{"type":"array","items":{"type":"object","required":["profileId","merchant","mode","action"],"properties":{"profileId":{"type":"string","example":"sprof_123"},"merchant":{"type":"string","example":"Example Merchant"},"mode":{"type":"string","example":"manual_review"},"action":{"type":"string","example":"skipped"},"reason":{"type":"string","nullable":true},"cooldownUntil":{"type":"string","format":"date-time","nullable":true},"batchId":{"type":"string","nullable":true},"paymentCount":{"type":"integer"},"netAmount":{"type":"string","nullable":true},"minNetAmount":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"destination":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"batch":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}},"nullable":true},"execution":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"nullable":true}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Run a settlement profile immediately or as a dry-run preview","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/automation/run":{"post":{"operationId":"AdminSettlementAutomationController_runAutomation","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSettlementAutomationDto"}}}},"responses":{"200":{"description":"Settlement automation finished successfully.","content":{"application/json":{"schema":{"type":"object","required":["scannedProfiles","executedProfiles","results"],"properties":{"scannedProfiles":{"type":"integer","example":1},"executedProfiles":{"type":"integer","example":0},"results":{"type":"array","items":{"type":"object","required":["profileId","merchant","mode","action"],"properties":{"profileId":{"type":"string","example":"sprof_123"},"merchant":{"type":"string","example":"Example Merchant"},"mode":{"type":"string","example":"manual_review"},"action":{"type":"string","example":"skipped"},"reason":{"type":"string","nullable":true},"cooldownUntil":{"type":"string","format":"date-time","nullable":true},"batchId":{"type":"string","nullable":true},"paymentCount":{"type":"integer"},"netAmount":{"type":"string","nullable":true},"minNetAmount":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"destination":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}}},"batch":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}},"nullable":true},"execution":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Run all active settlement automation profiles or preview them with dry-run","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/processors":{"get":{"operationId":"AdminSettlementProcessorsController_listProcessors","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Settlement processors fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["providerCode","providerName","enabled"],"properties":{"providerCode":{"type":"string","example":"manual_payout"},"providerName":{"type":"string","example":"Manual payout"},"enabled":{"type":"boolean"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"List settlement execution processors and whether they are enabled","tags":["Admin Settlements"]}},"/api/v1/admin/settlements/processors/run":{"post":{"operationId":"AdminSettlementProcessorsController_run","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSettlementProcessorsDto"}}}},"responses":{"200":{"description":"Settlement execution processors finished successfully.","content":{"application/json":{"schema":{"type":"object","required":["startedAt","processors","plannedCount","broadcastedCount","results"],"properties":{"startedAt":{"type":"string","format":"date-time"},"processors":{"type":"array","items":{"type":"object","required":["providerCode","providerName","enabled"],"properties":{"providerCode":{"type":"string","example":"manual_payout"},"providerName":{"type":"string","example":"Manual payout"},"enabled":{"type":"boolean"}}}},"plannedCount":{"type":"integer"},"broadcastedCount":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["executionId","providerCode","action"],"properties":{"executionId":{"type":"string"},"providerCode":{"type":"string"},"action":{"type":"string","example":"skipped"},"reason":{"type":"string","nullable":true},"result":{"type":"object","nullable":true,"additionalProperties":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"summary":"Run settlement execution processors to dispatch or confirm planned executions","tags":["Admin Settlements"]}},"/api/v1/payouts/services":{"get":{"operationId":"MerchantPayoutsController_listServices","parameters":[],"responses":{"200":{"description":"Payout services fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","custodyModel","liveBroadcastAvailable","warning","services"],"properties":{"status":{"type":"string","example":"ok"},"custodyModel":{"type":"string","example":"non_custodial_gateway"},"liveBroadcastAvailable":{"type":"boolean","example":false},"warning":{"type":"string"},"services":{"type":"array","items":{"type":"object","required":["providerCode","providerName","enabled","executionMode","liveBroadcastAvailable"],"properties":{"providerCode":{"type":"string"},"providerName":{"type":"string"},"enabled":{"type":"boolean"},"executionMode":{"type":"string"},"liveBroadcastAvailable":{"type":"boolean"}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"List payout processors and current live broadcast readiness","tags":["Payouts"]}},"/api/v1/payouts/batches":{"get":{"operationId":"MerchantPayoutsController_listPayoutBatches","parameters":[{"name":"channel","required":false,"in":"query","schema":{"$ref":"#/components/schemas/PaymentChannel"}},{"name":"currency","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"assetCode","required":false,"in":"query","schema":{"example":"USDT","type":"string"}},{"name":"networkCode","required":false,"in":"query","schema":{"example":"TRC20","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementStatus"}},{"name":"approvalStatus","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementApprovalStatus"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Merchant payout batches fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","liveBroadcastAvailable","data","pagination"],"properties":{"status":{"type":"string","example":"ok"},"liveBroadcastAvailable":{"type":"boolean","example":false},"data":{"type":"array","items":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}},"pagination":{"type":"object","required":["returned","limit"],"properties":{"returned":{"type":"integer"},"limit":{"type":"integer"}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"List owner-scoped payout settlement batches without exposing other merchants","tags":["Payouts"]},"post":{"operationId":"MerchantPayoutsController_createPayoutBatch","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantPayoutBatchDto"}}}},"responses":{"201":{"description":"Merchant payout batch planned idempotently. No funds are broadcast automatically.","content":{"application/json":{"schema":{"type":"object","required":["status","liveBroadcastAvailable","warning","batch"],"properties":{"status":{"type":"string","example":"planned"},"liveBroadcastAvailable":{"type":"boolean","example":false},"warning":{"type":"string"},"batch":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Create a merchant payout batch plan from confirmed unsettled payments","tags":["Payouts"]}},"/api/v1/payouts/batches/{id}":{"get":{"operationId":"MerchantPayoutsController_getPayoutBatch","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant payout batch fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","merchantId","channel","currency","status","paymentCount","grossAmount","feeAmount","netAmount","approval","createdAt","executions","items"],"properties":{"id":{"type":"string","example":"sbat_123"},"merchantId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string","example":"pending"},"paymentCount":{"type":"integer","example":2},"grossAmount":{"type":"string","example":"100.00"},"feeAmount":{"type":"string","example":"1.00"},"netAmount":{"type":"string","example":"99.00"},"externalReference":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"settledAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"executions":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"items":{"type":"array","items":{"type":"object","required":["id","paymentId","amountReceived","feeAmount","netAmount"],"properties":{"id":{"type":"string"},"paymentId":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"merchant":{"type":"string"},"amountReceived":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Get one owner-scoped payout settlement batch","tags":["Payouts"]}},"/api/v1/payouts":{"get":{"operationId":"MerchantPayoutsController_listPayouts","parameters":[{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementExecutionStatus"}},{"name":"approvalStatus","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SettlementApprovalStatus"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"example":20,"type":"number"}}],"responses":{"200":{"description":"Merchant payouts fetched successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"List owner-scoped merchant payout executions","tags":["Payouts"]}},"/api/v1/payouts/{id}":{"get":{"operationId":"MerchantPayoutsController_getPayout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant payout fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","batchId","kind","channel","currency","amount","status","approval","txid","plannedAt","createdAt"],"properties":{"id":{"type":"string","example":"sexec_123"},"batchId":{"type":"string","nullable":true},"merchant":{"type":"string","nullable":true},"kind":{"type":"string","example":"merchant_payout"},"channel":{"type":"string","example":"crypto"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"amount":{"type":"string","example":"90.00"},"status":{"type":"string","example":"planned"},"sourceWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationWallet":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"}}},"destinationAddress":{"type":"string","nullable":true},"destinationMemoTag":{"type":"string","nullable":true},"destinationAccountRef":{"type":"string","nullable":true},"providerCode":{"type":"string","nullable":true},"approval":{"type":"object","required":["status","requiredRole","requestedAt","decidedAt","note"],"properties":{"status":{"type":"string","example":"not_required"},"requiredRole":{"type":"string","nullable":true},"requestedAt":{"type":"string","format":"date-time","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string","nullable":true},"policy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"requiredRole":{"type":"string"}}},"decidedBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string"}}}}},"txid":{"type":"string","nullable":true},"externalReference":{"type":"string","nullable":true},"plannedAt":{"type":"string","format":"date-time"},"broadcastedAt":{"type":"string","format":"date-time","nullable":true},"confirmedAt":{"type":"string","format":"date-time","nullable":true},"failedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"merchantApiKey":[]}],"summary":"Get one owner-scoped merchant payout execution","tags":["Payouts"]}},"/api/v1/admin/console":{"get":{"operationId":"AdminConsoleController_renderConsole","parameters":[],"responses":{"200":{"description":""}},"tags":["AdminConsole"]}},"/api/v1/admin/dashboard/summary":{"get":{"operationId":"AdminDashboardController_getSummary","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Admin dashboard summary fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["metrics","invoiceStatusCounts","paymentStatusCounts","recentInvoices","recentPayments"],"properties":{"metrics":{"type":"object","required":["merchantsCount","activeFeeRules","activeCryptoRoutes","openCryptoInvoices","unsettledConfirmedPayments","openSettlementBatches","activeSettlementExecutions","activeSettlementProfiles","pendingBatchApprovals","pendingExecutionApprovals","openRefunds","openDisputes"],"properties":{"merchantsCount":{"type":"integer"},"activeFeeRules":{"type":"integer"},"activeCryptoRoutes":{"type":"integer"},"openCryptoInvoices":{"type":"integer"},"unsettledConfirmedPayments":{"type":"integer"},"openSettlementBatches":{"type":"integer"},"activeSettlementExecutions":{"type":"integer"},"activeSettlementProfiles":{"type":"integer"},"pendingBatchApprovals":{"type":"integer"},"pendingExecutionApprovals":{"type":"integer"},"openRefunds":{"type":"integer"},"openDisputes":{"type":"integer"}}},"invoiceStatusCounts":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"paymentStatusCounts":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"recentInvoices":{"type":"array","items":{"type":"object","required":["id","reference","merchant","amountExpected","amountReceived","status","checkoutReady","createdAt"],"properties":{"id":{"type":"string"},"reference":{"type":"string"},"merchant":{"type":"string"},"amountExpected":{"type":"string"},"amountReceived":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string"},"checkoutReady":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}},"recentPayments":{"type":"array","items":{"type":"object","required":["id","merchant","amountReceived","status","confirmations","createdAt"],"properties":{"id":{"type":"string"},"merchant":{"type":"string"},"invoiceId":{"type":"string","nullable":true},"amountReceived":{"type":"string"},"assetCode":{"type":"string","nullable":true},"networkCode":{"type":"string","nullable":true},"status":{"type":"string"},"txid":{"type":"string","nullable":true},"confirmations":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Admin Dashboard"]}},"/api/v1/admin/readiness":{"get":{"operationId":"AdminReadinessController_getReadinessReport","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gateway readiness report fetched successfully.","content":{"application/json":{"schema":{"type":"object","required":["status","generatedAt","summary","checks"],"properties":{"status":{"type":"string","example":"ready_with_warnings"},"generatedAt":{"type":"string","format":"date-time"},"summary":{"type":"object","additionalProperties":true},"checks":{"type":"array","items":{"type":"object","required":["key","status","message"],"properties":{"key":{"type":"string"},"status":{"type":"string","example":"pass"},"message":{"type":"string"},"recommendation":{"type":"string","nullable":true}}}}}}}}},"400":{"description":"Request validation or business-rule error.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Authentication is required or invalid.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"403":{"description":"The authenticated principal lacks the required scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"The requested resource was not found in the current scope.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","path","timestamp","message"],"properties":{"statusCode":{"type":"integer","example":400},"path":{"type":"string","example":"/api/v1/invoices"},"timestamp":{"type":"string","format":"date-time"},"message":{"oneOf":[{"type":"string","example":"Request validation failed"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","nullable":true}}}}}}},"security":[{"adminToken":[]}],"tags":["Admin Readiness"]}},"/api/v1/admin/auth/me":{"get":{"operationId":"AdminUsersController_me","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current admin context fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/api/v1/admin/users":{"get":{"operationId":"AdminUsersController_listUsers","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Admin users fetched successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]},"post":{"operationId":"AdminUsersController_createUser","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdminUserDto"}}}},"responses":{"201":{"description":"Admin user created successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/api/v1/admin/users/{id}/status":{"post":{"operationId":"AdminUsersController_updateUserStatus","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAdminUserStatusDto"}}}},"responses":{"200":{"description":"Admin user status updated successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/api/v1/admin/users/{id}/api-keys":{"post":{"operationId":"AdminUsersController_createApiKey","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdminApiKeyDto"}}}},"responses":{"201":{"description":"Admin API key created successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/api/v1/admin/api-keys/{id}/revoke":{"post":{"operationId":"AdminUsersController_revokeApiKey","parameters":[{"name":"x-admin-token","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Admin API key revoked successfully."}},"security":[{"adminToken":[]}],"tags":["Admin Auth"]}},"/health":{"get":{"operationId":"HealthController_getHealth","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}}},"info":{"title":"ZemiaxPay API","description":"Crypto-first payment gateway, business wallet and payout operations with strong domain boundaries.","version":"1.0.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"merchantApiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"adminToken":{"type":"apiKey","in":"header","name":"x-admin-token"}},"schemas":{"FeeRuleScope":{"type":"string","enum":["merchant","plan","method","network"]},"PaymentMethodType":{"type":"string","enum":["spei","clabe","card","usdt_trc20","usdt_bep20","usdt_erc20","btc","ltc","lightning","eth","usdc_polygon","sol","trx"]},"CreateFeeRuleDto":{"type":"object","properties":{"name":{"type":"string","example":"USDT TRC20 Growth Plan Fee"},"merchantId":{"type":"string","example":"merchant-public-id"},"scope":{"allOf":[{"$ref":"#/components/schemas/FeeRuleScope"}]},"methodType":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodType"}]},"networkCode":{"type":"string","example":"TRC20"},"providerCode":{"type":"string","example":"sandbox_crypto"},"planCode":{"type":"string","example":"growth"},"currency":{"type":"string","example":"USDT"},"percentageBps":{"type":"number","example":150},"fixedFee":{"type":"string","example":"0.25"},"minFee":{"type":"string","example":"0.50"},"isActive":{"type":"boolean","example":true}},"required":["name","scope"]},"FeeQuoteDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"methodType":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodType"}]},"amount":{"type":"string","example":"100.00"},"currency":{"type":"string","example":"USDT"},"pricingMode":{"type":"string","enum":["gross","net_target"]},"networkCode":{"type":"string","example":"TRC20"},"providerCode":{"type":"string","example":"sandbox_crypto"}},"required":["methodType","amount","currency"]},"CreateApiKeyDto":{"type":"object","properties":{"name":{"type":"string","example":"primary-server-key"},"expiresAt":{"type":"string","example":"2026-12-31T23:59:59.000Z"},"scopes":{"type":"array","example":["wallet:read","payout:read"],"description":"Optional scope restriction for this merchant API key. Omit to keep backward-compatible full access.","items":{"type":"string","enum":["wallet:read","wallet:write","payment:read","payment:write","payout:read","payout:write","invoice:read","invoice:write","webhook:read","webhook:write","api_key:read","api_key:write","settings:read","settings:write","team:read","team:write","customer:read","customer:write","product:read","product:write"]}}},"required":["name"]},"RevokeMerchantApiKeyDto":{"type":"object","properties":{"reason":{"type":"string","example":"Key rotated after operator request"}}},"CreateMerchantDto":{"type":"object","properties":{"code":{"type":"string","example":"merchant_store"},"name":{"type":"string","example":"Merchant Store SA de CV"},"legalName":{"type":"string","example":"Merchant Store Legal Name SA de CV"},"planCode":{"type":"string","example":"growth"},"metadata":{"type":"object","additionalProperties":true}},"required":["code","name"]},"PaymentStatus":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"]},"RegisterPaymentDto":{"type":"object","properties":{"invoiceId":{"type":"string","example":"c6fe4f0d-3f43-4f7a-8f90-8f8f86d0cc31"},"methodType":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodType"}]},"amountReceived":{"type":"string","example":"100.00"},"currency":{"type":"string","example":"MXN"},"status":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"],"default":"detected"},"providerCode":{"type":"string","example":"stp"},"networkCode":{"type":"string","example":"TRON"},"assetCode":{"type":"string","example":"USDT"},"externalReference":{"type":"string","example":"external-op-123"},"txid":{"type":"string","example":"abc123txid"},"address":{"type":"string","example":"TJxL4v5..."},"memoTag":{"type":"string","example":"123456"},"metadata":{"type":"object","additionalProperties":true}},"required":["invoiceId","methodType","amountReceived","currency"]},"TransitionPaymentStatusDto":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/PaymentStatus"}]},"metadata":{"type":"object","additionalProperties":true}},"required":["status"]},"LedgerEntryDirection":{"type":"string","enum":["credit","debit"]},"LedgerEntryType":{"type":"string","enum":["payment_credit","refund_debit","dispute_debit","settlement_debit","adjustment_credit","adjustment_debit"]},"LedgerEntryStatus":{"type":"string","enum":["posted","voided"]},"BackfillLedgerDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"dryRun":{"type":"boolean","example":true},"limit":{"type":"number","example":500,"minimum":1,"maximum":2000}}},"ConfigureWebhookEndpointDto":{"type":"object","properties":{"url":{"type":"string","example":"https://merchant.example/webhooks/payments"},"description":{"type":"string","example":"Primary billing webhook"},"signingSecret":{"type":"string","example":"whsec_custom_shared_secret"},"subscribedEvents":{"type":"array","description":"When omitted or empty, the endpoint receives every merchant webhook event.","example":["invoice.status.changed","payment.registered"],"items":{"type":"string","enum":["invoice.created","invoice.status.changed","payment.registered","payment.status.changed","refund.created","refund.status.changed","dispute.created","dispute.evidence.submitted","dispute.status.changed","settlement.batch.created","settlement.batch.status.changed","settlement.batch.approval.changed","settlement.execution.created","settlement.execution.status.changed","settlement.execution.approval.changed","payout.created","payout.status.changed","payout.approval.changed","settlement.destination.created","settlement.destination.status.changed","settlement.profile.created","settlement.profile.status.changed","webhook.test"]}},"replaceExisting":{"type":"boolean","example":true,"description":"Default true keeps the legacy single-active-endpoint behavior. Set false to add another active endpoint."},"metadata":{"type":"object","additionalProperties":true}},"required":["url"]},"UpdateWebhookEndpointStatusDto":{"type":"object","properties":{"isActive":{"type":"boolean","example":true}},"required":["isActive"]},"RotateWebhookEndpointSecretDto":{"type":"object","properties":{"signingSecret":{"type":"string","example":"whsec_custom_rotated_secret","description":"When omitted, the gateway generates a new strong signing secret."}}},"WebhookTestDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"c6fe4f0d-3f43-4f7a-8f90-8f8f86d0cc31"},"eventType":{"type":"string","example":"merchant.updated"},"endpointUrlOverride":{"type":"string","example":"https://merchant.example/webhooks/payments"},"signingSecretOverride":{"type":"string","example":"whsec_customsecret"},"payload":{"type":"object","additionalProperties":true}},"required":["merchantId"]},"WebhookDeliveryStatus":{"type":"string","enum":["pending","processing","delivered","failed","dead"]},"MerchantWebhookTestDto":{"type":"object","properties":{"eventType":{"type":"string","example":"webhook.test"},"payload":{"type":"object","additionalProperties":true}}},"RefundStatus":{"type":"string","enum":["requested","approved","processing","succeeded","failed","rejected","cancelled"]},"CreateRefundDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"payment-public-id"},"amount":{"type":"string","example":"10.50","description":"When omitted, the gateway refunds the remaining refundable amount."},"reason":{"type":"string","example":"customer_requested"},"externalReference":{"type":"string","example":"refund-order-123"},"destinationAddress":{"type":"string","example":"TQm...refundAddress","description":"Required operational detail for manual crypto refunds."},"memoTag":{"type":"string","example":"memo-or-tag-if-needed"},"metadata":{"type":"object","additionalProperties":true}},"required":["paymentId"]},"TransitionRefundStatusDto":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/RefundStatus"}]},"providerRefundId":{"type":"string","example":"provider_refund_123"},"externalReference":{"type":"string","example":"txid-or-processor-reference"},"metadata":{"type":"object","additionalProperties":true}},"required":["status"]},"DisputeStatus":{"type":"string","enum":["inquiry","needs_response","under_review","won","lost","accepted","closed"]},"SubmitDisputeEvidenceDto":{"type":"object","properties":{"evidence":{"type":"object","additionalProperties":true,"example":{"customerEmail":"buyer@example.com","orderReference":"order-123","receiptUrl":"https://merchant.example/receipts/order-123"}},"note":{"type":"string","example":"Evidence submitted from merchant portal"}},"required":["evidence"]},"CreateDisputeDto":{"type":"object","properties":{"paymentId":{"type":"string","example":"payment-public-id"},"amount":{"type":"string","example":"100.00"},"providerDisputeId":{"type":"string","example":"dp_provider_123"},"providerCode":{"type":"string","example":"conekta"},"status":{"example":"needs_response","allOf":[{"$ref":"#/components/schemas/DisputeStatus"}]},"reason":{"type":"string","example":"fraudulent"},"evidenceDueAt":{"type":"string","example":"2026-05-01T00:00:00.000Z"},"metadata":{"type":"object","additionalProperties":true}},"required":["paymentId","amount"]},"TransitionDisputeStatusDto":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/DisputeStatus"}]},"metadata":{"type":"object","additionalProperties":true},"note":{"type":"string","example":"Provider decided dispute in merchant favor."}},"required":["status"]},"AcceptMerchantInvitationDto":{"type":"object","properties":{"token":{"type":"string","minLength":32,"maxLength":256,"writeOnly":true},"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true}},"required":["token","password"]},"MerchantPasswordResetRequestDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com"}},"required":["email"]},"MerchantPasswordResetConfirmDto":{"type":"object","properties":{"token":{"type":"string","minLength":32,"maxLength":128,"writeOnly":true},"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true}},"required":["token","password"]},"MerchantLoginDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com"},"password":{"type":"string","example":"Use-a-password-manager"},"totpCode":{"type":"string","description":"Authenticator or recovery code when 2FA is enabled"}},"required":["email","password"]},"MerchantTwoFactorCodeDto":{"type":"object","properties":{"code":{"type":"string","description":"Six-digit authenticator code or recovery code"}},"required":["code"]},"DisableMerchantTwoFactorDto":{"type":"object","properties":{"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true},"code":{"type":"string","description":"Six-digit authenticator code or recovery code"}},"required":["password","code"]},"CreateMerchantAuthIdentityDto":{"type":"object","properties":{"email":{"type":"string","example":"owner@example.com"},"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true}},"required":["email","password"]},"UpdateMerchantSettingsDto":{"type":"object","properties":{"businessName":{"type":"string","example":"Acme Store","description":"Merchant display name shown in the dashboard and checkout."},"legalName":{"type":"object","example":"Acme Store S.A. de C.V.","nullable":true,"description":"Optional legal name. Send null to clear it."},"defaultSuccessUrl":{"type":"object","example":"https://merchant.example/success","nullable":true,"description":"Default success URL applied only when an invoice omits one."},"defaultCloseUrl":{"type":"object","example":"https://merchant.example/checkout","nullable":true,"description":"Default close URL applied only when an invoice omits one."},"defaultExpirationSeconds":{"type":"object","example":900,"nullable":true,"minimum":60,"maximum":604800,"description":"Default crypto invoice lifetime in seconds. Send null to use the gateway default."},"checkoutAutoRedirect":{"type":"boolean","example":false,"description":"Whether hosted checkout redirects automatically after success."},"brandName":{"type":"object","example":"Acme Pay","nullable":true,"description":"Optional checkout brand name. Send null to use the merchant name."},"brandAccentColor":{"type":"object","example":"#635BFF","nullable":true,"description":"Optional six-digit hex accent color used by hosted checkout."},"notifyPaymentConfirmed":{"type":"boolean","example":true,"description":"Whether payment-confirmed webhook notifications are enabled."},"notifyWebhookFailures":{"type":"boolean","example":true,"description":"Whether webhook delivery failure notifications are enabled."}}},"CreateMerchantTeamInvitationDto":{"type":"object","properties":{"email":{"type":"string","example":"operator@example.com"}},"required":["email"]},"UpdateMerchantTeamRoleDto":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin"],"example":"admin"}},"required":["role"]},"UpdateCustomerDto":{"type":"object","properties":{"name":{"type":"object","nullable":true,"example":"Buyer name"},"phone":{"type":"object","nullable":true,"example":"+52 555 0100"},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"description":"Replaces merchant-owned scalar metadata. Send null to clear it."}}},"CreateProductDto":{"type":"object","properties":{"name":{"type":"string","example":"Premium access"},"description":{"type":"string","example":"One-time access to the premium package."},"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USD"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"net_target","description":"Fee mode. net_target keeps the merchant amount and adds the gateway fee to the buyer total; gross absorbs the fee from the fixed amount."},"metadata":{"type":"object","example":{"category":"access"}}},"required":["name","amount","currency"]},"CreateProductPriceDto":{"type":"object","properties":{"amount":{"type":"string","example":"25.00"},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"net_target","description":"Fee mode. net_target keeps the merchant amount and adds the gateway fee to the buyer total; gross absorbs the fee from the fixed amount."}},"required":["amount","currency"]},"CreateRecurringPaymentPlanDto":{"type":"object","properties":{"customerId":{"type":"string","example":"cus_1234567890","description":"Optional merchant-scoped customer public ID. When supplied, generated invoices remain linked to this existing customer."},"title":{"type":"string","example":"Monthly hosting plan"},"description":{"type":"string","example":"Hosted checkout plan for monthly billing."},"interval":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"example":"monthly"},"intervalCount":{"type":"number","example":1,"default":1},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00","description":"Amount expected for each future invoice, in asset units."},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"net_target","description":"Fee mode. net_target keeps the merchant amount and adds the gateway fee to the buyer total; gross absorbs the fee from the fixed amount."},"invoiceLifetimeSeconds":{"type":"number","example":900,"description":"Lifetime for invoices later created from this plan."},"nextInvoiceAt":{"type":"string","example":"2026-06-01T00:00:00.000Z"},"metadata":{"type":"object","example":{"customerId":"cus_123"}}},"required":["title","interval","assetCode","networkCode","amountExpected"]},"UpdateRecurringPaymentPlanStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused","cancelled","archived"],"example":"paused"},"reason":{"type":"string","example":"Paused by merchant request."}},"required":["status"]},"TriggerWatcherScanDto":{"type":"object","properties":{"watcherCode":{"type":"string","example":"tron_trc20","description":"Specific automatic watcher to run. When omitted, all enabled watchers are scanned."}}},"CryptoTransactionStatus":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","ignored"]},"SyncBtcpayWebhookDto":{"type":"object","properties":{"callbackUrl":{"type":"string","example":"https://zemiaxpay.com/api/v1/crypto/provider-webhooks/btcpay"}}},"CreateCryptoWalletDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"providerCode":{"type":"string","example":"sandbox_crypto"},"label":{"type":"string","example":"Merchant Hot Wallet TRON"},"address":{"type":"string","example":"TN3w9ExampleAddress"},"memoTag":{"type":"string","example":"123456"},"metadata":{"type":"object","additionalProperties":true}},"required":["assetCode","networkCode","label","address"]},"CryptoWalletStatus":{"type":"string","enum":["active","inactive","rotating"]},"CreateStaticWalletAssignmentDto":{"type":"object","properties":{"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"externalReference":{"type":"string","example":"customer-123","description":"Stable merchant-side reference. Defaults to default when omitted."},"label":{"type":"string","example":"Customer 123 static TRC20 wallet"},"metadata":{"type":"object","additionalProperties":true}},"required":["assetCode","networkCode"]},"BlockStaticWalletAssignmentDto":{"type":"object","properties":{"reason":{"type":"string","example":"customer requested address rotation"}}},"InvoiceLineItemDto":{"type":"object","properties":{"name":{"type":"string","example":"Zemiax Gold Plan"},"description":{"type":"string","example":"Subscription for April 2026"},"sku":{"type":"string","example":"PLAN-GOLD-2026"},"quantity":{"type":"number","example":1,"minimum":1,"maximum":9999},"unitPrice":{"type":"string","example":"100.00"}},"required":["name","quantity","unitPrice"]},"CreateCryptoInvoiceDto":{"type":"object","properties":{"productPriceId":{"type":"string","example":"price_1234567890","description":"Optional active one-time crypto catalog price. When supplied, amount and rail are taken from this merchant-owned price."},"invoiceReference":{"type":"string","example":"CRINV-1001","description":"Native Zemiax invoice reference. If omitted, orderId/order_id is used."},"orderId":{"type":"string","example":"ORDER-1001","description":"Merchant order id. Alias for invoiceReference."},"order_id":{"type":"string","example":"ORDER-1001","description":"Accepted alias for invoiceReference."},"externalReference":{"type":"string","example":"order-crypto-1001"},"quoteId":{"type":"string","example":"qp_1234567890abcdef","description":"Optional locked quote id returned by GET /api/v1/crypto/prices/quote. Do not combine with amountExpected, fiatAmount, fiatCurrency, or priceBufferBps."},"assetCode":{"type":"string","example":"USDT","description":"Native Zemiax crypto asset code. If omitted, toCurrency/to_currency/currency can provide it."},"networkCode":{"type":"string","example":"TRC20","description":"Native Zemiax network code. If omitted, network can provide it. Required after alias normalization."},"amount":{"type":"string","example":"100.00","description":"Amount alias. Interpreted as crypto amount when currency is crypto and no to_currency is set; otherwise as fiat amount."},"currency":{"type":"string","example":"USD","description":"Source currency. Use with to_currency for fiat-denominated invoices."},"network":{"type":"string","example":"TRON","description":"Network alias. Examples: TRON -> TRC20, BSC -> BEP20, ETH -> ERC20."},"toCurrency":{"type":"string","example":"USDT","description":"Target crypto currency alias."},"to_currency":{"type":"string","example":"USDT","description":"Target crypto currency alias."},"currencies":{"example":["USDT","BTC"],"description":"Allowed asset list for POST /crypto/invoice-selections. Direct concrete invoice creation rejects this field.","type":"array","items":{"type":"string"}},"exceptCurrencies":{"example":["BTC"],"description":"Excluded asset list for POST /crypto/invoice-selections. Direct concrete invoice creation rejects this field.","type":"array","items":{"type":"string"}},"except_currencies":{"example":["BTC"],"description":"Excluded asset list alias for POST /crypto/invoice-selections. Direct concrete invoice creation rejects this field.","type":"array","items":{"type":"string"}},"courseSource":{"type":"string","example":"Binance","description":"Gateway-compatible course source selector. Intentionally rejected; use Zemiax quoteId for locked pricing."},"course_source":{"type":"string","example":"Binance","description":"Gateway-compatible course source selector alias. Intentionally rejected; use Zemiax quoteId for locked pricing."},"discountPercent":{"type":"number","example":5,"description":"Gateway-compatible discount percent. Intentionally rejected; apply discounts before invoice creation."},"discount_percent":{"type":"number","example":5,"description":"Gateway-compatible discount percent alias. Intentionally rejected; apply discounts before invoice creation."},"isRefresh":{"type":"boolean","example":true,"description":"Gateway-compatible refresh flag. Intentionally rejected; invoice pricing is immutable after creation."},"is_refresh":{"type":"boolean","example":true,"description":"Gateway-compatible refresh flag alias. Intentionally rejected; invoice pricing is immutable after creation."},"amountExpected":{"type":"string","example":"100.00","description":"Amount in crypto asset units. Optional when fiatAmount is provided."},"fiatAmount":{"type":"string","example":"10.00","description":"Fiat amount to convert into the crypto asset through the gateway price engine."},"fiatCurrency":{"type":"string","example":"USD","default":"USD"},"priceBufferBps":{"type":"number","example":50,"description":"Price safety buffer in basis points. 50 = 0.5%. Applied to volatile assets."},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"net_target","description":"Fee mode. net_target keeps the merchant amount and adds the gateway fee to the buyer total; gross absorbs the fee from the fixed amount."},"expiresAt":{"type":"string","example":"2026-04-07T18:00:00.000Z"},"lifetime":{"type":"number","example":900,"description":"Invoice lifetime in seconds. Supported range: 300-43200."},"itemName":{"type":"string","example":"USDT Subscription Invoice"},"itemDesc":{"type":"string","example":"Subscription for April 2026"},"itemCode":{"type":"string","example":"SUB-APR-2026"},"buyerName":{"type":"string","example":"Customer Name"},"buyerEmail":{"type":"string","example":"axel@example.com"},"buyerPhone":{"type":"string","example":"+52 555 000 0000"},"brandName":{"type":"string","example":"Zemiax Store"},"brandLogoUrl":{"type":"string","example":"https://merchant.example/logo.png"},"brandAccentColor":{"type":"string","example":"#61e7ba"},"redirectUrl":{"type":"string","example":"https://merchant.example/payments/success"},"urlSuccess":{"type":"string","example":"https://merchant.example/payments/success","description":"Accepted alias for redirectUrl."},"url_success":{"type":"string","example":"https://merchant.example/payments/success","description":"Accepted alias for redirectUrl."},"closeUrl":{"type":"string","example":"https://merchant.example/payments/cancelled"},"urlReturn":{"type":"string","example":"https://merchant.example/cart","description":"Accepted alias for closeUrl."},"url_return":{"type":"string","example":"https://merchant.example/cart","description":"Accepted alias for closeUrl."},"urlCallback":{"type":"string","example":"https://merchant.example/webhooks/payments","description":"Unsupported per-invoice field. Configure signed merchant webhook endpoints instead."},"url_callback":{"type":"string","example":"https://merchant.example/webhooks/payments","description":"Unsupported per-invoice field. Configure signed merchant webhook endpoints instead."},"autoRedirect":{"type":"boolean","example":true,"default":false},"isPaymentMultiple":{"type":"boolean","example":true,"description":"Confirmation flag. Zemiax currently supports true only."},"is_payment_multiple":{"type":"boolean","example":true,"description":"Accepted alias. Zemiax currently supports true only."},"accuracyPaymentPercent":{"type":"number","example":0,"description":"Payment tolerance. Zemiax currently supports 0 only."},"accuracy_payment_percent":{"type":"number","example":0,"description":"Payment tolerance alias. Zemiax currently supports 0 only."},"subtract":{"type":"number","example":100,"description":"Fee pass-through. Supported values: 0 merchant absorbs fees, 100 buyer pays all Zemiax fees."},"additionalData":{"type":"string","example":"CRM order context","description":"Merchant-only metadata not shown to the buyer."},"additional_data":{"type":"string","example":"CRM order context","description":"Accepted alias for merchant-only metadata."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItemDto"}},"metadata":{"type":"object","additionalProperties":true}}},"CryptoInvoiceInfoDto":{"type":"object","properties":{"uuid":{"type":"string","example":"7e2e0f8e-12b7-4d40-8a72-b10a5f0487a9","description":"Zemiax public invoice id used for invoice lookup."},"id":{"type":"string","example":"7e2e0f8e-12b7-4d40-8a72-b10a5f0487a9","description":"Alias for uuid/public invoice id."},"orderId":{"type":"string","example":"ORDER-1001","description":"Merchant order id. Matches invoiceReference or externalReference for panel compatibility."},"order_id":{"type":"string","example":"ORDER-1001","description":"Accepted order_id alias. Matches invoiceReference or externalReference."},"invoiceReference":{"type":"string","example":"ORDER-1001"}}},"ConfirmCryptoInvoiceSelectionDto":{"type":"object","properties":{"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"buyerName":{"type":"string","example":"Customer Name"},"buyerEmail":{"type":"string","example":"buyer@example.com"},"buyerPhone":{"type":"string","example":"+52 555 000 0000"}},"required":["assetCode","networkCode"]},"CreateCryptoPaymentLinkDto":{"type":"object","properties":{"productPriceId":{"type":"string","example":"price_1234567890","description":"Optional active one-time crypto catalog price. When supplied, amount and rail are taken from this merchant-owned price."},"title":{"type":"string","example":"USDT checkout link"},"description":{"type":"string","example":"Reusable checkout link for USDT TRC20."},"slug":{"type":"string","example":"usdt-trc20-plan","description":"Public slug. If omitted, ZemiaxPay generates a merchant-prefixed slug."},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountExpected":{"type":"string","example":"25.00","description":"Fixed amount in crypto asset units."},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"net_target","description":"Fee mode. net_target keeps the merchant amount and adds the gateway fee to the buyer total; gross absorbs the fee from the fixed amount."},"invoiceLifetimeSeconds":{"type":"number","example":900,"description":"Lifetime in seconds for each invoice created from this link."},"itemName":{"type":"string","example":"Checkout payment"},"itemDesc":{"type":"string","example":"Reusable public crypto checkout link"},"itemCode":{"type":"string","example":"LINK-USDT-TRC20"},"brandName":{"type":"string","example":"Zemiax Store"},"brandLogoUrl":{"type":"string","example":"https://merchant.example/logo.png"},"brandAccentColor":{"type":"string","example":"#61e7ba"},"redirectUrl":{"type":"string","example":"https://merchant.example/success"},"closeUrl":{"type":"string","example":"https://merchant.example/cart"},"autoRedirect":{"type":"boolean","example":false,"default":false},"expiresAt":{"type":"string","example":"2026-06-01T00:00:00.000Z"},"metadata":{"type":"object","example":{"plan":"starter"}}},"required":["title"]},"UpdateCryptoPaymentLinkDto":{"type":"object","properties":{"title":{"type":"string","example":"Updated checkout link"},"description":{"type":"string","example":"Updated checkout description."},"invoiceLifetimeSeconds":{"type":"number","example":1800,"description":"Lifetime in seconds for invoices created after the update."},"itemName":{"type":"string","example":"Updated item name"},"itemDesc":{"type":"string","example":"Updated item description."},"itemCode":{"type":"string","example":"UPDATED-LINK"},"brandName":{"type":"string","example":"Merchant Store"},"brandLogoUrl":{"type":"string","example":"https://merchant.example/logo.png"},"brandAccentColor":{"type":"string","example":"#8b5cf6"},"redirectUrl":{"type":"string","example":"https://merchant.example/success"},"closeUrl":{"type":"string","example":"https://merchant.example/cart"},"autoRedirect":{"type":"boolean","example":false},"expiresAt":{"type":"string","example":"2026-12-31T23:59:59.000Z"}}},"CreatePaymentLinkInvoiceDto":{"type":"object","properties":{"orderId":{"type":"string","example":"ORDER-1001","description":"Optional merchant order id. If omitted, a deterministic reference is derived from the payment link and Idempotency-Key."},"buyerName":{"type":"string","example":"Customer Name"},"buyerEmail":{"type":"string","example":"buyer@example.com"},"buyerPhone":{"type":"string","example":"+52 555 000 0000"},"metadata":{"type":"object","example":{"source":"hosted-link"}}}},"HostedSandboxCardPaymentDto":{"type":"object","properties":{"attemptId":{"type":"string","example":"bd75a8dc-f3b7-4300-87db-32d29d9096b1"},"cardNumber":{"type":"string","example":"4242 4242 4242 4242"},"expiryMonth":{"type":"string","example":"12"},"expiryYear":{"type":"string","example":"2030"},"cvv":{"type":"string","example":"123"},"cardholderName":{"type":"string","example":"AXEL C TEST"},"payerEmail":{"type":"string","example":"payer@example.com"}},"required":["attemptId","cardNumber","expiryMonth","expiryYear","cvv","cardholderName"]},"DetectCryptoTransactionDto":{"type":"object","properties":{"invoiceId":{"type":"string","example":"invoice-public-id"},"amount":{"type":"string","example":"100.00"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"currency":{"type":"string","example":"USDT"},"txid":{"type":"string","example":"trx-demo-001"},"address":{"type":"string","example":"TN3w..."},"memoTag":{"type":"string","example":"123456"},"initialPaymentStatus":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"],"default":"detected"},"confirmations":{"type":"number","example":0},"metadata":{"type":"object","additionalProperties":true}},"required":["amount","assetCode","networkCode","currency","txid"]},"ConfirmCryptoTransactionDto":{"type":"object","properties":{"networkCode":{"type":"string","example":"TRC20"},"txid":{"type":"string","example":"trx-demo-001"},"confirmations":{"type":"number","example":20}},"required":["networkCode","txid","confirmations"]},"SimulateCryptoPaymentDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"invoiceId":{"type":"string","example":"invoice-public-id"},"amountReceived":{"type":"string","example":"100.00"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"currency":{"type":"string","example":"USDT"},"txid":{"type":"string","example":"trx-abc-123"},"status":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"],"default":"pending_confirmation"},"address":{"type":"string","example":"TN3w..."},"memoTag":{"type":"string","example":"123456"},"externalReference":{"type":"string","example":"tx-external-7788"},"metadata":{"type":"object","additionalProperties":true}},"required":["merchantId","invoiceId","amountReceived","assetCode","networkCode","currency","txid"]},"CreateInvoiceDto":{"type":"object","properties":{"invoiceReference":{"type":"string","example":"INV-1001"},"externalReference":{"type":"string","example":"order-7788"},"methodType":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodType"}]},"amountExpected":{"type":"string","example":"1000.00"},"pricingMode":{"type":"string","enum":["gross","net_target"],"default":"gross"},"currency":{"type":"string","example":"MXN"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"providerCode":{"type":"string","example":"stp"},"providerCheckoutUrl":{"type":"string","example":"https://checkout.provider.example/session/abc123"},"expiresAt":{"type":"string","example":"2026-04-05T15:00:00.000Z"},"itemName":{"type":"string","example":"Zemiax Gold Plan"},"itemDesc":{"type":"string","example":"Subscription for April 2026"},"itemCode":{"type":"string","example":"PLAN-GOLD-2026"},"buyerName":{"type":"string","example":"Customer Name"},"buyerEmail":{"type":"string","example":"axel@example.com"},"buyerPhone":{"type":"string","example":"+52 555 000 0000"},"brandName":{"type":"string","example":"Zemiax Store"},"brandLogoUrl":{"type":"string","example":"https://merchant.example/logo.png"},"brandAccentColor":{"type":"string","example":"#61e7ba"},"redirectUrl":{"type":"string","example":"https://merchant.example/payments/success"},"closeUrl":{"type":"string","example":"https://merchant.example/payments/cancelled"},"autoRedirect":{"type":"boolean","example":true,"default":false},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItemDto"}},"metadata":{"type":"object","additionalProperties":true}},"required":["invoiceReference","methodType","amountExpected","currency"]},"InvoiceStatus":{"type":"string","enum":["pending","processing","paid","confirmed","partially_paid","expired","failed","cancelled"]},"CancelInvoiceDto":{"type":"object","properties":{"reason":{"type":"string","example":"Customer abandoned checkout"}}},"ArchiveInvoiceDto":{"type":"object","properties":{"reason":{"type":"string","example":"Closed merchant order"}}},"ExpireDueInvoicesDto":{"type":"object","properties":{"limit":{"type":"number","example":100,"minimum":1,"maximum":500}}},"SimulateSpeiPaymentDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"invoiceId":{"type":"string","example":"invoice-public-id"},"amountReceived":{"type":"string","example":"1000.00"},"currency":{"type":"string","example":"MXN"},"status":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"],"default":"confirmed"},"externalReference":{"type":"string","example":"spei-op-1001"},"metadata":{"type":"object","additionalProperties":true}},"required":["merchantId","invoiceId","amountReceived","currency"]},"SimulateCardPaymentDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"invoiceId":{"type":"string","example":"invoice-public-id"},"amountReceived":{"type":"string","example":"499.99"},"currency":{"type":"string","example":"MXN"},"status":{"type":"string","enum":["detected","pending_confirmation","confirmed","failed","reversed","ignored"],"default":"pending_confirmation"},"externalReference":{"type":"string","example":"card-auth-7788"},"metadata":{"type":"object","additionalProperties":true}},"required":["merchantId","invoiceId","amountReceived","currency"]},"CreateStpFiatAccountDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"alias":{"type":"string","example":"Cobranza SPEI principal"},"currency":{"type":"string","example":"MXN"},"speiClabe":{"type":"string","example":"646180157000000001"},"bankName":{"type":"string","example":"STP"},"metadata":{"type":"object","example":{"remoteAccountId":"stp-collect-001"}}},"required":["merchantId","alias","currency","speiClabe"]},"PaymentChannel":{"type":"string","enum":["fiat","crypto"]},"SettlementStatus":{"type":"string","enum":["pending","processing","settled","failed","cancelled"]},"SettlementApprovalStatus":{"type":"string","enum":["not_required","pending","approved","rejected"]},"SettlementExecutionStatus":{"type":"string","enum":["planned","broadcasted","confirmed","failed","cancelled"]},"SettlementExecutionKind":{"type":"string","enum":["treasury_sweep","merchant_payout","manual_adjustment"]},"CreateSettlementBatchDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"channel":{"allOf":[{"$ref":"#/components/schemas/PaymentChannel"}]},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"paymentIds":{"example":["payment-public-id-1","payment-public-id-2"],"type":"array","items":{"type":"string"}},"externalReference":{"type":"string","example":"settlement-2026-04-14"},"metadata":{"type":"object","example":{"walletSweepId":"sweep_001","destination":"treasury_hot_1"}}}},"CreateSettlementExecutionDto":{"type":"object","properties":{"kind":{"allOf":[{"$ref":"#/components/schemas/SettlementExecutionKind"}]},"amount":{"type":"string","example":"99.50"},"sourceWalletId":{"type":"string","example":"wallet-public-id"},"destinationWalletId":{"type":"string","example":"destination-wallet-public-id"},"destinationAddress":{"type":"string","example":"TN3w9TreasuryWalletDestination0003"},"destinationMemoTag":{"type":"string","example":"memo-001"},"destinationAccountRef":{"type":"string","example":"CLABE:646180157000000001"},"providerCode":{"type":"string","example":"sandbox_payout"},"externalReference":{"type":"string","example":"sweep-2026-04-15-001"},"metadata":{"type":"object","example":{"destinationLabel":"treasury hot wallet","requestedBy":"ops"}}},"required":["kind"]},"TransitionSettlementBatchStatusDto":{"type":"object","properties":{"status":{"examples":["processing","settled"],"allOf":[{"$ref":"#/components/schemas/SettlementStatus"}]},"externalReference":{"type":"string","example":"sweep_tx_001"},"metadata":{"type":"object","example":{"note":"settled to treasury wallet","approvedBy":"ops-admin"}}},"required":["status"]},"TransitionSettlementExecutionStatusDto":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/SettlementExecutionStatus"}]},"txid":{"type":"string","example":"0xsettlementsweeptx001"},"externalReference":{"type":"string","example":"broadcast-001"},"metadata":{"type":"object","example":{"explorerUrl":"https://...","note":"confirmed on treasury sweep"}}},"required":["status"]},"DecideSettlementApprovalDto":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"note":{"type":"string","example":"Reviewed treasury balance and recipient ownership."}},"required":["decision"]},"SettlementApprovalSubjectType":{"type":"string","enum":["batch","execution"]},"AdminUserRole":{"type":"string","enum":["super_admin","ops_admin","analyst"]},"CreateSettlementApprovalPolicyDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"name":{"type":"string","example":"High value merchant payout approvals"},"subjectType":{"allOf":[{"$ref":"#/components/schemas/SettlementApprovalSubjectType"}]},"channel":{"allOf":[{"$ref":"#/components/schemas/PaymentChannel"}]},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"amountThreshold":{"type":"string","example":"5000.00"},"requiredRole":{"allOf":[{"$ref":"#/components/schemas/AdminUserRole"}]},"isActive":{"type":"boolean","example":true},"metadata":{"type":"object","example":{"reason":"high_value_control"}}},"required":["name","subjectType","channel","currency","amountThreshold","requiredRole"]},"UpdateSettlementApprovalPolicyStatusDto":{"type":"object","properties":{"isActive":{"type":"boolean","example":false}},"required":["isActive"]},"SettlementDestinationType":{"type":"string","enum":["crypto_wallet","crypto_address","fiat_account_ref"]},"CreateSettlementDestinationDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"label":{"type":"string","example":"Primary USDT treasury destination"},"channel":{"allOf":[{"$ref":"#/components/schemas/PaymentChannel"}]},"type":{"allOf":[{"$ref":"#/components/schemas/SettlementDestinationType"}]},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"walletId":{"type":"string","example":"wallet-public-id"},"address":{"type":"string","example":"TN3w9TreasuryWalletDestination0003"},"memoTag":{"type":"string","example":"memo-001"},"accountRef":{"type":"string","example":"CLABE:646180157000000001"},"providerCode":{"type":"string","example":"sandbox_payout"},"custodyType":{"type":"string","enum":["self_custody","exchange"],"example":"exchange"},"exchangeCode":{"type":"string","example":"BINANCE"},"addressTagLabel":{"type":"string","example":"MEMO"},"destinationNotes":{"type":"string","example":"Binance deposit address for treasury settlements"},"isDefault":{"type":"boolean","example":true},"metadata":{"type":"object","example":{"owner":"merchant_finance"}}},"required":["merchantId","label","channel","type","currency"]},"UpdateSettlementDestinationStatusDto":{"type":"object","properties":{"isActive":{"type":"boolean","example":true},"isDefault":{"type":"boolean","example":true}},"required":["isActive"]},"SettlementProfileMode":{"type":"string","enum":["manual","auto_batch","auto_execute"]},"CreateSettlementProfileDto":{"type":"object","properties":{"merchantId":{"type":"string","example":"merchant-public-id"},"destinationId":{"type":"string","example":"settlement-destination-public-id"},"sourceWalletId":{"type":"string","example":"source-wallet-public-id"},"channel":{"allOf":[{"$ref":"#/components/schemas/PaymentChannel"}]},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"mode":{"allOf":[{"$ref":"#/components/schemas/SettlementProfileMode"}]},"executionKind":{"allOf":[{"$ref":"#/components/schemas/SettlementExecutionKind"}]},"minNetAmount":{"type":"string","example":"500.00"},"maxPaymentsPerBatch":{"type":"number","example":200,"minimum":1,"maximum":500},"cooldownMinutes":{"type":"number","example":60,"minimum":0,"maximum":10080},"metadata":{"type":"object","example":{"cadence":"daily_settlement"}}},"required":["merchantId","destinationId","channel","currency","mode"]},"UpdateSettlementProfileStatusDto":{"type":"object","properties":{"isActive":{"type":"boolean","example":true}},"required":["isActive"]},"RunSettlementAutomationDto":{"type":"object","properties":{"dryRun":{"type":"boolean","example":false},"force":{"type":"boolean","example":false},"limit":{"type":"number","example":25,"minimum":1,"maximum":200}}},"RunSettlementProcessorsDto":{"type":"object","properties":{"executionId":{"type":"string","example":"execution-public-id"},"providerCode":{"type":"string","example":"sandbox_payout"},"limit":{"type":"number","example":50,"minimum":1,"maximum":200}}},"CreateMerchantPayoutBatchDto":{"type":"object","properties":{"channel":{"allOf":[{"$ref":"#/components/schemas/PaymentChannel"}]},"currency":{"type":"string","example":"USDT"},"assetCode":{"type":"string","example":"USDT"},"networkCode":{"type":"string","example":"TRC20"},"paymentIds":{"example":["payment-public-id-1","payment-public-id-2"],"type":"array","items":{"type":"string"}},"externalReference":{"type":"string","example":"merchant-payout-batch-2026-05-14"},"metadata":{"type":"object","example":{"destinationProfile":"default-usdt-trc20"}}}},"CreateAdminUserDto":{"type":"object","properties":{"email":{"type":"string","example":"ops@zemiax.com"},"name":{"type":"string","example":"Ops Admin"},"role":{"allOf":[{"$ref":"#/components/schemas/AdminUserRole"}]},"metadata":{"type":"object","example":{"team":"operations"}}},"required":["email","name","role"]},"UpdateAdminUserStatusDto":{"type":"object","properties":{"isActive":{"type":"boolean","example":false}},"required":["isActive"]},"CreateAdminApiKeyDto":{"type":"object","properties":{"name":{"type":"string","example":"Ops Console Key"},"expiresAt":{"type":"string","example":"2026-12-31T23:59:59.000Z"}},"required":["name"]}}}}