{ "paths": { "/api/v1/api-keys/{apikey}": { "delete": { "operationId": "ApiKeys_DeleteApiKey", "tags": [ "API Keys" ], "summary": "Revoke an API Key", "description": "Revoke the current API key so that it cannot be used anymore", "parameters": [ { "name": "apikey", "in": "path", "required": true, "description": "The API Key to revoke", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key has been deleted" }, "404": { "description": "The key is not found for this user" } }, "security": [ { "API_Key": [ "unrestricted" ], "Basic": [] } ] } }, "/api/v1/api-keys/current": { "get": { "operationId": "ApiKeys_GetCurrentApiKey", "tags": [ "API Keys" ], "summary": "Get the current API Key information", "description": "View information about the current API key", "responses": { "200": { "description": "Information about the current api key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyData" } } } } }, "security": [ { "API_Key": [] } ] }, "delete": { "operationId": "ApiKeys_DeleteCurrentApiKey", "tags": [ "API Keys" ], "summary": "Revoke the current API Key", "description": "Revoke the current API key so that it cannot be used anymore", "responses": { "200": { "description": "The key was revoked and is no longer usable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyData" } } } } }, "security": [ { "API_Key": [] } ] } }, "/api/v1/api-keys": { "post": { "operationId": "ApiKeys_CreateApiKey", "tags": [ "API Keys" ], "summary": "Create a new API Key", "description": "Create a new API Key", "responses": { "200": { "description": "Information about the new api key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyData" } } } } }, "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "description": "The label of the new API Key", "nullable": true }, "permissions": { "type": "array", "description": "The permissions granted to this API Key (See API Key Authentication)", "nullable": true, "items": { "type": "string" } } } } } } }, "security": [ { "API_Key": [ "unrestricted" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/apps/pos": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store ID", "schema": { "type": "string" } } ], "post": { "operationId": "Apps_CreatePointOfSaleApp", "summary": "Create a new Point of Sale app", "description": "Point of Sale apps allows accepting payments for items in a virtual store", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "appName": { "type": "string", "description": "The name of the app (shown in admin UI)", "nullable": false }, "title": { "type": "string", "description": "The title of the app (shown to the user)", "nullable": true }, "description": { "type": "string", "description": "The description of the app", "nullable": true }, "template": { "type": "string", "description": "Template for items available in the app", "nullable": true }, "defaultView": { "type": "string", "description": "Template for items available in the app", "nullable": true, "x-enumNames": [ "Static", "Cart", "Light", "Print" ], "enum": [ "Static", "Cart", "Light", "Print" ] }, "currency": { "type": "string", "description": "Currency to use for the app. Defaults to the currency used by the store if not specified", "example": "BTC", "nullable": true }, "showCustomAmount": { "type": "boolean", "description": "Whether to include a special item in the store which allows user to input a custom payment amount", "default": true, "nullable": true }, "showDiscount": { "type": "boolean", "description": "Whether to allow user to input a discount amount. Applies to Cart view only. Not recommended for customer self-checkout", "default": true, "nullable": true }, "enableTips": { "type": "boolean", "description": "Whether to allow user to input a tip amount. Applies to Cart and Light views only", "default": true, "nullable": true }, "customAmountPayButtonText": { "type": "string", "description": "Payment button text which appears for items which allow user to input a custom amount", "default": "Pay", "nullable": true }, "fixedAmountPayButtonText": { "type": "string", "description": "Payment button text which appears for items which have a fixed price", "default": "Buy for {PRICE_HERE}", "nullable": true }, "tipText": { "type": "string", "description": "Prompt which appears next to the tip amount field if tipping is enabled", "default": "Do you want to leave a tip?", "nullable": true }, "customCSSLink": { "type": "string", "description": "Link to a custom CSS stylesheet to be used in the app", "nullable": true }, "embeddedCSS": { "type": "string", "description": "Custom CSS to embed into the app", "nullable": true }, "notificationUrl": { "type": "string", "description": "Callback notification url to POST to once when invoice is paid for and once when there are enough blockchain confirmations", "nullable": true }, "redirectUrl": { "type": "string", "description": "URL to redirect user to once invoice is paid", "nullable": true }, "redirectAutomatically": { "type": "boolean", "description": "Whether to redirect user to redirect URL automatically once invoice is paid. Defaults to what is set in the store settings", "nullable": true }, "requiresRefundEmail": { "type": "boolean", "description": "Whether to redirect user to redirect URL automatically once invoice is paid. Defaults to what is set in the store settings", "nullable": true } } } } } }, "responses": { "200": { "description": "Created app details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointOfSaleAppData" } } } }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "tags": [ "Apps" ], "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/apps/{appId}": { "get": { "tags": [ "Apps" ], "operationId": "Apps_GetPointOfSaleApp", "summary": "Get basic app data", "description": "Returns basic app data shared between all types of apps", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "The app ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Basic app data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicAppData" } } } }, "404": { "description": "App with specified ID was not found" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "tags": [ "Apps" ], "operationId": "Apps_DeletePointOfSaleApp", "summary": "Delete app", "description": "Deletes apps with specified ID", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "The app ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "App was deleted" }, "404": { "description": "App with specified ID was not found" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api-keys/authorize": { "get": { "operationId": "ApiKeys_Authorize", "tags": [ "Authorization" ], "summary": "Authorize User", "description": "Redirect the browser to this endpoint to request the user to generate an api-key with specific permissions", "parameters": [ { "name": "permissions", "description": "The permissions to request. (See API Key authentication)", "in": "query", "style": "form", "explode": true, "schema": { "type": "array", "nullable": true, "items": { "type": "string" } }, "x-position": 1 }, { "name": "applicationName", "description": "The name of your application", "in": "query", "schema": { "type": "string", "nullable": true }, "x-position": 2 }, { "name": "strict", "description": "If permissions are specified, and strict is set to false, it will allow the user to reject some of permissions the application is requesting.", "in": "query", "schema": { "type": "boolean", "default": true, "nullable": true }, "x-position": 3 }, { "name": "selectiveStores", "description": "If the application is requesting the CanModifyStoreSettings permission and selectiveStores is set to true, this allows the user to only grant permissions to selected stores under the user's control.", "in": "query", "schema": { "type": "boolean", "default": false, "nullable": true }, "x-position": 4 }, { "name": "redirect", "description": "The url to redirect to after the user consents, with the query parameters appended to it: permissions, user-id, api-key. If not specified, user is redirected to their API Key list.", "in": "query", "schema": { "type": "string", "format": "url", "nullable": true }, "x-position": 5 }, { "name": "applicationIdentifier", "description": "If specified, BTCPay Server will check if there is an existing API key associated with the user that also has this application identifier, redirect host AND the permissions required match(takes selectiveStores and strict into account). `applicationIdentifier` is ignored if redirect is not specified.", "in": "query", "schema": { "type": "string", "nullable": true }, "x-position": 6 } ], "responses": { "200": { "description": "A HTML form that a user can use to confirm permissions to grant", "content": { "text/html": {} } }, "307": { "description": "Makes browser do an HTTP POST request to the specified url in `redirect` with a JSON body consisting of `apiKey` (the api key created or matched), `permissions` (the permissions the user consented to), and `userId` (the id of the user that consented) upon consent" } }, "security": [] } }, "/api/v1/custodians": { "get": { "tags": [ "Custodians" ], "summary": "List supported custodians", "description": "List all supported custodians for the BTCPay instance. You can install plugins to add more custodians.", "operationId": "Custodians_GetSupportedCustodians", "responses": { "200": { "description": "list of supported custodians", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustodianData" } } } } } }, "security": [ { "API_Key": [], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts": { "get": { "operationId": "Custodians_GetStoreCustodianAccounts", "tags": [ "Custodians" ], "summary": "List store custodian accounts", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "assetBalances", "in": "query", "required": false, "description": "Enable if you want the result to include the 'assetBalances' field. This will make the call slower or could cause the call to fail if the asset balances cannot be loaded (i.e. due to a bad API key).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of custodian accounts for the store.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustodianAccountData" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the store's custodian accounts" } } }, "post": { "operationId": "Custodians_AddStoreCustodianAccount", "tags": [ "Custodians" ], "summary": "Add a custodial account to a store.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } } ], "description": "Add a custodial account to a store.", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustodianAccountRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the new custodian account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustodianAccountData" } } } }, "403": { "description": "If you are authenticated but forbidden to add new custodian account" } }, "security": [ { "API_Key": [ "btcpay.store.canmanagecustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}": { "get": { "operationId": "Custodians_GetStoreCustodianAccount", "tags": [ "Custodians" ], "summary": "Get store custodian account", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID", "schema": { "type": "string" } }, { "name": "assetBalances", "in": "query", "required": false, "description": "Enable if you want the result to include the 'assetBalances' field. This will make the call slower or could cause the call to fail if the asset balances cannot be loaded (i.e. due to a bad API key).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of custodian accounts for the store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustodianAccountData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the custodian account" } } }, "put": { "operationId": "Custodians_UpdateStoreCustodianAccount", "tags": [ "Custodians" ], "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID", "schema": { "type": "string" } } ], "summary": "Update custodial account", "description": "Update custodial account", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustodianAccountRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The updated custodian account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustodianAccountData" } } } }, "403": { "description": "If you are authenticated but forbidden to modify new custodian account" } }, "security": [ { "API_Key": [ "btcpay.store.canmanagecustodianaccounts" ], "Basic": [] } ] }, "delete": { "operationId": "Custodians_DeleteStoreCustodianAccount", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID", "schema": { "type": "string" } } ], "tags": [ "Custodians" ], "summary": "Delete store custodian account", "description": "Deletes a custodial account", "responses": { "200": { "description": "Custodian account deleted" }, "403": { "description": "If you are authenticated but forbidden to delete the custodian account" } } } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}/trades/quote": { "get": { "operationId": "Custodians_GetStoreCustodianAccountTradeQuote", "tags": [ "Custodians" ], "summary": "Get quote for trading one asset for another", "description": "Get the current bid and ask price for converting one asset into another.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID.", "schema": { "type": "string" } }, { "name": "fromAsset", "in": "query", "required": true, "description": "The asset to convert.", "schema": { "type": "string" } }, { "name": "toAsset", "in": "query", "required": true, "description": "The asset you want.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The quote for converting one asset to another.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResultData" } } } }, "404": { "description": "No tradable asset pair found for this trade." }, "403": { "description": "If you are authenticated but forbidden to create trades" } }, "security": [ { "API_Key": [ "btcpay.store.canviewcustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}/trades/market": { "post": { "operationId": "Custodians_StoreCustodianAccountTradeMarket", "tags": [ "Custodians" ], "summary": "Trade one asset for another", "description": "Trade one asset for another using a market order (=instant purchase with instant result or failure). A suitable asset pair will automatically be selected. If no asset pair is available, the call will fail.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID.", "schema": { "type": "string" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeRequestData" } } } }, "responses": { "200": { "description": "Information about the trade that was executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeResultData" } } } }, "404": { "description": "No tradable asset pair found for this trade." }, "403": { "description": "If you are authenticated but forbidden to create trades" } }, "security": [ { "API_Key": [ "btcpay.store.cantradecustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}/addresses/{paymentMethod}": { "get": { "operationId": "Custodians_GetStoreCustodianAccountDepositAddress", "tags": [ "Custodians" ], "summary": "Get a deposit address for custodian", "description": "Get a new deposit address for the custodian using the specified payment method (network + crypto code).", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID.", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "The payment method to use for the deposit. Example: \"BTC-OnChain\" or \"BTC-Lightning\"", "schema": { "type": "string" } } ], "responses": { "200": { "description": "deposit address", "content": { "application/json": { "schema": { "type": "object", "properties": { "depositAddress": { "type": "string", "description": "The address to deposit your funds." } }, "description": "A bitcoin address belonging to the custodian" }, "example": { "depositAddress": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } }, "404": { "description": "The custodian does not support deposits using this payment method." }, "403": { "description": "If you are authenticated but forbidden to get the deposit address" } }, "security": [ { "API_Key": [ "btcpay.store.candeposittocustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}/withdrawals": { "post": { "operationId": "Custodians_WithdrawFromStoreCustodianAccount", "tags": [ "Custodians" ], "summary": "Withdraw to store wallet", "description": "Withdraw an asset to your store wallet.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID.", "schema": { "type": "string" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalRequestData" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the withdrawal that was executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResultData" } } } }, "400": { "description": "Withdrawal is not possible because you don't have this much in your account." }, "404": { "description": "Withdrawal is not possible for this asset." }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "description": "If you are authenticated but forbidden to create trades" }, { "type": "string", "description": "Withdrawing to the address provided is not allowed" } ] } } } } }, "security": [ { "API_Key": [ "btcpay.store.canwithdrawfromcustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/custodian-accounts/{accountId}/withdrawals/{withdrawalId}": { "post": { "operationId": "Custodians_GetStoreCustodianAccountWithdrawalInfo", "tags": [ "Custodians" ], "summary": "Get withdrawal info", "description": "Get the details about a past withdrawal.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The Store ID", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Custodian Account ID.", "schema": { "type": "string" } }, { "name": "withdrawalId", "in": "path", "required": true, "description": "The Withdrawal ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Information about the withdrawal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalResultData" } } } }, "404": { "description": "Withdrawal not found." }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "description": "If you are authenticated but forbidden to create trades" }, { "type": "string", "description": "Withdrawing to the address provided is not allowed" } ] } } } } }, "security": [ { "API_Key": [ "btcpay.store.canwithdrawfromcustodianaccounts" ], "Basic": [] } ] } }, "/api/v1/health": { "get": { "tags": [ "Health" ], "summary": "Get health status", "description": "Check the instance health status", "operationId": "Health_GetHealth", "responses": { "200": { "description": "Instance is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationHealthData" } } } } }, "security": [] } }, "/api/v1/stores/{storeId}/invoices": { "get": { "tags": [ "Invoices" ], "summary": "Get invoices", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } }, { "name": "orderId", "in": "query", "required": false, "description": "Array of OrderIds to fetch the invoices for", "schema": { "type": "array", "items": { "type": "string" } }, "example": "1000&orderId=1001&orderId=1002" }, { "name": "status", "in": "query", "required": false, "description": "Array of statuses of invoices to be fetched", "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "name": "textSearch", "in": "query", "required": false, "description": "A term that can help locating specific invoices.", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Start date of the period to retrieve invoices", "schema": { "$ref": "#/components/schemas/UnixTimestamp" } }, { "name": "endDate", "in": "query", "required": false, "description": "End date of the period to retrieve invoices", "schema": { "$ref": "#/components/schemas/UnixTimestamp" } }, { "name": "skip", "in": "query", "required": false, "description": "Number of records to skip", "schema": { "nullable": true, "type": "number" } }, { "name": "take", "in": "query", "required": false, "description": "Number of records returned in response", "schema": { "nullable": true, "type": "number" } } ], "description": "View information about the existing invoices", "operationId": "Invoices_GetInvoices", "responses": { "200": { "description": "list of invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canviewinvoices" ], "Basic": [] } ] }, "post": { "tags": [ "Invoices" ], "summary": "Create a new invoice", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } } ], "description": "Create a new invoice", "operationId": "Invoices_CreateInvoice", "responses": { "200": { "description": "Information about the new invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceData" } } } }, "400": { "description": "A list of errors that occurred when creating the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to add new invoices" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.cancreateinvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/invoices/{invoiceId}": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to fetch", "schema": { "type": "string" } } ], "description": "View information about the specified invoice", "operationId": "Invoices_GetInvoice", "responses": { "200": { "description": "specified invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified invoice" }, "404": { "description": "The key is not found for this invoice" } }, "security": [ { "API_Key": [ "btcpay.store.canviewinvoices" ], "Basic": [] } ] }, "delete": { "tags": [ "Invoices" ], "summary": "Archive invoice", "description": "Archives the specified invoice.", "operationId": "Invoices_ArchiveInvoice", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store the invoice belongs to", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice has been archived" }, "400": { "description": "A list of errors that occurred when archiving the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to archive the specified invoice" }, "404": { "description": "The key is not found for this invoice" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifyinvoices" ], "Basic": [] } ] }, "put": { "tags": [ "Invoices" ], "summary": "Update invoice", "description": "Updates the specified invoice.", "operationId": "Invoices_UpdateInvoice", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store the invoice belongs to", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to update", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice that has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceData" } } } }, "400": { "description": "A list of errors that occurred when updating the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified invoice" }, "404": { "description": "The key is not found for this invoice" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifyinvoices" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice payment methods", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to fetch", "schema": { "type": "string" } }, { "name": "onlyAccountedPayments", "in": "query", "required": false, "description": "If default or true, only returns payments which are accounted (in Bitcoin, this mean not returning RBF'd or double spent payments)", "schema": { "type": "boolean", "default": true } } ], "description": "View information about the specified invoice's payment methods", "operationId": "Invoices_GetInvoicePaymentMethods", "responses": { "200": { "description": "specified invoice payment methods data", "content": { "application/json": { "schema": { "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/InvoicePaymentMethodDataModel" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified invoice" }, "404": { "description": "The key is not found for this invoice" } }, "security": [ { "API_Key": [ "btcpay.store.canviewinvoices" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/invoices/{invoiceId}/status": { "post": { "tags": [ "Invoices" ], "summary": "Mark invoice status", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to update", "schema": { "type": "string" } } ], "description": "Mark an invoice as invalid or settled.", "operationId": "Invoices_MarkInvoiceStatus", "responses": { "200": { "description": "The updated invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceData" } } } }, "400": { "description": "A list of errors that occurred when updating the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the invoice" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkInvoiceStatusRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifyinvoices" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/invoices/{invoiceId}/unarchive": { "post": { "tags": [ "Invoices" ], "summary": "Unarchive invoice", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to update", "schema": { "type": "string" } } ], "description": "Unarchive an invoice", "operationId": "Invoices_UnarchiveInvoice", "responses": { "200": { "description": "The unarchived invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceData" } } } }, "400": { "description": "A list of errors that occurred when updating the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the invoice" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifyinvoices" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods/{paymentMethod}/activate": { "post": { "tags": [ "Invoices" ], "summary": "Activate Payment Method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice to update", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "The payment method to activate", "schema": { "type": "string" } } ], "description": "Activate an invoice payment method (if lazy payments mode is enabled)", "operationId": "Invoices_ActivatePaymentMethod", "responses": { "200": { "description": "" }, "400": { "description": "A list of errors that occurred when updating the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to activate the invoice payment method" } }, "security": [ { "API_Key": [ "btcpay.store.canviewinvoices" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/info": { "get": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get node information", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the lightning node", "operationId": "InternalLightningNodeApi_GetInfo", "responses": { "200": { "description": "Lightning node information such as reachable nodeinfos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNodeInformationData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/balance": { "get": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get node balance", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View balance of the lightning node", "operationId": "InternalLightningNodeApi_GetBalance", "responses": { "200": { "description": "Lightning node balance for on-chain and off-chain funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNodeBalanceData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/connect": { "post": { "tags": [ "Lightning (Internal Node)" ], "summary": "Connect to lightning node", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Connect to another lightning node.", "operationId": "InternalLightningNodeApi_ConnectToNode", "responses": { "200": { "description": "Successfully connected" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `could-not-connect`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectToNodeRequest" } } } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/channels": { "get": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get channels", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the current channels of the lightning node", "operationId": "InternalLightningNodeApi_GetChannels", "responses": { "200": { "description": "list of channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LightningChannelData" } } } } }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] }, "post": { "tags": [ "Lightning (Internal Node)" ], "summary": "Open channel", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Open a channel with another lightning node. You should connect to that node first.", "operationId": "InternalLightningNodeApi_OpenChannel", "responses": { "200": { "description": "Successfully opened" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `channel-already-exists`, `cannot-afford-funding`, `need-more-confirmations`, `peer-not-connected`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenLightningChannelRequest" } } } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/address": { "post": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get deposit address", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Get an on-chain deposit address for the lightning node ", "operationId": "InternalLightningNodeApi_GetDepositAddress", "responses": { "200": { "description": "deposit address", "content": { "application/json": { "schema": { "type": "string", "description": "A bitcoin address belonging to the lightning node" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/payments/{paymentHash}": { "get": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get payment", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "paymentHash", "in": "path", "required": true, "description": "The payment hash of the lightning payment.", "schema": { "type": "string" } } ], "description": "View information about the requested lightning payment", "operationId": "InternalLightningNodeApi_GetPayment", "responses": { "200": { "description": "Lightning payment data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningPaymentData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration or the specified invoice was not found " } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/invoices/{id}": { "get": { "tags": [ "Lightning (Internal Node)" ], "summary": "Get invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "id", "in": "path", "required": true, "description": "The id of the lightning invoice.", "schema": { "type": "string" } } ], "description": "View information about the requested lightning invoice", "operationId": "InternalLightningNodeApi_GetInvoice", "responses": { "200": { "description": "Lightning invoice data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningInvoiceData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration or the specified invoice was not found " } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/invoices/pay": { "post": { "tags": [ "Lightning (Internal Node)" ], "summary": "Pay Lightning Invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Pay a lightning invoice.", "operationId": "InternalLightningNodeApi_PayInvoice", "responses": { "200": { "description": "Successfully paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningPaymentData" } } } }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `could-not-find-route`, `generic-error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayLightningInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.server.canuseinternallightningnode" ], "Basic": [] } ] } }, "/api/v1/server/lightning/{cryptoCode}/invoices": { "post": { "tags": [ "Lightning (Internal Node)" ], "summary": "Create lightning invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Create a lightning invoice.", "operationId": "InternalLightningNodeApi_CreateInvoice", "responses": { "200": { "description": "Successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningInvoiceData" } } } }, "400": { "description": "Wellknown error codes are: `invoice-error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLightningInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.server.cancreatelightninginvoiceinternalnode" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/info": { "get": { "tags": [ "Lightning (Store)" ], "summary": "Get node information", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "View information about the lightning node", "operationId": "StoreLightningNodeApi_GetInfo", "responses": { "200": { "description": "Lightning node information such as reachable nodeinfos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNodeInformationData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.store.canuselightningnode" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/balance": { "get": { "tags": [ "Lightning (Store)" ], "summary": "Get node balance", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "View balance of the lightning node", "operationId": "StoreLightningNodeApi_GetBalance", "responses": { "200": { "description": "Lightning node balance for on-chain and off-chain funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNodeBalanceData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.store.canuselightningnode" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/connect": { "post": { "tags": [ "Lightning (Store)" ], "summary": "Connect to lightning node", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "Connect to another lightning node.", "operationId": "StoreLightningNodeApi_ConnectToNode", "responses": { "200": { "description": "Successfully connected" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `could-not-connect`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectToNodeRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/channels": { "get": { "tags": [ "Lightning (Store)" ], "summary": "Get channels", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "View information about the current channels of the lightning node", "operationId": "StoreLightningNodeApi_GetChannels", "responses": { "200": { "description": "list of channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LightningChannelData" } } } } }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] }, "post": { "tags": [ "Lightning (Store)" ], "summary": "Open channel", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "Open a channel with another lightning node. You should connect to that node first.", "operationId": "StoreLightningNodeApi_OpenChannel", "responses": { "200": { "description": "Successfully opened" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `channel-already-exists`, `cannot-afford-funding`, `need-more-confirmations`, `peer-not-connected`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenLightningChannelRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/address": { "post": { "tags": [ "Lightning (Store)" ], "summary": "Get deposit address", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string", "description": "A bitcoin address belonging to the lightning node" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "Get an on-chain deposit address for the lightning node ", "operationId": "StoreLightningNodeApi_GetDepositAddress", "responses": { "200": { "description": "deposit address", "content": { "application/json": { "schema": { "type": "string" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/payments/{paymentHash}": { "get": { "tags": [ "Lightning (Store)" ], "summary": "Get payment", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } }, { "name": "paymentHash", "in": "path", "required": true, "description": "The payment hash of the lightning payment.", "schema": { "type": "string" } } ], "description": "View information about the requested lightning payment", "operationId": "StoreLightningNodeApi_GetPayment", "responses": { "200": { "description": "Lightning payment data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningPaymentData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration or the specified invoice was not found " } }, "security": [ { "API_Key": [ "btcpay.store.canuselightningnode" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices/{id}": { "get": { "tags": [ "Lightning (Store)" ], "summary": "Get invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The id of the lightning invoice.", "schema": { "type": "string" } } ], "description": "View information about the requested lightning invoice", "operationId": "StoreLightningNodeApi_GetInvoice", "responses": { "200": { "description": "Lightning invoice data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningInvoiceData" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration or the specified invoice was not found " } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices/pay": { "post": { "tags": [ "Lightning (Store)" ], "summary": "Pay Lightning Invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "Pay a lightning invoice.", "operationId": "StoreLightningNodeApi_PayInvoice", "responses": { "200": { "description": "Successfully paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningPaymentData" } } } }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `could-not-find-route`, `generic-error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayLightningInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.store.cancreatelightninginvoice" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices": { "post": { "tags": [ "Lightning (Store)" ], "summary": "Create lightning invoice", "parameters": [ { "name": "cryptoCode", "in": "path", "required": true, "description": "The cryptoCode of the lightning-node to query", "schema": { "type": "string" }, "example": "BTC" }, { "name": "storeId", "in": "path", "required": true, "description": "The store id with the lightning-node configuration to query", "schema": { "type": "string" } } ], "description": "Create a lightning invoice.", "operationId": "StoreLightningNodeApi_CreateInvoice", "responses": { "200": { "description": "Successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningInvoiceData" } } } }, "400": { "description": "Wellknown error codes are: `invoice-error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Unable to access the lightning node" }, "404": { "description": "The lightning node configuration was not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLightningInvoiceRequest" } } } }, "security": [ { "API_Key": [ "btcpay.server.cancreatelightninginvoiceinternalnode" ], "Basic": [] } ] } }, "/misc/permissions": { "get": { "tags": [ "Miscelleneous" ], "summary": "Permissions metadata", "description": "The metadata of available permissions", "operationId": "permissionsMetadata", "responses": { "200": { "description": "The metadata of available permissions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The permission id", "nullable": false }, "included": { "type": "array", "description": "Permissions included in this array are also granted by this permission", "nullable": false, "items": { "type": "string" } } } } } } } } }, "security": [] } }, "/misc/lang": { "get": { "tags": [ "Miscelleneous" ], "summary": "Language codes", "description": "The supported language codes", "operationId": "langCodes", "responses": { "200": { "description": "The supported language codes", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The language code", "nullable": false }, "currentLanguage": { "type": "string", "description": "The language name", "nullable": false } } } } } } } }, "security": [] } }, "/i/{invoiceId}": { "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "description": "The invoice id", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "The preferred language of the checkout page. You can use \"auto\" to use the language of the customer's browser or see the list of language codes with [this operation](#operation/langCodes).", "schema": { "type": "string" } } ], "get": { "tags": [ "Miscelleneous" ], "operationId": "Invoice_Checkout", "summary": "Invoice checkout", "description": "View the checkout page of an invoice", "responses": { "200": { "description": "The checkout page", "content": { "text/html": { "example": "The HTML checkout page of the invoice" } } } }, "security": [] } }, "/api/v1/users/me/notifications": { "get": { "tags": [ "Notifications (Current User)" ], "summary": "Get notifications", "parameters": [ { "name": "seen", "in": "query", "required": false, "description": "filter by seen notifications", "schema": { "type": "string", "nullable": true } }, { "name": "skip", "in": "query", "required": false, "description": "Number of records to skip", "schema": { "nullable": true, "type": "number" } }, { "name": "take", "in": "query", "required": false, "description": "Number of records returned in response", "schema": { "nullable": true, "type": "number" } } ], "description": "View current user's notifications", "operationId": "Notifications_GetNotifications", "responses": { "200": { "description": "list of notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationData" } } } } }, "security": [ { "API_Key": [ "btcpay.user.canmanagenotificationsforuser", "btcpay.user.canviewnotificationsforuser" ], "Basic": [] } ] } }, "/api/v1/users/me/notifications/{id}": { "get": { "tags": [ "Notifications (Current User)" ], "summary": "Get notification", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The notification to fetch", "schema": { "type": "string" } } ], "description": "View information about the specified notification", "operationId": "Notifications_GetNotification", "responses": { "200": { "description": "specified notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified notification" }, "404": { "description": "The key is not found for this notification" } }, "security": [ { "API_Key": [ "btcpay.user.canmanagenotificationsforuser", "btcpay.user.canviewnotificationsforuser" ], "Basic": [] } ] }, "put": { "tags": [ "Notifications (Current User)" ], "summary": "Update notification", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The notification to update", "schema": { "type": "string" } } ], "description": "Updates the notification", "operationId": "Notifications_UpdateNotification", "responses": { "200": { "description": "updated notification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationData" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified notification" }, "404": { "description": "The key is not found for this notification" } }, "security": [ { "API_Key": [ "btcpay.user.canmanagenotificationsforuser" ], "Basic": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotification" } } } } }, "delete": { "tags": [ "Notifications (Current User)" ], "summary": "Remove Notification", "description": "Removes the specified notification.", "operationId": "Notifications_DeleteNotification", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The notification to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The notification has been deleted" }, "403": { "description": "If you are authenticated but forbidden to remove the specified notification" }, "404": { "description": "The key is not found for this notification" } }, "security": [ { "API_Key": [ "btcpay.user.canmanagenotificationsforuser" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-requests": { "get": { "tags": [ "Payment Requests" ], "summary": "Get payment requests", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } } ], "description": "View information about the existing payment requests", "operationId": "PaymentRequests_GetPaymentRequests", "responses": { "200": { "description": "list of payment requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canviewpaymentrequests" ], "Basic": [] } ] }, "post": { "tags": [ "Payment Requests" ], "summary": "Create a new payment request", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } } ], "description": "Create a new payment request", "operationId": "PaymentRequests_CreatePaymentRequest", "responses": { "200": { "description": "Information about the new payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestData" } } } }, "400": { "description": "A list of errors that occurred when creating the payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to add new payment requests" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestBaseData" } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifypaymentrequests" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-requests/{paymentRequestId}": { "get": { "tags": [ "Payment Requests" ], "summary": "Get payment request", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "paymentRequestId", "in": "path", "required": true, "description": "The payment request to fetch", "schema": { "type": "string" } } ], "description": "View information about the specified payment request", "operationId": "PaymentRequests_GetPaymentRequest", "responses": { "200": { "description": "specified payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified payment request" }, "404": { "description": "The key is not found for this payment request" } }, "security": [ { "API_Key": [ "btcpay.store.canviewpaymentrequests" ], "Basic": [] } ] }, "delete": { "tags": [ "Payment Requests" ], "summary": "Archive payment request", "description": "Archives the specified payment request.", "operationId": "PaymentRequests_ArchivePaymentRequest", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store the payment request belongs to", "schema": { "type": "string" } }, { "name": "paymentRequestId", "in": "path", "required": true, "description": "The payment request to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payment request has been archived" }, "400": { "description": "A list of errors that occurred when archiving the payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to archive the specified payment request" }, "404": { "description": "The key is not found for this payment request" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifypaymentrequests" ], "Basic": [] } ] }, "put": { "tags": [ "Payment Requests" ], "summary": "Update payment request", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to query", "schema": { "type": "string" } }, { "name": "paymentRequestId", "in": "path", "required": true, "description": "The payment request to update", "schema": { "type": "string" } } ], "description": "Update a payment request", "operationId": "PaymentRequests_UpdatePaymentRequest", "responses": { "200": { "description": "The updated payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestData" } } } }, "400": { "description": "A list of errors that occurred when updating the payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the payment request" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestBaseData" } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifypaymentrequests" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors": { "get": { "tags": [ "Stores (Payout Processors)" ], "summary": "Get store configured payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "Get store configured payout processors", "operationId": "StorePayoutProcessors_GetStorePayoutProcessors", "responses": { "200": { "description": "configured payout processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutProcessorData" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors/{processor}/{paymentMethod}": { "delete": { "tags": [ "Stores (Payout Processors)" ], "summary": "Remove store configured payout processor", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store", "schema": { "type": "string" } }, { "name": "processor", "in": "path", "required": true, "description": "The processor", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "The payment method", "schema": { "type": "string" } } ], "description": "Remove store configured payout processor", "operationId": "StorePayoutProcessors_RemoveStorePayoutProcessor", "responses": { "200": { "description": "removed" }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/payout-processors": { "get": { "tags": [ "Payout Processors" ], "summary": "Get payout processors", "description": "Get payout processors available in this instance", "operationId": "PayoutProcessors_GetPayoutProcessors", "responses": { "200": { "description": "available payout processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutProcessorData" } } } } } }, "security": [ { "API_Key": [], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors/OnChainAutomatedTransferSenderFactory/{paymentMethod}": { "get": { "tags": [ "Stores (Payout Processors)" ], "summary": "Get configured store onchain automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "A specific payment method to fetch", "schema": { "type": "string" } } ], "description": "Get configured store onchain automated payout processors", "operationId": "GreenfieldStoreAutomatedOnChainPayoutProcessorsController_GetStoreOnChainAutomatedPayoutProcessorsForPaymentMethod", "responses": { "200": { "description": "configured processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OnChainAutomatedTransferSettings" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Stores (Payout Processors)" ], "summary": "Update configured store onchain automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "A specific payment method to fetch", "schema": { "type": "string" } } ], "description": "Update configured store onchain automated payout processors", "operationId": "GreenfieldStoreAutomatedOnChainPayoutProcessorsController_UpdateStoreOnChainAutomatedPayoutProcessorForPaymentMethod", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnChainAutomatedTransferSettings" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "configured processor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainAutomatedTransferSettings" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors/LightningAutomatedTransferSenderFactory/{paymentMethod}": { "get": { "tags": [ "Stores (Payout Processors)" ], "summary": "Get configured store Lightning automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "A specific payment method to fetch", "schema": { "type": "string" } } ], "description": "Get configured store Lightning automated payout processors", "operationId": "GreenfieldStoreAutomatedLightningPayoutProcessorsController_GetStoreLightningAutomatedPayoutProcessorsForPaymentMethod", "responses": { "200": { "description": "configured processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LightningAutomatedTransferSettings" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Stores (Payout Processors)" ], "summary": "Update configured store Lightning automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "path", "required": true, "description": "A specific payment method to fetch", "schema": { "type": "string" } } ], "description": "Update configured store Lightning automated payout processors", "operationId": "GreenfieldStoreAutomatedLightningPayoutProcessorsController_UpdateStoreLightningAutomatedPayoutProcessor", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLightningAutomatedTransferSettings" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "configured processor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningAutomatedTransferSettings" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors/OnChainAutomatedTransferSenderFactory": { "get": { "tags": [ "Stores (Payout Processors)" ], "summary": "Get configured store onchain automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "Get configured store onchain automated payout processors", "operationId": "GreenfieldStoreAutomatedOnChainPayoutProcessorsController_GetStoreOnChainAutomatedTransferSenderFactory", "responses": { "200": { "description": "configured processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OnChainAutomatedTransferSettings" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Stores (Payout Processors)" ], "summary": "Update configured store onchain automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "Update configured store onchain automated payout processors", "operationId": "GreenfieldStoreAutomatedOnChainPayoutProcessorsController_UpdateStoreOnChainAutomatedTransferSenderFactory", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnChainAutomatedTransferSettings" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "configured processor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainAutomatedTransferSettings" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payout-processors/LightningAutomatedTransferSenderFactory": { "get": { "tags": [ "Stores (Payout Processors)" ], "summary": "Get configured store Lightning automated payout processors", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "Get configured store Lightning automated payout processors", "operationId": "GreenfieldStoreAutomatedLightningPayoutProcessorsController_GetStoreLightningAutomatedTransferSenderFactory", "responses": { "200": { "description": "configured processors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LightningAutomatedTransferSettings" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/pull-payments": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store ID", "schema": { "type": "string" } } ], "get": { "operationId": "PullPayments_GetPullPayments", "summary": "Get store's pull payments", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "description": "Whether this should list archived pull payments", "schema": { "type": "boolean", "default": false } } ], "description": "Get the pull payments of a store", "responses": { "200": { "description": "List of pull payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullPaymentDataList" } } } } }, "tags": [ "Pull payments (Management)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] }, "post": { "operationId": "PullPayments_CreatePullPayment", "summary": "Create a new pull payment", "description": "A pull payment allows its receiver to ask for payouts up to `amount` of `currency` every `period`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the pull payment", "nullable": true }, "description": { "type": "string", "description": "The description of the pull payment", "nullable": true }, "amount": { "type": "string", "format": "decimal", "example": "0.1", "description": "The amount in `currency` of this pull payment as a decimal string" }, "currency": { "type": "string", "example": "BTC", "description": "The currency of the amount." }, "period": { "type": "integer", "format": "decimal", "example": 604800, "nullable": true, "description": "The length of each period in seconds." }, "BOLT11Expiration": { "type": "string", "example": 30, "default": 30, "nullable": true, "description": "If lightning is activated, do not accept BOLT11 invoices with expiration less than … days" }, "autoApproveClaims": { "type": "boolean", "example": false, "default": false, "nullable": true, "description": "Any payouts created for this pull payment will skip the approval phase upon creation" }, "startsAt": { "type": "integer", "format": "unix timestamp in seconds", "example": 1592312018, "nullable": true, "description": "When this pull payment is effective. Already started if null or unspecified." }, "expiresAt": { "type": "integer", "format": "unix timestamp in seconds", "example": 1593129600, "nullable": true, "description": "When this pull payment expires. Never expires if null or unspecified." }, "paymentMethods": { "type": "array", "description": "The list of supported payment methods supported by this pull payment. Available options can be queried from the `StorePaymentMethods_GetStorePaymentMethods` endpoint", "items": { "type": "string", "example": "BTC" } } } } } } }, "responses": { "200": { "description": "The create pull payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullPaymentData" } } } }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "tags": [ "Pull payments (Management)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] } }, "/api/v1/pull-payments/{pullPaymentId}": { "parameters": [ { "name": "pullPaymentId", "in": "path", "required": true, "description": "The ID of the pull payment", "schema": { "type": "string" } } ], "get": { "summary": "Get Pull Payment", "operationId": "PullPayments_GetPullPayment", "description": "Get a pull payment", "responses": { "200": { "description": "Information about the pull payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullPaymentData" } } } }, "404": { "description": "Pull payment not found" } }, "tags": [ "Pull payments (Public)" ], "security": [] } }, "/api/v1/stores/{storeId}/pull-payments/{pullPaymentId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The ID of the store", "schema": { "type": "string" } }, { "name": "pullPaymentId", "in": "path", "required": true, "description": "The ID of the pull payment", "schema": { "type": "string" } } ], "delete": { "operationId": "PullPayments_ArchivePullPayment", "summary": "Archive a pull payment", "description": "Archive this pull payment (Will cancel all payouts awaiting for payment)", "responses": { "200": { "description": "The pull payment has been archived" }, "404": { "description": "The pull payment has not been found, or does not belong to this store" } }, "tags": [ "Pull payments (Management)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] } }, "/api/v1/pull-payments/{pullPaymentId}/payouts": { "parameters": [ { "name": "pullPaymentId", "in": "path", "required": true, "description": "The ID of the pull payment", "schema": { "type": "string" } } ], "get": { "summary": "Get Payouts", "operationId": "PullPayments_GetPayouts", "description": "Get payouts", "parameters": [ { "name": "includeCancelled", "in": "query", "required": false, "description": "Whether this should list cancelled payouts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The payouts of the pull payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutDataList" } } } }, "404": { "description": "Pull payment not found" } }, "tags": [ "Pull payments (Public)" ], "security": [] }, "post": { "summary": "Create Payout", "description": "Create a new payout", "operationId": "PullPayments_CreatePayout", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "A new payout has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutData" } } } }, "404": { "description": "Pull payment not found" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `duplicate-destination`, `expired`, `not-started`, `archived`, `overdraft`, `amount-too-low`, `payment-method-not-supported`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "tags": [ "Pull payments (Public)" ], "security": [] } }, "/api/v1/pull-payments/{pullPaymentId}/payouts/{payoutId}": { "parameters": [ { "name": "pullPaymentId", "in": "path", "required": true, "description": "The ID of the pull payment", "schema": { "type": "string" } }, { "name": "payoutId", "in": "path", "required": true, "description": "The ID of the pull payment payout", "schema": { "type": "string" } } ], "get": { "summary": "Get Payout", "operationId": "PullPayments_GetPayout", "description": "Get payout", "responses": { "200": { "description": "A specific payout of a pull payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutData" } } } }, "404": { "description": "Pull payment payout not found" } }, "tags": [ "Pull payments (Public)", "Pull payments payout (Public)" ], "security": [] } }, "/api/v1/stores/{storeId}/payouts": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The ID of the store", "schema": { "type": "string" } } ], "post": { "summary": "Create Payout ", "description": "Create a new payout", "operationId": "Payouts_CreatePayoutThroughStore", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutThroughStoreRequest" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "A new payout has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutData" } } } }, "404": { "description": "store not found" }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `duplicate-destination`, `expired`, `not-started`, `archived`, `overdraft`, `amount-too-low`, `payment-method-not-supported`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "tags": [ "Stores (Payouts)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] }, "get": { "summary": "Get Store Payouts", "operationId": "PullPayments_GetStorePayouts", "description": "Get payouts", "parameters": [ { "name": "includeCancelled", "in": "query", "required": false, "description": "Whether this should list cancelled payouts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The payouts of the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutDataList" } } } }, "404": { "description": "Pull payment not found" } }, "tags": [ "Stores (Payouts)" ], "security": [] } }, "/api/v1/stores/{storeId}/payouts/{payoutId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The ID of the store", "schema": { "type": "string" } }, { "name": "payoutId", "in": "path", "required": true, "description": "The ID of the payout", "schema": { "type": "string" } } ], "post": { "summary": "Approve Payout", "operationId": "PullPayments_ApprovePayout", "description": "Approve a payout", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "description": "The revision number of the payout being modified" }, "rateRule": { "type": "string", "nullable": true, "example": "kraken(BTC_USD)", "description": "The rate rule to calculate the rate of the payout. This can also be a fixed decimal. (if null or unspecified, will use the same rate setting as the store's settings)" } } } } } }, "responses": { "200": { "description": "The payout has been approved, transitioning to `AwaitingPayment` state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutData" } } } }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `rate-unavailable`, `invalid-state`, `amount-too-low`, `old-revision`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The payout is not found" } }, "tags": [ "Stores (Payouts)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] }, "delete": { "summary": "Cancel Payout", "description": "Cancel the payout", "operationId": "PullPayments_CancelPayout", "responses": { "200": { "description": "The payout has been cancelled" }, "404": { "description": "The payout is not found" } }, "tags": [ "Stores (Payouts)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payouts/{payoutId}/mark-paid": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The ID of the store", "schema": { "type": "string" } }, { "name": "payoutId", "in": "path", "required": true, "description": "The ID of the payout", "schema": { "type": "string" } } ], "post": { "summary": "Mark Payout as Paid", "operationId": "PullPayments_MarkPayoutPaid", "description": "Mark a payout as paid", "responses": { "200": { "description": "The payout has been marked paid, transitioning to `Completed` state." }, "422": { "description": "Unable to validate the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "400": { "description": "Wellknown error codes are: `invalid-state`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The payout is not found" } }, "tags": [ "Stores (Payouts)" ], "security": [ { "API_Key": [ "btcpay.store.canmanagepullpayments" ], "Basic": [] } ] } }, "/api/v1/server/info": { "get": { "tags": [ "ServerInfo" ], "summary": "Get server info", "description": "Information about the server, chains and sync states", "operationId": "ServerInfo_GetServerInfo", "responses": { "200": { "description": "Server information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationServerInfoData" } } } } }, "security": [ { "API_Key": [], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/email": { "get": { "tags": [ "Stores (Email)" ], "summary": "Get store email settings", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "View email settings of the specified store", "operationId": "Stores_GetStoreEmailSettings", "responses": { "200": { "description": "specified store email settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Stores (Email)" ], "summary": "Update store email settings", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to update", "schema": { "type": "string" } } ], "description": "Update a store's email settings", "operationId": "Stores_UpdateStoreEmailSettings", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsData" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The settings were updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsData" } } } }, "400": { "description": "A list of errors that occurred when updating the settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to modify the store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/email/send": { "post": { "operationId": "Stores_SendStoreEmail", "tags": [ "Stores (Email)" ], "summary": "Send an email for a store", "description": "Send an email using the store's SMTP server", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to send the email from", "schema": { "type": "string" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailData" } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "The email was sent (scheduled) successfully" }, "400": { "description": "The store's SMTP is not configured" }, "403": { "description": "If you are authenticated but forbidden to add new stores" }, "404": { "description": "The store was not found" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods": { "get": { "tags": [ "Store Payment Methods" ], "summary": "Get store payment methods", "description": "View information about the stores' configured payment methods", "operationId": "StorePaymentMethods_GetStorePaymentMethods", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "description": "Fetch payment methods that are enabled/disabled only", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of payment methods", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GenericPaymentMethodData" } } } } } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/LightningNetwork": { "get": { "tags": [ "Store Payment Methods (Lightning Network)" ], "summary": "Get store Lightning Network payment methods", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "description": "Fetch payment methods that are enabled/disabled only", "schema": { "type": "boolean" } } ], "description": "View information about the stores' configured Lightning Network payment methods", "operationId": "StoreLightningNetworkPaymentMethods_GetLightningNetworkPaymentMethods", "responses": { "200": { "description": "list of payment methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNetworkPaymentMethodDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/LightningNetwork/{cryptoCode}": { "get": { "tags": [ "Store Payment Methods (Lightning Network)" ], "summary": "Get store Lightning Network payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the specified payment method", "operationId": "StoreLightningNetworkPaymentMethods_GetLightningNetworkPaymentMethod", "responses": { "200": { "description": "specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNetworkPaymentMethodData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/payment method" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Store Payment Methods (Lightning Network)" ], "summary": "Update store Lightning Network payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Update the specified store's payment method", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLightningNetworkPaymentMethodRequest" } } }, "required": true, "x-position": 1 }, "operationId": "StoreLightningNetworkPaymentMethods_UpdateLightningNetworkPaymentMethod", "responses": { "200": { "description": "updated specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LightningNetworkPaymentMethodData" } } } }, "400": { "description": "A list of errors that occurred when updating the store payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "operationId": "StoreLightningNetworkPaymentMethods_DeleteLightningNetworkPaymentMethod", "tags": [ "Store Payment Methods (Lightning Network)" ], "summary": "Remove store Lightning Network payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Removes the specified store payment method.", "responses": { "200": { "description": "The payment method has been removed" }, "400": { "description": "A list of errors that occurred when removing the payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to remove the specified payment method" }, "404": { "description": "The key is not found for this store/payment-method" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/LNURL": { "get": { "tags": [ "Store Payment Methods (LNURL Pay)" ], "summary": "Get store LNURL payment methods", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "description": "Fetch payment methods that are enabled/disabled only", "schema": { "type": "boolean" } } ], "description": "View information about the stores' configured LNURL payment methods", "operationId": "StoreLNURLPayPaymentMethods_GetLNURLPayPaymentMethods", "responses": { "200": { "description": "list of payment methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LNURLPayPaymentMethodDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/LNURL/{cryptoCode}": { "get": { "tags": [ "Store Payment Methods (LNURL Pay)" ], "summary": "Get store LNURL Pay payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the specified payment method", "operationId": "StoreLNURLPayPaymentMethods_GetLNURLPayPaymentMethod", "responses": { "200": { "description": "specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LNURLPayPaymentMethodData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/payment method" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Store Payment Methods (LNURL Pay)" ], "summary": "Update store LNURL Pay payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Update the specified store's payment method", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LNURLPayPaymentMethodData" } } }, "required": true, "x-position": 1 }, "operationId": "StoreLNURLPayPaymentMethods_UpdateLNURLPayPaymentMethod", "responses": { "200": { "description": "updated specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LNURLPayPaymentMethodData" } } } }, "400": { "description": "A list of errors that occurred when updating the store payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "operationId": "StoreLNURLPayPaymentMethods_DeleteLNURLPayPaymentMethod", "tags": [ "Store Payment Methods (LNURL Pay)" ], "summary": "Remove store LNURL Pay payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Removes the specified store payment method.", "responses": { "200": { "description": "The payment method has been removed" }, "400": { "description": "A list of errors that occurred when removing the payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to remove the specified payment method" }, "404": { "description": "The key is not found for this store/payment-method" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/OnChain": { "get": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Get store on-chain payment methods", "description": "View information about the stores' configured on-chain payment methods", "operationId": "StoreOnChainPaymentMethods_GetOnChainPaymentMethods", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "description": "Fetch payment methods that are enabled/disabled only", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "list of payment methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}": { "get": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Get store on-chain payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the specified payment method", "operationId": "StoreOnChainPaymentMethods_GetOnChainPaymentMethod", "responses": { "200": { "description": "specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/payment method" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Update store on-chain payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Update the specified store's payment method", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnChainPaymentMethodRequest" } } }, "required": true, "x-position": 1 }, "operationId": "StoreOnChainPaymentMethods_UpdateOnChainPaymentMethod", "responses": { "200": { "description": "updated specified payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodData" } } } }, "400": { "description": "A list of errors that occurred when updating the store payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "operationId": "StoreOnChainPaymentMethods_DeleteOnChainPaymentMethod", "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Remove store on-chain payment method", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Removes the specified store payment method.", "responses": { "200": { "description": "The payment method has been removed" }, "400": { "description": "A list of errors that occurred when removing the payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to remove the specified payment method" }, "404": { "description": "The key is not found for this store/payment-method" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/generate": { "post": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Generate store on-chain wallet", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to update", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Generate a wallet and update the specified store's payment method to it", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateOnChainWalletRequest" } } }, "required": true, "x-position": 1 }, "operationId": "StoreOnChainPaymentMethods_GenerateOnChainWallet", "responses": { "200": { "description": "updated specified payment method with the generated wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodDataWithSensitiveData" } } } }, "400": { "description": "A list of errors that occurred when updating the store payment method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/OnChain/{cryptoCode}/preview": { "get": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Preview store on-chain payment method addresses", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "offset", "in": "query", "required": false, "description": "From which index to fetch the addresses", "schema": { "type": "number" } }, { "name": "amount", "in": "query", "required": false, "description": "Number of addresses to preview", "schema": { "type": "number" } } ], "description": "View addresses of the current payment method of the store", "operationId": "StoreOnChainPaymentMethods_GetOnChainPaymentMethodPreview", "responses": { "200": { "description": "specified payment method addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodPreviewResultData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/payment method" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "post": { "tags": [ "Store Payment Methods (On Chain)" ], "summary": "Preview proposed store on-chain payment method addresses", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "offset", "in": "query", "required": false, "description": "From which index to fetch the addresses", "schema": { "type": "number" } }, { "name": "amount", "in": "query", "required": false, "description": "Number of addresses to preview", "schema": { "type": "number" } } ], "description": "View addresses of a proposed payment method of the store", "operationId": "StoreOnChainPaymentMethods_POSTOnChainPaymentMethodPreview", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "type": "object", "properties": { "derivationScheme": { "type": "string", "description": "The derivation scheme", "example": "xpub..." } } } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "specified payment method addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainPaymentMethodPreviewResultData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/users": { "get": { "tags": [ "Stores (Users)" ], "summary": "Get store users", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "View users of the specified store", "operationId": "Stores_GetStoreUsers", "responses": { "200": { "description": "specified store users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUserDataList" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "post": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to add the user to", "schema": { "type": "string" } } ], "tags": [ "Stores (Users)" ], "summary": "Add a store user", "description": "Add a store user", "operationId": "Stores_AddStoreUser", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUserData" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "The user was added" }, "400": { "description": "A list of errors that occurred when creating the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to add new stores" }, "409": { "description": "Error code: `duplicate-store-user-role`. Removing this user would result in the store having no owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/users/{userId}": { "delete": { "tags": [ "Stores (Users)" ], "summary": "Remove Store User", "operationId": "Stores_RemoveStoreUser", "description": "Removes the specified store user. If there is no other owner, this endpoint will fail.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "The user", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user has been removed" }, "400": { "description": "A list of errors that occurred when removing the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "409": { "description": "Error code: `store-user-role-orphaned`. Removing this user would result in the store having no owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to remove the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet overview", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "View information about the specified wallet", "operationId": "StoreOnChainWallets_ShowOnChainWalletOverview", "responses": { "200": { "description": "specified wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainWalletOverviewData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet/feerate": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet fee rate", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "blockTarget", "in": "query", "required": false, "description": "The number of blocks away you are willing to target for confirmation. Defaults to the wallet's configured `RecommendedFeeBlockTarget`", "schema": { "type": "number", "minimum": 1 } } ], "description": "Get wallet onchain fee rate", "operationId": "StoreOnChainWallets_GetOnChainFeeRate", "responses": { "200": { "description": "fee rate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainWalletFeeRateData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet/address": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet address", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "forceGenerate", "in": "query", "required": false, "description": "Whether to generate a new address for this request even if the previous one was not used", "schema": { "type": "boolean", "default": false } } ], "description": "Get or generate address for wallet", "operationId": "StoreOnChainWallets_GetOnChainWalletReceiveAddress", "responses": { "200": { "description": "reserved address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainWalletAddressData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "tags": [ "Store Wallet (On Chain)" ], "summary": "UnReserve last store on-chain wallet address", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the payment method to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "UnReserve address", "operationId": "StoreOnChainWallets_UnReserveOnChainWalletReceiveAddress", "responses": { "200": { "description": "address unreserved" }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet or there was no address reserved" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet/transactions": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet transactions", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the wallet to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "statusFilter", "in": "query", "required": false, "description": "Statuses to filter the transactions with", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionStatus" } } }, { "name": "labelFilter", "in": "query", "required": false, "description": "Transaction label to filter by", "schema": { "type": "string" }, "example": "invoice" }, { "name": "skip", "in": "query", "required": false, "description": "Number of transactions to skip from the start", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of transactions to return", "schema": { "type": "integer" } } ], "description": "Get store on-chain wallet transactions", "operationId": "StoreOnChainWallets_ShowOnChainWalletTransactions", "responses": { "200": { "description": "transactions list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OnChainWalletTransactionData" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" }, "503": { "description": "You need to allow non-admins to use hotwallets for their stores (in /server/policies)" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "post": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Create store on-chain wallet transaction", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the wallet", "schema": { "type": "string" }, "example": "BTC" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnChainTransactionRequest" } } } }, "description": "Create store on-chain wallet transaction", "operationId": "StoreOnChainWallets_CreateOnChainTransaction", "responses": { "200": { "description": "the tx", "content": { "application/json": { "schema": { "oneOf": [ { "description": "The unbroadcasted transaction in hex format", "type": "string" }, { "$ref": "#/components/schemas/OnChainWalletTransactionData" } ] } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet/transactions/{transactionId}": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet transaction", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the wallet to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "transactionId", "in": "path", "required": true, "description": "The transaction id to fetch", "schema": { "type": "string" } } ], "description": "Get store on-chain wallet transaction", "operationId": "StoreOnChainWallets_GetOnChainWalletTransaction", "responses": { "200": { "description": "transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainWalletTransactionData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "patch": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Patch store on-chain wallet transaction info", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the wallet to fetch", "schema": { "type": "string" }, "example": "BTC" }, { "name": "transactionId", "in": "path", "required": true, "description": "The transaction id to fetch", "schema": { "type": "string" } }, { "name": "force", "in": "query", "required": false, "description": "Whether to update the label/comments even if the transaction does not yet exist", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchOnChainTransactionRequest" } } } }, "description": "Patch store on-chain wallet transaction info", "operationId": "StoreOnChainWallets_PatchOnChainWalletTransaction", "responses": { "200": { "description": "transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnChainWalletTransactionData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/payment-methods/onchain/{cryptoCode}/wallet/utxos": { "get": { "tags": [ "Store Wallet (On Chain)" ], "summary": "Get store on-chain wallet UTXOS", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } }, { "name": "cryptoCode", "in": "path", "required": true, "description": "The crypto code of the wallet to fetch", "schema": { "type": "string" }, "example": "BTC" } ], "description": "Get store on-chain wallet utxos", "operationId": "StoreOnChainWallets_GetOnChainWalletUTXOs", "responses": { "200": { "description": "utxo list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OnChainWalletUTXOData" } } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store/wallet" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores": { "get": { "tags": [ "Stores" ], "summary": "Get stores", "description": "View information about the available stores", "operationId": "Stores_GetStores", "responses": { "200": { "description": "list of stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDataList" } } } } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "post": { "operationId": "Stores_CreateStore", "tags": [ "Stores" ], "summary": "Create a new store", "description": "Create a new store", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBaseData" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the new store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreData" } } } }, "400": { "description": "A list of errors that occurred when creating the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to add new stores" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}": { "get": { "tags": [ "Stores" ], "summary": "Get store", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to fetch", "schema": { "type": "string" } } ], "description": "View information about the specified store", "operationId": "Stores_GetStore", "responses": { "200": { "description": "specified store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreData" } } } }, "403": { "description": "If you are authenticated but forbidden to view the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canviewstoresettings" ], "Basic": [] } ] }, "put": { "tags": [ "Stores" ], "summary": "Update store", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to update", "schema": { "type": "string" } } ], "description": "Update the specified store", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreData" } } }, "required": true, "x-position": 1 }, "operationId": "Stores_UpdateStore", "responses": { "200": { "description": "updated specified store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreData" } } } }, "400": { "description": "A list of errors that occurred when updating the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to update the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] }, "delete": { "operationId": "Stores_DeleteStore", "tags": [ "Stores" ], "summary": "Remove Store", "description": "Removes the specified store. If there is another user with access, only your access will be removed.", "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The store has been removed" }, "400": { "description": "A list of errors that occurred when removing the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "403": { "description": "If you are authenticated but forbidden to remove the specified store" }, "404": { "description": "The key is not found for this store" } }, "security": [ { "API_Key": [ "btcpay.store.canmodifystoresettings" ], "Basic": [] } ] } }, "/api/v1/users/me": { "get": { "tags": [ "Users" ], "summary": "Get current user information", "description": "View information about the current user", "operationId": "Users_GetCurrentUser", "responses": { "200": { "description": "Information about the current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationUserData" } } } }, "404": { "description": "The user could not be found" } }, "security": [ { "API_Key": [ "btcpay.user.canviewprofile" ], "Basic": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Deletes user profile", "description": "Deletes user profile and associated user data for user making the request", "operationId": "Users_DeleteCurrentUser", "responses": { "200": { "description": "User and associated data deleted successfully" }, "404": { "description": "The user could not be found" } }, "security": [ { "API_Key": [ "btcpay.user.candeleteuser" ], "Basic": [] } ] } }, "/api/v1/users": { "get": { "operationId": "Users_GetUsers", "tags": [ "Users" ], "summary": "Get all users", "description": "Load all users that exist.", "parameters": [], "responses": { "200": { "description": "Users found" }, "401": { "description": "Missing authorization for loading the users" }, "403": { "description": "Authorized but forbidden to load the users. You have the wrong API permissions." } }, "security": [ { "API_Key": [ "btcpay.server.canviewusers" ], "Basic": [] } ] }, "post": { "operationId": "Users_CreateUser", "tags": [ "Users" ], "summary": "Create user", "description": "Create a new user.\n\nThis operation can be called without authentication in any of this cases:\n* There is not any administrator yet on the server,\n* The subscriptions are not disabled in the server's policies.\n\nIf the first administrator is created by this call, subscriptions are automatically disabled.", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "description": "The email of the new user", "nullable": false }, "password": { "type": "string", "description": "The password of the new user" }, "isAdministrator": { "type": "boolean", "description": "Make this user administrator (only if you have the `unrestricted` permission of a server administrator)", "nullable": true, "default": false } } } } }, "required": true, "x-position": 1 }, "responses": { "201": { "description": "Information about the new user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationUserData" } } } }, "400": { "description": "A list of errors that occurred when creating the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "If you need to authenticate for this endpoint (ie. the server settings policies lock subscriptions and that an admin already exists)" }, "403": { "description": "If you are authenticated but forbidden to create a new user (ie. you don't have the `unrestricted` permission on a server administrator or if you are not administrator and registrations are disabled in the server's policies)" }, "429": { "description": "DDoS protection if you are creating more than 2 accounts every minutes (non-admin only)" } }, "security": [ { "API_Key": [ "btcpay.server.cancreateuser" ], "Basic": [] } ] } }, "/api/v1/users/{idOrEmail}": { "get": { "operationId": "Users_GetUser", "tags": [ "Users" ], "summary": "Get user by ID or Email", "description": "Get 1 user by ID or Email.", "parameters": [ { "name": "idOrEmail", "in": "path", "required": true, "description": "The ID or email of the user to load", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User found" }, "401": { "description": "Missing authorization for loading the user" }, "403": { "description": "Authorized but forbidden to load the user. You have the wrong API permissions." }, "404": { "description": "No user found with this ID or email" } }, "security": [ { "API_Key": [ "btcpay.server.canviewusers" ], "Basic": [] } ] }, "delete": { "operationId": "Users_DeleteUser", "tags": [ "Users" ], "summary": "Delete user", "description": "Delete a user.\n\nMust be an admin to perform this operation.\n\nAttempting to delete the only admin user will not succeed.\n\nAll data associated with the user will be deleted as well if the operation succeeds.", "parameters": [ { "name": "idOrEmail", "in": "path", "required": true, "description": "The ID of the user to be deleted", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User has been successfully deleted" }, "401": { "description": "Missing authorization for deleting the user" }, "403": { "description": "Authorized but forbidden to delete the user. Can happen if you attempt to delete the only admin user." }, "404": { "description": "User with provided ID was not found" } }, "security": [ { "API_Key": [ "btcpay.user.candeleteuser" ], "Basic": [] } ] } }, "/api/v1/users/{idOrEmail}/lock": { "delete": { "operationId": "Users_ToggleUserLock", "tags": [ "Users" ], "summary": "Toggle user", "description": "Lock or unlock a user.\n\nMust be an admin to perform this operation.\n\nAttempting to lock the only admin user will not succeed.", "parameters": [ { "name": "idOrEmail", "in": "path", "required": true, "description": "The ID of the user to be un/locked", "schema": { "type": "string" } } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockUserRequest" } } } }, "responses": { "200": { "description": "User has been successfully toggled" }, "401": { "description": "Missing authorization for deleting the user" }, "403": { "description": "Authorized but forbidden to disable the user. Can happen if you attempt to disable the only admin user." }, "404": { "description": "User with provided ID was not found" } }, "security": [ { "API_Key": [ "btcpay.user.canmodifyserversettings" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get webhooks of a store", "description": "View webhooks of a store", "operationId": "Webhooks_GetWebhooks", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataList" } } } }, "404": { "description": "The key is not found for this list of webhooks" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "post": { "operationId": "Webhooks_CreateWebhook", "tags": [ "Webhooks" ], "summary": "Create a new webhook", "description": "Create a new webhook", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataCreate" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the new webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataCreate" } } } }, "400": { "description": "A list of errors that occurred when creating the webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook of a store", "description": "View webhook of a store", "operationId": "Webhooks_GetWebhook", "responses": { "200": { "description": "A webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookData" } } } }, "404": { "description": "The webhook has not been found" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "put": { "operationId": "Webhooks_UpdateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Update a webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataUpdate" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookData" } } } }, "400": { "description": "A list of errors that occurred when creating the webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "delete": { "operationId": "Webhooks_DeleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Delete a webhook", "responses": { "200": { "description": "The webhook has been deleted" }, "404": { "description": "The webhook does not exist" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "Get latest deliveries", "description": "List the latest deliveries to the webhook, ordered from the most recent", "parameters": [ { "name": "count", "in": "query", "description": "The number of latest deliveries to fetch", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "404": { "description": "The key is not found for this list of deliveries" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Get a webhook delivery", "description": "Information about a webhook delivery", "responses": { "200": { "description": "Information about a delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryData" } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}/request": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDeliveryRequests", "tags": [ "Webhooks" ], "summary": "Get the delivery's request", "description": "The delivery's JSON request sent to the endpoint", "responses": { "200": { "description": "The delivery's JSON Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "post": { "operationId": "Webhooks_RedeliverWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Redeliver the delivery", "description": "Redeliver the delivery", "responses": { "200": { "description": "The new delivery id being broadcasted. (Broadcast happen asynchronously with this call)", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } } }, "components": { "schemas": { "ApiKeyData": { "type": "object", "additionalProperties": false, "properties": { "apiKey": { "type": "string", "description": "The API Key to use for API Key Authentication", "nullable": false }, "label": { "type": "string", "description": "The label given by the user to this API Key", "nullable": false }, "permissions": { "type": "array", "description": "The permissions associated to this API Key", "nullable": false, "items": { "type": "string" } } } }, "PointOfSaleAppData": { "allOf": [ { "$ref": "#/components/schemas/BasicAppData" }, {} ] }, "BasicAppData": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the app", "example": "3ki4jsAkN4u9rv1PUzj1odX4Nx7s" }, "name": { "type": "string", "description": "Name given to the app when it was created", "example": "my test app" }, "storeId": { "type": "string", "description": "Id of the store to which the app belongs", "example": "9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776" }, "created": { "type": "integer", "example": 1651554744, "description": "UNIX timestamp for when the app was created" }, "appType": { "type": "string", "example": "PointOfSale", "description": "Type of the app which was created" } } }, "CustodianData": { "type": "object", "properties": { "code": { "type": "string", "description": "The unique code of the custodian.", "nullable": false }, "label": { "type": "string", "description": "The name of the custodian.", "nullable": false }, "depositablePaymentMethods": { "type": "array", "description": "A list of payment methods (crypto code + network) you can deposit to the custodian.", "nullable": false, "items": { "type": "string" } }, "withdrawablePaymentMethods": { "type": "array", "description": "A list of payment methods (crypto code + network) you can withdraw from the custodian.", "nullable": false, "items": { "type": "string" } }, "tradableAssetPairs": { "type": "array", "description": "A list of tradable asset pair objects, or NULL if the custodian cannot trades/convert assets.", "nullable": true, "items": { "$ref": "#/components/schemas/AssetPairData" } } }, "example": { "code": "kraken", "name": "Kraken", "tradableAssetPairs": { "BTC/USD": { "assetBought": "BTC", "assetSold": "USD", "minimumTradeQty": 0.001 }, "BTC/EUR": { "assetBought": "BTC", "assetSold": "EUR", "minimumTradeQty": 0.001 }, "LTC/USD": { "assetBought": "LTC", "assetSold": "USD", "minimumTradeQty": 0.05 }, "LTC/EUR": { "assetBought": "LTC", "assetSold": "EUR", "minimumTradeQty": 0.05 } }, "withdrawablePaymentMethods": [ "BTC-OnChain", "LTC-OnChain" ], "depositablePaymentMethods": [ "BTC-OnChain", "LTC-OnChain" ] } }, "CustodianAccountData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The unique code of the customer's account with this custodian. The format depends on the custodian." }, "storeId": { "type": "string", "description": "The store ID." }, "custodianCode": { "type": "string", "description": "The code for the custodian." }, "name": { "type": "string", "description": "The name of the custodian account." }, "assetBalances": { "type": "array", "nullable": true, "description": "A real-time loaded list of all assets (fiat and crypto) on this custodian and the quantity held in the account. Assets with qty 0 can be omitted.", "items": { "$ref": "#/components/schemas/AssetBalanceData" } }, "config": { "type": "object", "nullable": true, "description": "The configuration of this custodian account. Specific contents depend on the custodian and your access permissions." } }, "example": { "accountId": "xxxxxxxxxxxxxxx", "storeId": "xxxxxxxxxxxxxx", "custodianCode": "kraken", "name": "My Kraken Account", "assetBalances": [ { "asset": "BTC", "qty": 1.23456 }, { "asset": "USD", "qty": 123456.78 } ], "config": { "WithdrawToAddressNamePerPaymentMethod": { "BTC-OnChain": "My Ledger Nano" }, "ApiKey": "xxx", "PrivateKey": "xxx" } } }, "CreateCustodianAccountRequest": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The unique code of the customer's account with this custodian. The format depends on the custodian." }, "storeId": { "type": "string", "description": "The store ID." }, "custodianCode": { "type": "string", "description": "The code for the custodian." }, "name": { "type": "string", "description": "The name of the custodian account." }, "config": { "type": "object", "nullable": true, "description": "The configuration of this custodian account. Specific contents depend on the custodian and your access permissions." } }, "example": { "accountId": "xxxxxxxxxxxxxxx", "storeId": "xxxxxxxxxxxxxx", "custodianCode": "kraken", "name": "My Kraken Account", "config": { "WithdrawToAddressNamePerPaymentMethod": { "BTC-OnChain": "My Ledger Nano" }, "ApiKey": "xxx", "PrivateKey": "xxx" } } }, "QuoteResultData": { "type": "object", "properties": { "fromAsset": { "type": "string", "description": "The asset to trade.", "nullable": false }, "toAsset": { "type": "string", "description": "The asset you want.", "nullable": false }, "bid": { "type": "number", "description": "The bid price.", "nullable": false }, "ask": { "type": "number", "description": "The ask price", "nullable": false } }, "example": { "fromAsset": "USD", "toAsset": "BTC", "bid": 30000.12, "ask": 30002.24 } }, "TradeRequestData": { "type": "object", "properties": { "fromAsset": { "type": "string", "description": "The asset to trade.", "nullable": false }, "toAsset": { "type": "string", "description": "The asset you want.", "nullable": false }, "qty": { "oneOf": [ { "type": "number", "description": "The qty of fromAsset to convert into toAsset." }, { "type": "string", "description": "The percent of fromAsset to convert into toAsset. The value must end with \"%\" to be considered a percentage." } ], "nullable": false } }, "example": { "fromAsset": "USD", "toAsset": "BTC", "qty": "50%" } }, "TradeResultData": { "type": "object", "properties": { "fromAsset": { "type": "string", "description": "The asset to trade." }, "toAsset": { "type": "string", "description": "The asset you want." }, "ledgerEntries": { "type": "array", "description": "The asset entries that were changed during the trade. This is an array of at least 2 items with the asset sold and the asset gained. It may also include ledger entries for the costs of the trade and possibly exchange tokens used.", "items": { "$ref": "#/components/schemas/LedgerEntryData" } }, "tradeId": { "type": "string", "description": "The unique ID of the trade used by the exchange. This ID can be used to get the details of this trade at a later time.", "nullable": true }, "accountId": { "type": "string", "description": "The unique ID of the custodian account used.", "nullable": false }, "custodianCode": { "type": "string", "description": "The code of the custodian used.", "nullable": false } }, "example": { "fromAsset": "USD", "toAsset": "BTC", "ledgerEntries": [ { "asset": "BTC", "qty": 1.23456, "type": "Trade" }, { "asset": "USD", "qty": -61728, "type": "Trade" }, { "asset": "BTC", "qty": -0.00123456, "type": "Fee" }, { "asset": "KFEE", "qty": -123.456, "type": "Fee" } ], "tradeId": "XXXX-XXXX-XXXX-XXXX", "accountId": "xxxxxxxxxxxxxx", "custodianCode": "kraken" } }, "WithdrawalRequestData": { "type": "object", "properties": { "paymentMethod": { "type": "string", "description": "The payment method (cryptocode + network) of the withdrawal.", "nullable": false }, "qty": { "type": "number", "description": "The qty to withdraw.", "nullable": false } }, "example": { "paymentMethod": "BTC-OnChain", "qty": 0.123456 } }, "WithdrawalResultData": { "type": "object", "properties": { "asset": { "type": "string", "description": "The asset that is being withdrawn." }, "paymentMethod": { "type": "string", "description": "The payment method that is used (crypto code + network)." }, "ledgerEntries": { "type": "array", "description": "The asset entries that were changed during the withdrawal. The first item is always the withdrawal itself. It could also includes ledger entries for the costs and may include credits or exchange tokens to give a discount.", "items": { "$ref": "#/components/schemas/LedgerEntryData" } }, "withdrawalId": { "type": "string", "description": "The unique ID of the withdrawal used by the exchange.", "nullable": true }, "accountId": { "type": "string", "description": "The unique ID of the custodian account used.", "nullable": false }, "custodianCode": { "type": "string", "description": "The code of the custodian used.", "nullable": false }, "status": { "type": "string", "description": "The status of the withdrawal: 'Queued', 'Complete', 'Failed' or 'Unknown'.", "nullable": false }, "transactionId": { "type": "string", "description": "The transaction ID on the blockchain once the withdrawal has been executed.", "nullable": true }, "targetAddress": { "type": "string", "description": "The address where the funds were sent to once the withdrawal has been executed.", "nullable": true } }, "example": { "asset": "BTC", "paymentMethod": "BTC-OnChain", "ledgerEntries": [ { "asset": "BTC", "qty": -0.123456, "type": "Withdrawal" }, { "asset": "BTC", "qty": -0.005, "type": "Fee" } ], "withdrawalId": "XXXX-XXXX-XXXX-XXXX", "accountId": "xxxxxxxxxxxxxxx", "custodianCode": "kraken", "status": "Complete", "transactionId": "xxxxxxxxxxxxxxx", "targetAddress": "bc1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, "LedgerEntryData": { "type": "object", "description": "A single ledger entry meaning an asset and qty has changed (increased or decreased).", "properties": { "asset": { "type": "string", "description": "An asset.", "nullable": false }, "qty": { "type": "number", "description": "The quantity changed of the asset. Can be positive or negative.", "nullable": false }, "type": { "type": "string", "description": "Trade, Fee or Withdrawal", "nullable": false } }, "example": { "asset": "BTC", "qty": 1.23456, "type": "Trade" } }, "AssetBalanceData": { "type": "object", "description": "An asset and it's qty.", "properties": { "asset": { "type": "string", "description": "An asset.", "nullable": false }, "qty": { "type": "number", "description": "The quantity changed of the asset. Can be positive or negative.", "nullable": false } }, "example": { "asset": "BTC", "qty": 1.23456 } }, "AssetPairData": { "type": "object", "description": "An asset pair we can trade.", "properties": { "pair": { "type": "string", "description": "The name of the asset pair.", "nullable": false }, "minimumTradeQty": { "type": "number", "description": "The smallest amount we can buy or sell.", "nullable": false } }, "example": { "assetBought": "BTC", "assetSold": "USD", "minimumTradeQty": 0.0001 } }, "ApplicationHealthData": { "type": "object", "additionalProperties": false, "properties": { "synchronized": { "type": "boolean", "description": "True if the instance is fully synchronized, according to NBXplorer" } } }, "InvoiceDataList": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceData" } }, "MarkInvoiceStatusRequest": { "type": "object", "additionalProperties": false, "properties": { "status": { "nullable": false, "description": "Mark an invoice as completed or invalid.", "$ref": "#/components/schemas/InvoiceStatusMark" } } }, "InvoiceStatusMark": { "type": "string", "description": "", "x-enumNames": [ "Invalid", "Settled" ], "enum": [ "Invalid", "Settled" ] }, "InvoiceStatus": { "type": "string", "description": "", "x-enumNames": [ "New", "Processing", "Expired", "Invalid", "Settled" ], "enum": [ "New", "Processing", "Expired", "Invalid", "Settled" ] }, "InvoiceAdditionalStatus": { "type": "string", "description": "An additional status that describes why an invoice is in its current status.", "x-enumNames": [ "None", "PaidLate", "PaidPartial", "Marked", "Invalid", "PaidOver" ], "enum": [ "None", "PaidLate", "PaidPartial", "Marked", "Invalid", "PaidOver" ] }, "InvoiceDataBase": { "properties": { "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" }, "checkout": { "nullable": true, "$ref": "#/components/schemas/CheckoutOptions", "description": "Additional settings to customize the checkout flow" }, "receipt": { "nullable": true, "$ref": "#/components/schemas/ReceiptOptions", "description": "Additional settings to customize the public receipt" } } }, "InvoiceData": { "allOf": [ { "$ref": "#/components/schemas/InvoiceDataBase" }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The identifier of the invoice" }, "storeId": { "type": "string", "description": "The store identifier that the invoice belongs to" }, "amount": { "type": "string", "format": "decimal", "description": "The amount of the invoice", "example": "5.00" }, "currency": { "type": "string", "description": "The currency of the invoice", "example": "USD" }, "type": { "$ref": "#/components/schemas/InvoiceType", "description": "The type of invoice" }, "checkoutLink": { "type": "string", "description": "The link to the checkout page, where you can redirect the customer" }, "createdTime": { "description": "The creation time of the invoice", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "expirationTime": { "description": "The expiration time of the invoice", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "monitoringTime": { "description": "The monitoring time of the invoice", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus", "description": "The status of the invoice" }, "additionalStatus": { "$ref": "#/components/schemas/InvoiceAdditionalStatus", "description": "a secondary status of the invoice" }, "availableStatusesForManualMarking": { "type": "array", "description": "The statuses the invoice can be manually marked as", "items": { "$ref": "#/components/schemas/InvoiceStatus" } }, "archived": { "type": "boolean", "description": "true if the invoice is archived" } } } ] }, "InvoiceMetadataPosString": { "type": "string", "description": "shown on the invoice details page" }, "InvoiceMetadataPosObject": { "type": "object", "description": "Any json object in any schema you want. Will be rendered on a best effort basis in terms of style on the invoice details UI" }, "InvoiceMetadata": { "type": "object", "additionalProperties": true, "description": "Additional information around the invoice that can be supplied. The mentioned properties are all optional and you can introduce any json format you wish.", "anyOf": [ { "properties": { "orderId": { "type": "string", "nullable": true, "description": "You can use this property to store the ID of an external system. We allow you to search in the invoice list based on this ID." }, "orderUrl": { "type": "string", "nullable": true, "description": "You can use this property to store the URL to the order of an external system. This makes navigating to the order easier." } } }, { "properties": { "posData": { "oneOf": [ { "$ref": "#/components/schemas/InvoiceMetadataPosString" }, { "$ref": "#/components/schemas/InvoiceMetadataPosObject" } ] } } }, { "properties": { "buyerName": { "type": "string", "nullable": true } } }, { "properties": { "buyerEmail": { "type": "string", "nullable": true } } }, { "properties": { "buyerCountry": { "type": "string", "nullable": true } } }, { "properties": { "buyerZip": { "type": "string", "nullable": true } } }, { "properties": { "buyerState": { "type": "string", "nullable": true } } }, { "properties": { "buyerCity": { "type": "string", "nullable": true } } }, { "properties": { "buyerAddress1": { "type": "string", "nullable": true } } }, { "properties": { "buyerAddress2": { "type": "string", "nullable": true } } }, { "properties": { "buyerPhone": { "type": "string", "nullable": true } } }, { "properties": { "itemDesc": { "type": "string", "nullable": true } } }, { "properties": { "itemCode": { "type": "string", "nullable": true } } }, { "properties": { "physical": { "type": "string", "nullable": true } } }, { "properties": { "taxIncluded": { "type": "number", "nullable": true } } } ] }, "CreateInvoiceRequest": { "allOf": [ { "$ref": "#/components/schemas/InvoiceDataBase" }, { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "format": "decimal", "nullable": true, "description": "The amount of the invoice. If null or unspecified, the invoice will be a top-up invoice. (ie. The invoice will consider any payment as a full payment)", "example": "5.00" }, "currency": { "type": "string", "description": "The currency of the invoice (if null, empty or unspecified, the currency will be the store's settings default)'", "nullable": true, "example": "USD" }, "additionalSearchTerms": { "type": "array", "items": { "type": "string" }, "description": "Additional search term to help you find this invoice via text search", "nullable": true } } } ] }, "UpdateInvoiceRequest": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" } } }, "CheckoutOptions": { "type": "object", "additionalProperties": false, "properties": { "speedPolicy": { "nullable": true, "$ref": "#/components/schemas/SpeedPolicy", "description": "This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency" }, "paymentMethods": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "A specific set of payment methods to use for this invoice (ie. BTC, BTC-LightningNetwork). By default, select all payment methods enabled in the store." }, "defaultPaymentMethod": { "type": "string", "nullable": true, "description": "Default payment type for the invoice (e.g., BTC, BTC-LightningNetwork). Default payment method set for the store is used if this parameter is not specified." }, "expirationMinutes": { "nullable": true, "description": "The number of minutes after which an invoice becomes expired. Defaults to the store's settings. (The default store settings is 15)", "allOf": [ { "$ref": "#/components/schemas/TimeSpanMinutes" } ] }, "monitoringMinutes": { "type": "number", "nullable": true, "description": "The number of minutes after an invoice expired after which we are still monitoring for incoming payments. Defaults to the store's settings. (The default store settings is 1440, 1 day)", "allOf": [ { "$ref": "#/components/schemas/TimeSpanMinutes" } ] }, "paymentTolerance": { "type": "number", "format": "double", "nullable": true, "minimum": 0, "maximum": 100, "description": "A percentage determining whether to count the invoice as paid when the invoice is paid within the specified margin of error. Defaults to the store's settings. (The default store settings is 100)" }, "redirectURL": { "type": "string", "nullable": true, "description": "When the customer has paid the invoice, the URL where the customer will be redirected when clicking on the `return to store` button. You can use placeholders `{InvoiceId}` or `{OrderId}` in the URL, BTCPay Server will replace those with this invoice `id` or `metadata.orderId` respectively." }, "redirectAutomatically": { "type": "boolean", "nullable": true, "description": "When the customer has paid the invoice, and a `redirectURL` is set, the checkout is redirected to `redirectURL` automatically if `redirectAutomatically` is true. Defaults to the store's settings. (The default store settings is false)" }, "requiresRefundEmail": { "type": "boolean", "nullable": true, "description": "Invoice will require user to provide a refund email if this option is set to `true`. Has no effect if `buyerEmail` metadata is set as there is no email to collect in this case." }, "defaultLanguage": { "type": "string", "nullable": true, "description": "The language code (eg. en-US, en, fr-FR...) of the language presented to your customer in the checkout page. BTCPay Server tries to match the best language available. If null or not set, will fallback on the store's default language. You can see the list of language codes with [this operation](#operation/langCodes)." } } }, "ReceiptOptions": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "nullable": true, "description": "A public page will be accessible once the invoice is settled. If null or unspecified, it will fallback to the store's settings. (The default store settings is true)" }, "showQR": { "type": "boolean", "nullable": true, "default": null, "description": "Show the QR code of the receipt in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)" }, "showPayments": { "type": "boolean", "nullable": true, "default": null, "description": "Show the payment list in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)" } } }, "InvoicePaymentMethodDataModel": { "type": "object", "additionalProperties": false, "properties": { "paymentMethod": { "type": "string", "description": "Payment method available for the invoice (e.g., \"BTC\" or \"BTC-LightningNetwork\" or \"BTC-LNURLPAY\")" }, "cryptoCode": { "type": "string", "description": "Crypto code of the payment method (e.g., \"BTC\" or \"LTC\")", "example": "BTC" }, "destination": { "type": "string", "description": "The destination the payment must be made to" }, "paymentLink": { "type": "string", "nullable": true, "description": "A payment link that helps pay to the payment destination" }, "rate": { "type": "string", "format": "decimal", "description": "The rate between this payment method's currency and the invoice currency" }, "paymentMethodPaid": { "type": "string", "format": "decimal", "description": "The amount paid by this payment method" }, "totalPaid": { "type": "string", "format": "decimal", "description": "The total amount paid by all payment methods to the invoice, converted to this payment method's currency" }, "due": { "type": "string", "format": "decimal", "description": "The total amount left to be paid, converted to this payment method's currency (will be negative if overpaid)" }, "amount": { "type": "string", "format": "decimal", "description": "The invoice amount, converted to this payment method's currency" }, "networkFee": { "type": "string", "format": "decimal", "description": "The added merchant fee to pay for network costs of this payment method." }, "payments": { "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/Payment" }, "description": "Payments made with this payment method." }, "activated": { "type": "boolean", "description": "If the payment method is activated (when lazy payments option is enabled" }, "additionalData": { "description": "Additional data provided by the payment method.", "anyOf": [ { "type": "object", "description": "LNURL Pay information", "properties": { "providedComment": { "type": "string", "nullable": true, "description": "The provided comment to a LNUrl payment with comments enabled", "example": "Thank you!" }, "consumedLightningAddress": { "type": "string", "nullable": true, "description": "The consumed lightning address of a LN Address payment", "example": "customer@example.com" } } }, { "type": "object", "description": "No additional information" } ] } } }, "Payment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "A unique identifier for this payment" }, "receivedDate": { "description": "The date the payment was recorded", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "value": { "type": "string", "format": "decimal", "description": "The value of the payment" }, "fee": { "type": "string", "format": "decimal", "description": "The fee paid for the payment" }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "The status of the payment" }, "destination": { "type": "string", "description": "The destination the payment was made to" } } }, "PaymentStatus": { "type": "string", "description": "", "x-enumNames": [ "Invalid", "Processing", "Settled" ], "enum": [ "Invalid", "Processing", "Settled" ] }, "InvoiceType": { "type": "string", "description": "", "x-enumNames": [ "Standard", "TopUp" ], "enum": [ "Standard", "TopUp" ] }, "ValidationProblemDetails": { "type": "array", "description": "An array of validation errors of the request", "items": { "type": "object", "description": "A specific validation error on a json property", "properties": { "path": { "type": "string", "nullable": false, "description": "The json path of the property which failed validation" }, "message": { "type": "string", "nullable": false, "description": "User friendly error message about the validation" } } } }, "ProblemDetails": { "type": "object", "description": "Description of an error happening during processing of the request", "properties": { "code": { "type": "string", "nullable": false, "description": "An error code describing the error" }, "message": { "type": "string", "nullable": false, "description": "User friendly error message about the error" } } }, "UnixTimestamp": { "type": "number", "format": "int32", "example": 1592312018, "description": "A unix timestamp in seconds" }, "SpeedPolicy": { "type": "string", "description": "`\"HighSpeed\"`: 0 confirmations (1 confirmation if RBF enabled in transaction) \n`\"MediumSpeed\"`: 1 confirmation \n`\"LowMediumSpeed\"`: 2 confirmations \n`\"LowSpeed\"`: 6 confirmations\n", "x-enumNames": [ "HighSpeed", "MediumSpeed", "LowSpeed", "LowMediumSpeed" ], "enum": [ "HighSpeed", "MediumSpeed", "LowSpeed", "LowMediumSpeed" ] }, "TimeSpan": { "type": "number", "format": "int32", "example": 90 }, "TimeSpanSeconds": { "allOf": [ { "$ref": "#/components/schemas/TimeSpan" } ], "format": "seconds", "description": "A span of times in seconds" }, "TimeSpanMinutes": { "allOf": [ { "$ref": "#/components/schemas/TimeSpan" } ], "format": "minutes", "description": "A span of times in minutes" }, "ConnectToNodeRequest": { "type": "object", "additionalProperties": false, "properties": { "nodeURI": { "type": "string", "nullable": true, "description": "Node URI in the form `pubkey@endpoint[:port]`" } } }, "CreateLightningInvoiceRequest": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount wrapped in a string, represented in a millistatoshi string. (1000 millisatoshi = 1 satoshi)", "nullable": false }, "description": { "type": "string", "nullable": true, "description": "Description of the invoice in the BOLT11" }, "descriptionHash": { "type": "string", "format": "hex", "nullable": true, "description": "Description hash of the invoice in the BOLT11" }, "expiry": { "description": "Expiration time in seconds", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] }, "privateRouteHints": { "type": "boolean", "nullable": true, "default": false, "description": "True if the invoice should include private route hints" } } }, "LightningChannelData": { "type": "object", "additionalProperties": false, "properties": { "remoteNode": { "type": "string", "nullable": false, "description": "The public key of the node (Node ID)" }, "isPublic": { "type": "boolean", "description": "Whether the node is public" }, "isActive": { "type": "boolean", "description": "Whether the node is online" }, "capacity": { "type": "string", "description": "The capacity of the channel in millisatoshi", "nullable": false }, "localBalance": { "type": "string", "description": "The local balance of the channel in millisatoshi", "nullable": false }, "channelPoint": { "type": "string", "nullable": true } } }, "LightningPaymentData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The payment's ID" }, "status": { "$ref": "#/components/schemas/LightningPaymentStatus" }, "BOLT11": { "type": "string", "description": "The BOLT11 representation of the payment", "nullable": false }, "paymentHash": { "type": "string", "description": "The payment hash", "nullable": false }, "preimage": { "type": "string", "description": "The payment preimage (available when status is complete)" }, "createdAt": { "description": "The unix timestamp when the payment got created", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "totalAmount": { "type": "string", "description": "The total amount (including fees) in millisatoshi" }, "feeAmount": { "type": "string", "description": "The total fees in millisatoshi" } } }, "LightningInvoiceData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The invoice's ID" }, "status": { "$ref": "#/components/schemas/LightningInvoiceStatus" }, "BOLT11": { "type": "string", "description": "The BOLT11 representation of the invoice", "nullable": false }, "paidAt": { "description": "The unix timestamp when the invoice got paid", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "expiresAt": { "description": "The unix timestamp when the invoice expires", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "amount": { "type": "string", "description": "The amount of the invoice in millisatoshi" }, "amountReceived": { "type": "string", "description": "The amount received in millisatoshi" } } }, "LightningInvoiceStatus": { "type": "string", "description": "", "x-enumNames": [ "Unpaid", "Paid", "Expired" ], "enum": [ "Unpaid", "Paid", "Expired" ] }, "LightningPaymentStatus": { "type": "string", "description": "", "x-enumNames": [ "Unknown", "Pending", "Complete", "Failed" ], "enum": [ "Unknown", "Pending", "Complete", "Failed" ] }, "LightningNodeInformationData": { "type": "object", "properties": { "nodeURIs": { "type": "array", "description": "Node URIs to connect to this node in the form `pubkey@endpoint[:port]`", "items": { "type": "string" } }, "blockHeight": { "type": "integer", "description": "The block height of the lightning node" } } }, "LightningNodeBalanceData": { "type": "object", "properties": { "onchain": { "type": "object", "description": "On-chain balance of the Lightning node", "nullable": true, "$ref": "#/components/schemas/OnchainBalanceData" }, "offchain": { "type": "object", "description": "Off-chain balance of the Lightning node", "nullable": true, "$ref": "#/components/schemas/OffchainBalanceData" } } }, "OnchainBalanceData": { "type": "object", "properties": { "confirmed": { "type": "string", "description": "The confirmed amount in satoshi", "nullable": true }, "unconfirmed": { "type": "string", "description": "The unconfirmed amount in satoshi", "nullable": true }, "reserved": { "type": "string", "description": "The reserved amount in satoshi", "nullable": true } } }, "OffchainBalanceData": { "type": "object", "properties": { "opening": { "type": "string", "description": "The amount of current channel openings in millisatoshi", "nullable": true }, "local": { "type": "string", "description": "The amount that is available on the local end of active channels in millisatoshi", "nullable": true }, "remote": { "type": "string", "description": "The amount that is available on the remote end of active channels in millisatoshi", "nullable": true }, "closing": { "type": "string", "description": "The amount of current channel closings in millisatoshi", "nullable": true } } }, "PayLightningInvoiceRequest": { "type": "object", "properties": { "BOLT11": { "type": "string", "description": "The BOLT11 of the invoice to pay" }, "amount": { "type": "string", "description": "Optional explicit payment amount in millisatoshi (if specified, it overrides the BOLT11 amount)", "nullable": true }, "maxFeePercent": { "type": "string", "format": "float", "nullable": true, "description": "The fee limit expressed as a percentage of the payment amount", "example": "6.15" }, "maxFeeFlat": { "type": "string", "nullable": true, "description": "The fee limit expressed as a fixed amount in satoshi", "example": "21" } } }, "OpenLightningChannelRequest": { "type": "object", "additionalProperties": false, "properties": { "nodeURI": { "type": "string", "description": "Node URI in the form `pubkey@endpoint[:port]`" }, "channelAmount": { "type": "string", "description": "The amount to fund (in satoshi)" }, "feeRate": { "type": "number", "description": "The amount to fund (in satoshi per byte)" } } }, "UpdateNotification": { "type": "object", "additionalProperties": false, "properties": { "seen": { "type": "boolean", "nullable": true, "description": "Sets the notification as seen/unseen. If left null, sets it to the opposite value" } } }, "NotificationData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The identifier of the notification" }, "body": { "type": "string", "format": "html", "description": "The html body of the notifications" }, "link": { "type": "string", "format": "uri", "nullable": true, "description": "The link of the notification" }, "createdTime": { "description": "The creation time of the notification", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "seen": { "type": "boolean", "description": "If the notification has been seen by the user" } } }, "PaymentRequestDataList": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestData" } }, "PaymentRequestData": { "allOf": [ { "$ref": "#/components/schemas/PaymentRequestBaseData" }, { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the payment request", "nullable": false }, "storeId": { "type": "string", "description": "The store identifier that the payment request belongs to" }, "status": { "type": "string", "enum": [ "Pending", "Completed", "Expired" ], "description": "The status of the payment request", "nullable": false }, "createdTime": { "description": "The creation date of the payment request", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ], "nullable": false } } } ] }, "PaymentRequestBaseData": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "format": "decimal", "minimum": 0, "exclusiveMinimum": true, "description": "The amount of the payment request", "nullable": false }, "title": { "type": "string", "description": "The title of the payment request", "nullable": false }, "currency": { "type": "string", "format": "ISO 4217 Currency code(BTC, EUR, USD, etc)", "description": "The currency of the payment request. If empty, the store's default currency code will be used.", "nullable": true }, "email": { "type": "string", "description": "The email used in invoices generated by the payment request", "nullable": true, "format": "email" }, "description": { "type": "string", "description": "The description of the payment request", "nullable": true, "format": "html" }, "expiryDate": { "description": "The expiry date of the payment request", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "embeddedCSS": { "type": "string", "description": "Custom CSS styling for the payment request", "nullable": true, "format": "css", "maximum": 500 }, "customCSSLink": { "type": "string", "description": "Custom CSS link for styling the payment request", "nullable": true, "format": "uri" }, "allowCustomPaymentAmounts": { "type": "boolean", "description": "Whether to allow users to create invoices that partially pay the payment request ", "nullable": true } } }, "PayoutProcessorData": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "unique identifier of the payout processor", "type": "string" }, "friendlyName": { "description": "Human name of the payout processor", "type": "string" }, "paymentMethods": { "nullable": true, "description": "Supported, payment methods by this processor", "type": "array", "items": { "type": "string" } } } }, "UpdateLightningAutomatedTransferSettings": { "type": "object", "additionalProperties": false, "properties": { "intervalSeconds": { "description": "How often should the processor run", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] } } }, "LightningAutomatedTransferSettings": { "type": "object", "additionalProperties": false, "properties": { "paymentMethod": { "description": "payment method of the payout processor", "type": "string" }, "intervalSeconds": { "description": "How often should the processor run", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] } } }, "UpdateOnChainAutomatedTransferSettings": { "type": "object", "additionalProperties": false, "properties": { "intervalSeconds": { "description": "How often should the processor run", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] } } }, "OnChainAutomatedTransferSettings": { "type": "object", "additionalProperties": false, "properties": { "paymentMethod": { "description": "payment method of the payout processor", "type": "string" }, "intervalSeconds": { "description": "How often should the processor run", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] } } }, "PullPaymentDataList": { "type": "array", "items": { "$ref": "#/components/schemas/PullPaymentData" } }, "PayoutDataList": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutData" } }, "CreatePayoutRequest": { "type": "object", "properties": { "destination": { "type": "string", "example": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2", "description": "The destination of the payout (can be an address or a BIP21 url)" }, "amount": { "type": "string", "format": "decimal", "example": "10399.18", "description": "The amount of the payout in the currency of the pull payment (eg. USD)." }, "paymentMethod": { "type": "string", "example": "BTC", "description": "The payment method of the payout" } } }, "CreatePayoutThroughStoreRequest": { "allOf": [ { "$ref": "#/components/schemas/CreatePayoutRequest" }, { "type": "object", "properties": { "pullPaymentId": { "type": "string", "description": "The pull payment to create this for. Optional." }, "approved": { "type": "boolean", "description": "Whether to approve this payout automatically upon creation" } } } ] }, "PayoutData": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the payout" }, "revision": { "type": "integer", "description": "The revision number of the payout. This revision number is incremented when the payout amount or destination is modified before the approval." }, "pullPaymentId": { "type": "string", "description": "The id of the pull payment this payout belongs to" }, "date": { "type": "string", "description": "The creation date of the payout as a unix timestamp" }, "destination": { "type": "string", "example": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2", "description": "The destination of the payout (can be an address or a BIP21 url)" }, "amount": { "type": "string", "format": "decimal", "example": "10399.18", "description": "The amount of the payout in the currency of the pull payment (eg. USD)." }, "paymentMethod": { "type": "string", "example": "BTC", "description": "The payment method of the payout (e.g., \"BTC\" or \"BTC_LightningLike\"" }, "cryptoCode": { "type": "string", "example": "BTC", "description": "Crypto code of the payment method of the payout (e.g., \"BTC\" or \"LTC\")" }, "paymentMethodAmount": { "type": "string", "format": "decimal", "nullable": true, "example": "1.12300000", "description": "The amount of the payout in the currency of the payment method (eg. BTC). This is only available from the `AwaitingPayment` state." }, "state": { "type": "string", "example": "AwaitingPayment", "description": "The state of the payout (`AwaitingApproval`, `AwaitingPayment`, `InProgress`, `Completed`, `Cancelled`)", "x-enumNames": [ "AwaitingApproval", "AwaitingPayment", "InProgress", "Completed", "Cancelled" ], "enum": [ "AwaitingApproval", "AwaitingPayment", "InProgress", "Completed", "Cancelled" ] } } }, "PullPaymentData": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the pull payment" }, "name": { "type": "string", "description": "Name given to pull payment when it was created" }, "description": { "type": "string", "description": "Description given to pull payment when it was created" }, "currency": { "type": "string", "example": "BTC", "description": "The currency of the pull payment's amount" }, "amount": { "type": "string", "format": "decimal", "example": "1.12000000", "description": "The amount in the currency of this pull payment as a decimal string" }, "period": { "type": "integer", "example": 604800, "nullable": true, "description": "The length of each period in seconds" }, "BOLT11Expiration": { "type": "string", "example": 30, "description": "If lightning is activated, do not accept BOLT11 invoices with expiration less than … days" }, "autoApproveClaims": { "type": "boolean", "example": false, "default": false, "nullable": true, "description": "Any payouts created for this pull payment will skip the approval phase upon creation" }, "archived": { "type": "boolean", "description": "Whether this pull payment is archived" }, "viewLink": { "type": "string", "description": "The link to a page to claim payouts to this pull payment" } } }, "ApplicationServerInfoData": { "type": "object", "properties": { "version": { "type": "string", "description": "BTCPay Server version" }, "onion": { "type": "string", "description": "The Tor hostname" }, "supportedPaymentMethods": { "type": "array", "description": "The payment methods this server supports", "items": { "type": "string" } }, "fullySynched": { "type": "boolean", "description": "True if the instance is fully synchronized, according to NBXplorer" }, "syncStatus": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationServerInfoSyncStatusData" } } } }, "ApplicationServerInfoNodeStatusData": { "type": "object", "nullable": true, "description": "Detailed sync status of the internal full node", "properties": { "headers": { "type": "integer", "description": "The height of the chain of header of the internal full node" }, "blocks": { "type": "integer", "description": "The height of the latest validated block of the internal full node" }, "verificationProgress": { "type": "number", "format": "double", "minimum": 0, "maximum": 1, "description": "The current synchronization progress" } } }, "ApplicationServerInfoSyncStatusData": { "type": "object", "description": "Detailed sync status", "properties": { "cryptoCode": { "type": "string", "description": "The CryptoCode of the crypto currency (eg. BTC)", "example": "BTC" }, "nodeInformation": { "$ref": "#/components/schemas/ApplicationServerInfoNodeStatusData" }, "chainHeight": { "type": "integer", "description": "The height of the chain of header of the internal indexer" }, "syncHeight": { "type": "number", "format": "integer", "nullable": true, "description": "The height of the latest indexed block of the internal indexer" }, "available": { "type": "boolean", "description": "True if the full node and the indexer are fully synchronized", "nullable": false } } }, "EmailData": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "description": "Email of the recipient" }, "subject": { "type": "string", "description": "Subject of the email" }, "body": { "type": "string", "description": "Body of the email to send as plain text." } } }, "EmailSettingsData": { "type": "object", "additionalProperties": false, "properties": { "server": { "type": "string", "description": "Smtp server host" }, "port": { "type": "number", "description": "Smtp server port" }, "login": { "type": "string", "description": "Smtp server username" }, "password": { "type": "string", "description": "Smtp server password" }, "from": { "type": "string", "format": "email", "description": "Email to send from" }, "fromDisplay": { "type": "string", "description": "The name of the sender" } } }, "GenericPaymentMethodData": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled" }, "cryptoCode": { "type": "string", "description": "The currency code of the payment method" }, "data": { "type": "object", "additionalProperties": false, "description": "Associated dynamic data based on payment method type.", "oneOf": [ { "$ref": "#/components/schemas/OnChainPaymentMethodBaseData" }, { "$ref": "#/components/schemas/LightningNetworkPaymentMethodBaseData" }, { "description": "Any other unofficial payment method data", "type": "object", "additionalProperties": true } ] } } }, "LightningNetworkPaymentMethodDataList": { "type": "array", "items": { "$ref": "#/components/schemas/LightningNetworkPaymentMethodData" } }, "LightningNetworkPaymentMethodBaseData": { "type": "object", "additionalProperties": false, "properties": { "connectionString": { "type": "string", "description": "The lightning connection string. Set to 'Internal Node' to use the internal node. (See [this doc](https://github.com/btcpayserver/BTCPayServer.Lightning/blob/master/README.md#examples) for some example)", "example": "type=clightning;server=..." }, "disableBOLT11PaymentOption": { "type": "boolean", "description": "Whether to disable generation of bolt11 invoices. Useful when wanting to only use LNURL Pay exclusively." } } }, "LightningNetworkPaymentMethodData": { "allOf": [ { "$ref": "#/components/schemas/LightningNetworkPaymentMethodBaseData" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled" }, "cryptoCode": { "type": "string", "description": "Crypto code of the payment method" }, "paymentMethod": { "type": "string", "description": "The payment method" } } } ] }, "UpdateLightningNetworkPaymentMethodRequest": { "allOf": [ { "$ref": "#/components/schemas/LightningNetworkPaymentMethodBaseData" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled" } } } ] }, "LNURLPayPaymentMethodDataList": { "type": "array", "items": { "$ref": "#/components/schemas/LNURLPayPaymentMethodData" } }, "LNURLPayPaymentMethodBaseData": { "type": "object", "additionalProperties": false, "properties": { "useBech32Scheme": { "type": "boolean", "description": "Whether to use [LUD-01](https://github.com/fiatjaf/lnurl-rfc/blob/luds/01.md)'s bech32 format or to use [LUD-17](https://github.com/fiatjaf/lnurl-rfc/blob/luds/17.md) url formatting. " }, "enableForStandardInvoices": { "type": "boolean", "description": "Whether to allow this payment method to also be used for standard invoices and not just topup invoices." }, "lud12Enabled": { "type": "boolean", "description": "Allow comments to be passed on via lnurl." } } }, "LNURLPayPaymentMethodData": { "allOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled. Note that this can only enabled when a Lightning Network payment method is available and enabled" }, "cryptoCode": { "type": "string", "description": "Crypto code of the payment method" } } }, { "$ref": "#/components/schemas/LNURLPayPaymentMethodBaseData" } ] }, "OnChainPaymentMethodDataList": { "type": "array", "items": { "$ref": "#/components/schemas/OnChainPaymentMethodData" } }, "OnChainPaymentMethodDataWithSensitiveData": { "allOf": [ { "$ref": "#/components/schemas/OnChainPaymentMethodData" }, { "type": "object", "properties": { "mnemonic": { "type": "string", "description": "The mnemonic used to generate the wallet", "nullable": false } } } ] }, "OnChainPaymentMethodBaseData": { "type": "object", "additionalProperties": false, "properties": { "derivationScheme": { "type": "string", "description": "The derivation scheme", "example": "xpub..." }, "label": { "type": "string", "description": "A label that will be shown in the UI" }, "accountKeyPath": { "type": "string", "description": "The wallet fingerprint followed by the keypath to derive the account key used for signing operation or creating PSBTs", "example": "abcd82a1/84'/0'/0'" } } }, "UpdateOnChainPaymentMethodRequest": { "allOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled" } } }, { "$ref": "#/components/schemas/OnChainPaymentMethodBaseData" } ] }, "OnChainPaymentMethodData": { "allOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the payment method is enabled" }, "paymentMethod": { "type": "string", "description": "The payment method" } } }, { "$ref": "#/components/schemas/OnChainPaymentMethodDataPreview" } ] }, "OnChainPaymentMethodDataPreview": { "allOf": [ { "$ref": "#/components/schemas/OnChainPaymentMethodBaseData" }, { "type": "object", "properties": { "cryptoCode": { "type": "string", "description": "Crypto code of the payment method" } } } ] }, "OnChainPaymentMethodPreviewResultData": { "type": "object", "additionalProperties": false, "properties": { "addresses": { "type": "array", "description": "a list of addresses generated by the derivation scheme", "items": { "$ref": "#/components/schemas/OnChainPaymentMethodPreviewResultAddressItem" } } } }, "OnChainPaymentMethodPreviewResultAddressItem": { "type": "object", "additionalProperties": false, "properties": { "keyPath": { "type": "string", "description": "The key path relative to the account key path." }, "address": { "type": "string", "description": "The address generated at the key path" } } }, "GenerateOnChainWalletRequest": { "type": "object", "additionalProperties": false, "properties": { "existingMnemonic": { "type": "string", "description": "An existing BIP39 mnemonic seed to generate the wallet with" }, "passphrase": { "type": "string", "description": "A passphrase for the BIP39 mnemonic seed" }, "accountNumber": { "type": "number", "default": 0, "description": "The account to derive from the BIP39 mnemonic seed" }, "savePrivateKeys": { "type": "boolean", "default": false, "description": "Whether to store the seed inside BTCPay Server to enable some additional services. IF `false` AND `existingMnemonic` IS NOT SPECIFIED, BE SURE TO SECURELY STORE THE SEED IN THE RESPONSE!" }, "importKeysToRPC": { "type": "boolean", "default": false, "description": "Whether to import all addresses generated via BTCPay Server into the underlying node wallet. (Private keys will also be imported if `savePrivateKeys` is set to true." }, "wordList": { "type": "string", "description": "If `existingMnemonic` is not set, a mnemonic is generated using the specified wordList.", "default": "English", "x-enumNames": [ "English", "Japanese", "Spanish", "ChineseSimplified", "ChineseTraditional", "French", "PortugueseBrazil", "Czech" ], "enum": [ "English", "Japanese", "Spanish", "ChineseSimplified", "ChineseTraditional", "French", "PortugueseBrazil", "Czech" ] }, "wordCount": { "type": "number", "description": "If `existingMnemonic` is not set, a mnemonic is generated using the specified wordCount.", "default": 12, "x-enumNames": [ 12, 15, 18, 21, 24 ], "enum": [ 12, 15, 18, 21, 24 ] }, "scriptPubKeyType": { "type": "string", "description": "the type of wallet to generate", "default": "Segwit", "x-enumNames": [ "Legacy", "Segwit", "SegwitP2SH" ], "enum": [ "Legacy", "Segwit", "SegwitP2SH" ] } } }, "StoreUserDataList": { "type": "array", "items": { "$ref": "#/components/schemas/StoreData" } }, "StoreUserData": { "allOf": [ { "type": "object", "properties": { "userId": { "type": "string", "description": "The id of the user", "nullable": false }, "role": { "type": "string", "description": "The role of the user. Default roles are `Owner` and `Guest`", "nullable": false } } } ] }, "OnChainWalletOverviewData": { "type": "object", "additionalProperties": false, "properties": { "balance": { "type": "string", "format": "decimal", "description": "The total current balance of the wallet" }, "unconfirmedBalance": { "type": "string", "format": "decimal", "description": "The current unconfirmed balance of the wallet" }, "confirmedBalance": { "type": "string", "format": "decimal", "description": "The current confirmed balance of the wallet" } } }, "OnChainWalletFeeRateData": { "type": "object", "additionalProperties": false, "properties": { "feerate": { "type": "number", "format": "decimal", "description": "The fee rate (sats per byte) based on the wallet's configured recommended block confirmation target" } } }, "OnChainWalletAddressData": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string", "description": "The bitcoin address" }, "keyPath": { "type": "string", "format": "keypath", "description": "the derivation path in relation to the HD account" }, "paymentLink": { "type": "string", "format": "BIP21", "description": "a bip21 payment link" } } }, "TransactionStatus": { "type": "string", "description": "", "x-enumNames": [ "Unconfirmed", "Confirmed" ], "enum": [ "Unconfirmed", "Confirmed" ] }, "LabelData": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The type of label" }, "text": { "type": "string", "description": "Information about this label" } } }, "OnChainWalletTransactionData": { "type": "object", "additionalProperties": false, "properties": { "transactionHash": { "type": "string", "nullable": true, "description": "The transaction id" }, "comment": { "type": "string", "description": "A comment linked to the transaction" }, "amount": { "type": "string", "format": "decimal", "description": "The amount the wallet balance changed with this transaction" }, "blockHash": { "type": "string", "nullable": true, "description": "The hash of the block that confirmed this transaction. Null if still unconfirmed." }, "blockHeight": { "type": "string", "nullable": true, "description": "The height of the block that confirmed this transaction. Null if still unconfirmed." }, "confirmations": { "type": "string", "nullable": true, "description": "The number of confirmations for this transaction" }, "timestamp": { "description": "The time of the transaction", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "status": { "$ref": "#/components/schemas/TransactionStatus", "description": "The status for this transaction" }, "labels": { "description": "Labels linked to this transaction", "type": "array", "items": { "$ref": "#/components/schemas/LabelData" } } } }, "OnChainWalletUTXOData": { "type": "object", "additionalProperties": false, "properties": { "comment": { "type": "string", "description": "A comment linked to this utxo" }, "amount": { "type": "string", "description": "the value of this utxo" }, "link": { "type": "string", "format": "url", "description": "a link to the configured blockchain explorer to view the utxo" }, "outpoint": { "type": "string", "format": "{txid}:{outputIndex}", "description": "outpoint of this utxo" }, "timestamp": { "description": "The time of the utxo", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "keyPath": { "type": "string", "format": "keypath", "description": "the derivation path in relation to the HD account" }, "address": { "type": "string", "description": "The wallet address of this utxo" }, "confirmations": { "type": "number", "description": "The number of confirmations of this utxo" }, "labels": { "description": "Labels linked to this transaction", "type": "array", "items": { "$ref": "#/components/schemas/LabelData" } } } }, "CreateOnChainTransactionRequestDestination": { "type": "object", "additionalProperties": false, "properties": { "destination": { "type": "string", "description": "A wallet address or a BIP21 payment link" }, "amount": { "type": "string", "format": "decimal", "nullable": true, "description": "The amount to send. If `destination` is a BIP21 link, the amount must be the same or null." }, "subtractFromAmount": { "type": "boolean", "description": "Whether to subtract the transaction fee from the provided amount. This makes the receiver receive less, or in other words: he or she pays the transaction fee. Also useful if you want to clear out your wallet. Must be false if `destination` is a BIP21 link" } } }, "CreateOnChainTransactionRequest": { "type": "object", "additionalProperties": false, "properties": { "destinations": { "nullable": false, "description": "What and where to send money", "type": "array", "items": { "$ref": "#/components/schemas/CreateOnChainTransactionRequestDestination" } }, "feerate": { "type": "number", "format": "decimal or long (sats/byte)", "description": "Transaction fee." }, "proceedWithPayjoin": { "type": "boolean", "default": true, "nullable": true, "description": "Whether to attempt to do a BIP78 payjoin if one of the destinations is a BIP21 with payjoin enabled" }, "proceedWithBroadcast": { "type": "boolean", "default": true, "nullable": true, "description": "Whether to broadcast the transaction after creating it or to simply return the transaction in hex format." }, "noChange": { "type": "boolean", "default": false, "nullable": true, "description": "Whether to send all the spent coins to the destinations (THIS CAN COST YOU SIGNIFICANT AMOUNTS OF MONEY, LEAVE FALSE UNLESS YOU KNOW WHAT YOU ARE DOING)." }, "rbf": { "type": "boolean", "nullable": true, "description": "Whether to enable RBF for the transaction. Leave blank to have it random (beneficial to privacy)" }, "excludeUnconfirmed": { "type": "boolean", "default": false, "nullable": true, "description": "Whether to exclude unconfirmed UTXOs from the transaction." }, "selectedInputs": { "nullable": true, "description": "Restrict the creation of the transactions from the outpoints provided ONLY (coin selection)", "type": "array", "items": { "type": "string" } } } }, "PatchOnChainTransactionRequest": { "type": "object", "additionalProperties": false, "properties": { "comment": { "nullable": true, "type": "string", "description": "Transaction comment" }, "labels": { "nullable": true, "description": "Transaction labels", "type": "array", "items": { "type": "string" } } } }, "StoreDataList": { "type": "array", "items": { "$ref": "#/components/schemas/StoreData" } }, "StoreData": { "allOf": [ { "$ref": "#/components/schemas/StoreBaseData" }, { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the store", "nullable": false } } } ] }, "StoreBaseData": { "type": "object", "x-abstract": true, "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The name of the store" }, "website": { "type": "string", "description": "The absolute url of the store", "format": "url" }, "defaultCurrency": { "type": "string", "description": "The default currency of the store", "default": "USD", "example": "USD" }, "invoiceExpiration": { "default": 900, "minimum": 60, "maximum": 2073600, "description": "The time after which an invoice is considered expired if not paid. The value will be rounded down to a minute.", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] }, "monitoringExpiration": { "default": 3600, "minimum": 600, "maximum": 2073600, "description": "The time after which an invoice which has been paid but not confirmed will be considered invalid. The value will be rounded down to a minute.", "allOf": [ { "$ref": "#/components/schemas/TimeSpanSeconds" } ] }, "speedPolicy": { "$ref": "#/components/schemas/SpeedPolicy" }, "lightningDescriptionTemplate": { "type": "string", "nullable": true, "description": "The BOLT11 description of the lightning invoice in the checkout. You can use placeholders '{StoreName}', '{ItemDescription}' and '{OrderId}'." }, "paymentTolerance": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "default": 0, "description": "Consider an invoice fully paid, even if the payment is missing 'x' % of the full amount." }, "anyoneCanCreateInvoice": { "type": "boolean", "default": false, "description": "If true, then no authentication is needed to create invoices on this store." }, "requiresRefundEmail": { "type": "boolean", "default": false, "description": "If true, the checkout page will ask to enter an email address before accessing payment information." }, "receipt": { "nullable": true, "$ref": "#/components/schemas/ReceiptOptions", "description": "Additional settings to customize the public receipt" }, "lightningAmountInSatoshi": { "type": "boolean", "default": false, "description": "If true, lightning payment methods show amount in satoshi in the checkout page." }, "lightningPrivateRouteHints": { "type": "boolean", "default": false, "description": "Should private route hints be included in the lightning payment of the checkout page." }, "onChainWithLnInvoiceFallback": { "type": "boolean", "default": false, "description": "Include lightning invoice fallback to on-chain BIP21 payment url." }, "redirectAutomatically": { "type": "boolean", "default": false, "description": "After successfull payment, should the checkout page redirect the user automatically to the redirect URL of the invoice?" }, "showRecommendedFee": { "type": "boolean", "default": true }, "recommendedFeeBlockTarget": { "type": "integer", "format": "int32", "default": 1, "description": "The fee rate recommendation in the checkout page for the on-chain payment to be confirmed after 'x' blocks." }, "defaultLang": { "type": "string", "default": "en", "description": "The default language to use in the checkout page. (The different translations available are listed [here](https://github.com/btcpayserver/btcpayserver/tree/master/BTCPayServer/wwwroot/locales)" }, "customLogo": { "type": "string", "nullable": true, "description": "URL to a logo to include in the checkout page." }, "customCSS": { "type": "string", "nullable": true, "description": "URL to a CSS stylesheet to include in the checkout page" }, "htmlTitle": { "type": "string", "nullable": true, "description": "The HTML title of the checkout page (when you over the tab in your browser)" }, "networkFeeMode": { "$ref": "#/components/schemas/NetworkFeeMode" }, "payJoinEnabled": { "type": "boolean", "default": false, "description": "If true, payjoin will be proposed in the checkout page if possible. ([More information](https://docs.btcpayserver.org/Payjoin/))" }, "lazyPaymentMethods": { "type": "boolean", "default": false, "description": "If true, payment methods are enabled individually upon user interaction in the invoice" }, "defaultPaymentMethod": { "type": "string", "example": "BTC", "description": "The default payment method to load when displaying an invoice. It can be in the format of `BTC_LightningNetwork` to specify Lightning to be the default or `BTC_OnChain`/ `BTC` for on-chain to be the default. " } } }, "NetworkFeeMode": { "type": "string", "description": "Check whether network fee should be added to the invoice if on-chain payment is used. ([More information](https://docs.btcpayserver.org/FAQ/Stores/#add-network-fee-to-invoice-vary-with-mining-fees))", "x-enumNames": [ "MultiplePaymentsOnly", "Always", "Never" ], "enum": [ "MultiplePaymentsOnly", "Always", "Never" ] }, "ApplicationUserData": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The id of the user", "nullable": false }, "email": { "type": "string", "description": "The email of the user", "nullable": false }, "emailConfirmed": { "type": "boolean", "description": "True if the email has been confirmed by the user" }, "requiresEmailConfirmation": { "type": "boolean", "description": "True if the email requires email confirmation to log in" }, "created": { "nullable": true, "description": "The creation date of the user as a unix timestamp. Null if created before v1.0.5.6", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "roles": { "type": "array", "nullable": false, "items": { "type": "string" }, "description": "The roles of the user" } } }, "LockUserRequest": { "type": "object", "additionalProperties": false, "properties": { "locked": { "type": "boolean", "description": "Whether to lock or unlock the user" } } }, "WebhookDeliveryList": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryData" } }, "WebhookDeliveryData": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the delivery", "nullable": false }, "timestamp": { "nullable": false, "description": "Timestamp of when the delivery got broadcasted", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "httpCode": { "type": "number", "description": "HTTP code received by the remote service, if any.", "nullable": true }, "errorMessage": { "type": "string", "description": "User friendly error message, if any." }, "status": { "type": "string", "description": "Whether the delivery failed or not (possible values are: `Failed`, `HttpError`, `HttpSuccess`)" } } }, "WebhookDataList": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookData" } }, "WebhookData": { "allOf": [ { "$ref": "#/components/schemas/WebhookDataBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the webhook", "nullable": false } } } ] }, "WebhookDataCreate": { "allOf": [ { "$ref": "#/components/schemas/WebhookData" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/).", "nullable": false } } } ] }, "WebhookDataUpdate": { "allOf": [ { "$ref": "#/components/schemas/WebhookDataBase" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/). If left out, null, or empty, the secret will not be changed.", "nullable": true } } } ] }, "WebhookDataBase": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The id of the webhook", "nullable": false }, "enabled": { "type": "boolean", "description": "Whether this webhook is enabled or not", "nullable": false, "default": true }, "automaticRedelivery": { "type": "boolean", "description": "If true, BTCPay Server will retry to redeliver any failed delivery after 10 seconds, 1 minutes and up to 6 times after 10 minutes.", "nullable": false, "default": true }, "url": { "type": "string", "description": "The endpoint where BTCPay Server will make the POST request with the webhook body", "nullable": false }, "authorizedEvents": { "type": "object", "description": "Which event should be received by this endpoint", "properties": { "everything": { "type": "boolean", "description": "If true, the endpoint will receive all events related to the store.", "nullable": false, "default": true }, "specificEvents": { "type": "array", "items": { "type": "string" }, "description": "If `everything` is false, the specific events that the endpoint is interested in. Current events are: `InvoiceCreated`, `InvoiceReceivedPayment`, `InvoiceProcessing`, `InvoiceExpired`, `InvoiceSettled`, `InvoiceInvalid`.", "nullable": false } } } } }, "WebhookEvent": { "type": "object", "additionalProperties": false, "properties": { "deliveryId": { "type": "string", "nullable": false, "description": "The delivery id of the webhook" }, "webhookId": { "type": "string", "nullable": false, "description": "The id of the webhook" }, "originalDeliveryId": { "type": "string", "nullable": false, "description": "If this delivery is a redelivery, the is the delivery id of the original delivery." }, "isRedelivery": { "type": "boolean", "nullable": false, "description": "True if this delivery is a redelivery" }, "type": { "type": "string", "nullable": false, "description": "The type of this event, current available are `InvoiceCreated`, `InvoiceReceivedPayment`, `InvoiceProcessing`, `InvoiceExpired`, `InvoiceSettled`, `InvoiceInvalid`, and `InvoicePaymentSettled`." }, "timestamp": { "description": "The timestamp when this delivery has been created", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] } } }, "WebhookInvoiceEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "storeId": { "type": "string", "description": "The store id of the invoice's event", "nullable": false }, "invoiceId": { "type": "string", "description": "The invoice id of the invoice's event", "nullable": false } } } ] }, "WebhookInvoiceSettledEvent": { "description": "Callback sent if the `type` is `InvoiceSettled`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "manuallyMarked": { "type": "boolean", "description": "Whether the invoice have been manually marked as confirmed", "nullable": false } } }, { "type": "object", "properties": { "overPaid": { "type": "boolean", "description": "Whether this invoice has received more money than expected", "nullable": false } } } ] }, "WebhookInvoiceInvalidEvent": { "description": "Callback sent if the `type` is `InvoiceInvalid`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "manuallyMarked": { "type": "boolean", "description": "Whether the invoice have been manually marked as confirmed. If false, this invoice has received payments which could not confirm in time.", "nullable": false } } } ] }, "WebhookInvoiceProcessingEvent": { "description": "Callback sent if the `type` is `InvoiceProcessing`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "overPaid": { "type": "boolean", "description": "Whether this invoice has received more money than expected", "nullable": false } } } ] }, "WebhookInvoiceReceivedPaymentEvent": { "description": "Callback sent if the `type` is `InvoiceReceivedPayment`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "afterExpiration": { "type": "boolean", "description": "Whether this payment has been sent after expiration of the invoice", "nullable": false }, "paymentMethod": { "type": "string", "description": "What payment method was used for this payment", "nullable": false }, "payment": { "description": "Details about the payment", "$ref": "#/components/schemas/Payment" } } } ] }, "WebhookInvoicePaymentSettledEvent": { "description": "Callback sent if the `type` is `InvoicePaymentSettled`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceReceivedPaymentEvent" } ] }, "WebhookInvoiceExpiredEvent": { "description": "Callback sent if the `type` is `InvoiceExpired`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "partiallyPaid": { "type": "boolean", "description": "Whether the invoice received some payments before being expired.", "nullable": false } } } ] } }, "securitySchemes": { "API_Key": { "type": "apiKey", "description": "BTCPay Server supports authenticating and authorizing users through an API Key that is generated by them. Send the API Key as a header value to Authorization with the format: `token {token}`. For a smoother experience, you can generate a url that redirects users to an API key creation screen.\n\n The following permissions are available to the context of the user creating the API Key:\n\n* `unrestricted`: Unrestricted access\n* `btcpay.user.candeleteuser`: Delete user\n* `btcpay.user.canviewprofile`: View your profile\n* `btcpay.user.canmodifyprofile`: Manage your profile\n* `btcpay.user.canmanagenotificationsforuser`: Manage your notifications\n* `btcpay.user.canviewnotificationsforuser`: View your notifications\n\nThe following permissions are available if the user is an administrator:\n\n* `btcpay.server.canviewusers`: View users\n* `btcpay.server.cancreateuser`: Create new users\n* `btcpay.server.canmodifyserversettings`: Manage your server\n* `btcpay.server.canuseinternallightningnode`: Use the internal lightning node\n* `btcpay.server.cancreatelightninginvoiceinternalnode`: Create invoices with internal lightning node\n\nThe following permissions applies to all stores of the user, you can limit to a specific store with the following format: `btcpay.store.cancreateinvoice:6HSHAEU4iYWtjxtyRs9KyPjM9GAQp8kw2T9VWbGG1FnZ`:\n\n* `btcpay.store.canmodifystoresettings`: Modify your stores\n* `btcpay.store.canviewcustodianaccounts`: View exchange accounts linked to your stores\n* `btcpay.store.canmanagecustodianaccounts`: Manage exchange accounts linked to your stores\n* `btcpay.store.candeposittocustodianaccount`: Deposit funds to exchange accounts linked to your stores\n* `btcpay.store.canwithdrawfromcustodianaccount`: Withdraw funds from exchange accounts to your store\n* `btcpay.store.cantradecustodianaccount`: Trade funds on your store's exchange accounts\n* `btcpay.store.webhooks.canmodifywebhooks`: Modify stores webhooks\n* `btcpay.store.canviewstoresettings`: View your stores\n* `btcpay.store.cancreateinvoice`: Create an invoice\n* `btcpay.store.canviewinvoices`: View invoices\n* `btcpay.store.canmodifyinvoices`: Modify invoices\n* `btcpay.store.canmodifypaymentrequests`: Modify your payment requests\n* `btcpay.store.canviewpaymentrequests`: View your payment requests\n* `btcpay.store.canmanagepullpayments`: Manage your pull payments\n* `btcpay.store.canuselightningnode`: Use the lightning nodes associated with your stores\n* `btcpay.store.cancreatelightninginvoice`: Create invoices from the lightning nodes associated with your stores\n\nNote that API Keys only limits permission of a user and can never expand it. If an API Key has the permission `btcpay.server.canmodifyserversettings` but that the user account creating this API Key is not administrator, the API Key will not be able to modify the server settings.\nSome permissions may include other permissions, see [this operation](#operation/permissionsMetadata).\n", "name": "Authorization", "in": "header" }, "Basic": { "type": "http", "description": "BTCPay Server supports authenticating and authorizing users through the Basic HTTP authentication scheme. Send the user and password encoded in base64 with the format `Basic {base64(username:password)}`. Using this authentication method implicitly provides you with the `unrestricted` permission", "scheme": "Basic" } } }, "tags": [ { "name": "Webhooks" } ], "openapi": "3.0.0", "info": { "title": "BTCPay Greenfield API", "version": "v1", "description": "A full API to use your BTCPay Server", "contact": { "name": "BTCPay Server", "url": "https://btcpayserver.org" }, "license": { "name": "MIT", "url": "https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE" } }, "servers": [ { "url": "https://btcpay.example.com/api/v1", "description": "BTCPay Server Greenfield API" } ], "security": [ { "API_Key": [], "Basic": [] } ], "x-webhooks": { "InvoiceCreated": { "post": { "operationId": "Webhook_InvoiceCreated", "summary": "InvoiceCreated", "description": "A new invoice has been created", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceEvent" } } } }, "responses": {} } }, "InvoiceExpired": { "post": { "operationId": "Webhook_InvoiceExpired", "summary": "InvoiceExpired", "description": "An invoice expired", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceExpiredEvent" } } } }, "responses": {} } }, "InvoiceReceivedPayment": { "post": { "operationId": "Webhook_InvoiceReceivedPayment", "summary": "InvoiceReceivedPayment", "description": "An invoice received a payment", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceReceivedPaymentEvent" } } } }, "responses": {} } }, "InvoicePaymentSettled": { "post": { "operationId": "Webhook_InvoicePaymentSettled", "summary": "InvoicePaymentSettled", "description": "An payment relating to an invoice has settled", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoicePaymentSettledEvent" } } } }, "responses": {} } }, "InvoiceProcessing": { "post": { "operationId": "Webhook_InvoiceProcessing", "summary": "InvoiceProcessing", "description": "Triggers when an invoice is fully paid, but doesn't have the required amount of confirmations on the blockchain yet according to your store's settings.", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceProcessingEvent" } } } }, "responses": {} } }, "InvoiceInvalid": { "post": { "operationId": "Webhook_InvoiceInvalid", "summary": "InvoiceInvalid", "description": "An invoice became invalid", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceInvalidEvent" } } } }, "responses": {} } }, "InvoiceSettled": { "post": { "operationId": "Webhook_InvoiceSettled", "summary": "InvoiceSettled", "description": "Triggers when an invoice is considered settled and the merchant can proceed with the order's delivery. The invoice now has enough confirmations on the blockchain (if paid on-chain) according to your store's configuration.", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceSettledEvent" } } } }, "responses": {} } } } }