{
"openapi": "3.0.0",
"info": {
"title": "BTCPay Greenfield API",
"version": "v1",
"description": "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n -H \"Content-Type: application/json\" \\\n --user \"$USER:$PASSWORD\" \\\n -X POST \\\n -d \"$BODY\" \\\n \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: token $API_KEY\" \\\n -X GET \\\n \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n",
"contact": {
"name": "BTCPay Server",
"url": "https://btcpayserver.org"
},
"license": {
"name": "MIT",
"url": "https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE"
}
},
"servers": [
{
"url": "https://{btcpay-host}",
"description": "Your BTCPay Server instance",
"variables": {
"btcpay-host": {
"default": "mainnet.demo.btcpayserver.org",
"description": "The hostname of your BTCPay Server instance"
}
}
}
],
"externalDocs": {
"description": "Check out our examples on how to use the API",
"url": "https://docs.btcpayserver.org/Development/GreenFieldExample/"
},
"components": {
"parameters": {
"StoreId": {
"name": "storeId",
"in": "path",
"required": true,
"description": "The store ID",
"schema": {
"$ref": "#/components/schemas/StoreId"
}
},
"InvoiceId": {
"name": "invoiceId",
"in": "path",
"required": true,
"description": "The invoice ID",
"schema": {
"$ref": "#/components/schemas/InvoiceId"
}
},
"UserIdOrEmail": {
"name": "idOrEmail",
"in": "path",
"required": true,
"description": "The user's id or email",
"schema": {
"type": "string"
}
},
"AppId": {
"name": "appId",
"in": "path",
"required": true,
"description": "App ID",
"schema": {
"type": "string"
}
},
"CryptoCode": {
"name": "cryptoCode",
"in": "path",
"required": true,
"description": "The cryptoCode of the lightning-node to query",
"schema": {
"type": "string"
},
"example": "BTC"
},
"PaymentMethodId": {
"name": "paymentMethodId",
"in": "path",
"required": true,
"description": "The payment method id of the payment method to update",
"schema": {
"$ref": "#/components/schemas/PaymentMethodId"
},
"example": "BTC-CHAIN"
},
"PayoutMethodId": {
"name": "payoutMethodId",
"in": "path",
"required": true,
"description": "The payout method id",
"schema": {
"$ref": "#/components/schemas/PayoutMethodId"
},
"example": "BTC-CHAIN"
},
"RateSource": {
"name": "rateSource",
"in": "path",
"required": true,
"description": "The rate source to configure (`primary` or `fallback`)",
"schema": {
"type": "string",
"default": "primary",
"example": "primary"
}
},
"PortalSessionId": {
"name": "portalSessionId",
"in": "path",
"required": true,
"example": "ps_665afQ23ExGouiY4EZ",
"description": "Identifier of the portal session.",
"schema": {
"$ref": "#/components/schemas/PortalSessionId"
}
},
"PlanCheckoutId": {
"name": "checkoutId",
"in": "path",
"required": true,
"example": "plancheckout_Hpm59L1NPCMUj477Q5",
"description": "Unique identifier of the plan checkout session.",
"schema": {
"$ref": "#/components/schemas/PlanCheckoutId"
}
},
"Subscriptions/Currency": {
"name": "currency",
"in": "path",
"required": true,
"description": "Currency code for the credit balance. Use `current` to retrieve the current balance in the currency of the current plan.",
"schema": {
"type": "string"
},
"example": "current"
},
"CustomerSelector": {
"name": "customerSelector",
"in": "path",
"required": true,
"description": "Flexible customer selector. Supports: a customer ID (e.g., `cust_GUGnpx3311fkaqGk7f`), an email (e.g., `subscriber@example.com`), or a key/value identity (e.g., `Email:subscriber@example.com`).",
"schema": {
"$ref": "#/components/schemas/CustomerSelector"
}
},
"PlanId": {
"name": "planId",
"in": "path",
"required": true,
"description": "Plan's ID",
"example": "plan_KZMVyuQp3v2vFWnEUM",
"schema": {
"$ref": "#/components/schemas/PlanId"
}
},
"OfferingId": {
"name": "offeringId",
"in": "path",
"required": true,
"description": "Offering's ID",
"example": "offering_DKWhZGB6PZsgTcPwpf",
"schema": {
"$ref": "#/components/schemas/OfferingId"
}
},
"WebhookId": {
"name": "webhookId",
"in": "path",
"required": true,
"description": "The webhook id",
"schema": {
"type": "string"
}
},
"DeliveryId": {
"name": "deliveryId",
"in": "path",
"required": true,
"description": "The id of the delivery",
"schema": {
"type": "string"
}
}
},
"schemas": {
"BaseUrl": {
"type": "string",
"description": "Base URL of the BTCPay Server instance.",
"example": "https://btcpay.example.com/"
},
"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": "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.\n`\"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"
},
"TimeSpanDays": {
"allOf": [
{
"$ref": "#/components/schemas/TimeSpan"
}
],
"format": "days",
"description": "A span of times in days"
},
"TimeSpanMinutes": {
"allOf": [
{
"$ref": "#/components/schemas/TimeSpan"
}
],
"format": "minutes",
"description": "A span of times in minutes"
},
"StoreId": {
"type": "string",
"description": "Store ID of the item",
"example": "9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776"
},
"InvoiceId": {
"type": "string",
"description": "The invoice ID",
"example": "HMprBnL9BTXWuPvpoKBS6e"
},
"PaymentMethodId": {
"type": "string",
"description": "Payment method IDs. Available payment method IDs for Bitcoin are: \n- `\"BTC-CHAIN\"`: Onchain \n-`\"BTC-LN\"`: Lightning \n- `\"BTC-LNURL\"`: LNURL",
"example": "BTC-CHAIN"
},
"PayoutMethodId": {
"type": "string",
"description": "Payout method IDs. Available payment method IDs for Bitcoin are: \n- `\"BTC-CHAIN\"`: Onchain \n-`\"BTC-LN\"`: Lightning",
"example": "BTC-LN"
},
"HistogramData": {
"type": "object",
"description": "Histogram data for wallet balances over time",
"properties": {
"type": {
"type": "string",
"description": "The timespan of the histogram data",
"x-enumNames": [
"Week",
"Month",
"Year"
],
"enum": [
"Week",
"Month",
"Year"
],
"default": "Week"
},
"balance": {
"type": "string",
"format": "decimal",
"description": "The current wallet balance"
},
"series": {
"type": "array",
"description": "An array of historic balances of the wallet",
"items": {
"type": "string",
"format": "decimal",
"description": "The balance of the wallet at a specific time"
}
},
"labels": {
"type": "array",
"description": "An array of timestamps associated with the series data",
"items": {
"type": "integer",
"description": "UNIX timestamp of the balance snapshot"
}
}
}
},
"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 (can be scoped to a specific store)",
"nullable": false,
"items": {
"type": "string"
},
"example": [
"btcpay.server.canmanageusers",
"btcpay.server.canmanageusers:2KxSpc9V5zDWfUbvgYiZuAfka4wUhGF96F75Ao8y4zHP"
]
}
}
},
"AppBaseData": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the app",
"example": "3ki4jsAkN4u9rv1PUzj1odX4Nx7s"
},
"appName": {
"type": "string",
"description": "Name given to the app when it was created",
"example": "my test app"
},
"storeId": {
"description": "Id of the store to which the app belongs",
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
]
},
"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"
},
"archived": {
"type": "boolean",
"description": "If true, the app does not appear in the apps list by default.",
"default": false,
"nullable": true
}
}
},
"PointOfSaleBaseData": {
"allOf": [
{
"$ref": "#/components/schemas/AppBaseData"
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Display title of the app",
"example": "My PoS app",
"nullable": true
},
"description": {
"type": "string",
"description": "App description",
"example": "This is my amazing PoS app",
"nullable": true
},
"defaultView": {
"type": "string",
"description": "App view type (e.g., static, cart, etc...)",
"example": "Cart",
"x-enumNames": [
"Static",
"Cart",
"Light",
"Print"
],
"enum": [
"Static",
"Cart",
"Light",
"Print"
],
"nullable": true
},
"showItems": {
"type": "boolean",
"default": false,
"description": "Display item selection for keypad",
"example": true,
"nullable": true
},
"showCustomAmount": {
"type": "boolean",
"description": "Whether the option to enter a custom amount is shown",
"example": true,
"nullable": true
},
"showDiscount": {
"default": false,
"type": "boolean",
"description": "Whether the option to enter a discount is shown",
"example": false,
"nullable": true
},
"showSearch": {
"type": "boolean",
"description": "Display the search bar",
"example": false,
"default": true,
"nullable": true
},
"showCategories": {
"type": "boolean",
"description": "Display the list of categories",
"example": false,
"default": true,
"nullable": true
},
"enableTips": {
"default": false,
"type": "boolean",
"description": "Whether the option to enter a tip is shown",
"example": true,
"nullable": true
},
"currency": {
"type": "string",
"description": "Currency used for the app",
"example": "BTC",
"nullable": true
},
"fixedAmountPayButtonText": {
"type": "string",
"description": "Payment button text template for items with a set price",
"example": "Buy for {0}",
"nullable": true
},
"customAmountPayButtonText": {
"type": "string",
"description": "Payment button text which appears for items which allow user to input a custom amount",
"example": "Pay",
"nullable": true
},
"tipText": {
"type": "string",
"description": "Prompt which appears next to the tip amount field if tipping is enabled",
"example": "Do you want to leave a tip?",
"nullable": true
},
"customTipPercentages": {
"type": "array",
"description": "Array of predefined tip percentage amounts",
"items": {
"type": "number"
},
"default": [
15,
18,
20
],
"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 user is redirected to once invoice is paid",
"nullable": true
},
"redirectAutomatically": {
"type": "boolean",
"description": "Whether user is redirected to specified redirect URL automatically after the invoice is paid",
"example": true,
"nullable": true
},
"htmlLang": {
"type": "string",
"description": "Used for SEO, the [HTML Lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) of the page",
"nullable": true,
"example": "en"
},
"htmlMetaTags": {
"type": "string",
"description": "Used for SEO, the [Meta tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) of the page",
"nullable": true,
"example": ""
},
"formId": {
"type": "string",
"description": "Form ID to request customer data",
"nullable": true
}
}
}
]
},
"PointOfSaleAppRequest": {
"allOf": [
{
"$ref": "#/components/schemas/PointOfSaleBaseData"
},
{
"type": "object",
"properties": {
"template": {
"type": "string",
"description": "JSON of item available in the app"
}
}
}
]
},
"PointOfSaleAppData": {
"allOf": [
{
"$ref": "#/components/schemas/PointOfSaleBaseData"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppItem"
},
"description": "JSON object of app items",
"example": [
{
"id": "green tea",
"title": "Green Tea",
"description": "Lovely, fresh and tender, Meng Ding Gan Lu ('sweet dew') is grown in the lush Meng Ding Mountains of the southwestern province of Sichuan where it has been cultivated for over a thousand years.",
"image": "~/img/pos-sample/green-tea.jpg",
"price": "1.0",
"priceType": "Fixed",
"buyButtonText": null,
"inventory": 5,
"paymentMethods": null,
"disabled": false
},
{
"id": "black tea",
"title": "Black Tea",
"description": "Tian Jian Tian Jian means 'heavenly tippy tea' in Chinese, and it describes the finest grade of dark tea. Our Tian Jian dark tea is from Hunan province which is famous for making some of the best dark teas available.",
"image": "~/img/pos-sample/black-tea.jpg",
"price": "2.0",
"priceType": "Fixed",
"buyButtonText": "Test Buy Button Text",
"inventory": null,
"paymentMethods": null,
"disabled": false
}
]
}
}
}
]
},
"CrowdfundBaseData": {
"allOf": [
{
"$ref": "#/components/schemas/AppBaseData"
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Display title of the app",
"example": "My crowdfund app",
"nullable": true
},
"description": {
"type": "string",
"description": "App description",
"example": "My crowdfund description",
"nullable": true
},
"enabled": {
"type": "boolean",
"description": "Whether the app is enabled to be viewed by everyone",
"example": true,
"nullable": true
},
"enforceTargetAmount": {
"type": "boolean",
"description": "Whether contributions over the set target amount are allowed",
"example": false,
"nullable": true
},
"startDate": {
"type": "number",
"description": "UNIX timestamp for crowdfund start time (https://www.unixtimestamp.com/)",
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
],
"example": 768658369,
"nullable": true
},
"endDate": {
"type": "number",
"description": "UNIX timestamp for crowdfund end time (https://www.unixtimestamp.com/)",
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
],
"example": 771336769,
"nullable": true
},
"targetCurrency": {
"type": "string",
"description": "Target currency for the crowdfund",
"example": "BTC",
"nullable": true
},
"targetAmount": {
"type": "number",
"description": "Target amount for the crowdfund",
"example": 420.69,
"nullable": true
},
"mainImageUrl": {
"type": "string",
"description": "URL for image used as a cover image for 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
},
"tagline": {
"type": "string",
"description": "Tagline for the app displayed to user",
"example": "I can't believe it's not butter",
"nullable": true
},
"disqusEnabled": {
"type": "boolean",
"description": "Whether Disqus is enabled for the app",
"nullable": true
},
"disqusShortname": {
"type": "string",
"description": "Disqus shortname to used for the app",
"nullable": true
},
"soundsEnabled": {
"type": "boolean",
"description": "Whether sounds on new contributions are enabled",
"example": false,
"nullable": true
},
"animationsEnabled": {
"type": "boolean",
"description": "Whether background animations on new contributions are enabled",
"example": true,
"nullable": true
},
"resetEveryAmount": {
"type": "number",
"description": "Contribution goal reset frequency amount",
"example": 1,
"nullable": true
},
"resetEvery": {
"type": "string",
"description": "Contribution goal reset frequency",
"example": "Day",
"nullable": true
},
"displayPerksValue": {
"type": "boolean",
"description": "Whether perk values are displayed",
"example": false,
"nullable": true
},
"displayPerksRanking": {
"type": "boolean",
"description": "Whether perk ranking is displayed",
"example": false,
"nullable": true
},
"sortPerksByPopularity": {
"type": "boolean",
"description": "Whether perks are sorted by popularity",
"default": true,
"nullable": true
},
"sounds": {
"type": "array",
"description": "Array of custom sounds which can be used on new contributions",
"items": {
"type": "string"
},
"example": [
"https://github.com/ClaudiuHKS/AdvancedQuakeSounds/raw/master/sound/AQS/doublekill.wav"
],
"nullable": true
},
"animationColors": {
"type": "array",
"description": "Array of custom HEX colors which can be used for background animations on new contributions",
"items": {
"type": "string"
},
"example": [
"#FF0000",
"#00FF00",
"#0000FF"
],
"nullable": true
},
"htmlLang": {
"type": "string",
"description": "Used for SEO, the [HTML Lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) of the page",
"nullable": true,
"example": "en"
},
"htmlMetaTags": {
"type": "string",
"description": "Used for SEO, the [Meta tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) of the page",
"nullable": true,
"example": ""
},
"formId": {
"type": "string",
"description": "Form ID to request customer data",
"nullable": true
}
}
}
]
},
"CrowdfundAppRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CrowdfundBaseData"
},
{
"type": "object",
"properties": {
"perksTemplate": {
"type": "string",
"description": "JSON of perks available in the app"
}
}
}
]
},
"CrowdfundAppData": {
"allOf": [
{
"$ref": "#/components/schemas/CrowdfundBaseData"
},
{
"type": "object",
"properties": {
"perks": {
"type": "object",
"description": "JSON of perks available in the app",
"example": [
{
"description": null,
"id": "test perk",
"image": null,
"price": {
"type": 2,
"formatted": "$100.00",
"value": 100.0
},
"title": "test perk",
"buyButtonText": null,
"inventory": null,
"paymentMethods": null,
"disabled": false
},
{
"description": "this is an amazing perk",
"id": "test test",
"image": "https://mainnet.demo.btcpayserver.org/img/errorpages/404_nicolas.jpg",
"price": {
"type": 1,
"formatted": "$69.42",
"value": 69.42
},
"title": "test test",
"buyButtonText": null,
"inventory": 5,
"paymentMethods": null,
"disabled": false
},
{
"description": null,
"id": "f$t45hj764325",
"image": null,
"price": {
"type": 0,
"formatted": null,
"value": null
},
"title": "amazing perk",
"buyButtonText": "button text",
"inventory": null,
"paymentMethods": null,
"disabled": true
}
]
}
}
}
]
},
"AppItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "green-tea",
"description": "Unique ID of the item"
},
"title": {
"type": "string",
"example": "Green Tea",
"description": "The display name of the item"
},
"description": {
"type": "string",
"example": "Lovely, fresh and tender.",
"description": "A description text for the item"
},
"image": {
"type": "string",
"example": "http://teashop.com/img/green-tea.jpg",
"description": "An image URL for the item"
},
"price": {
"type": "string",
"format": "decimal",
"nullable": true,
"example": "21.0"
},
"priceType": {
"type": "string",
"x-enumNames": [
"Fixed",
"Topup",
"Minimum"
],
"enum": [
"Fixed",
"Topup",
"Minimum"
]
},
"buyButtonText": {
"type": "string",
"example": "Buy me!",
"description": "A custom text for the buy button for the item"
},
"inventory": {
"type": "integer",
"nullable": true,
"example": 21,
"description": "The remaining stock the item"
},
"disabled": {
"type": "boolean",
"description": "If true, the item does not appear in the list by default.",
"default": false
}
}
},
"AppSalesStats": {
"type": "object",
"properties": {
"salesCount": {
"type": "integer",
"example": 615,
"description": "Total sales in that period"
},
"series": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppSalesStatsItem"
}
}
}
},
"AppSalesStatsItem": {
"type": "object",
"properties": {
"date": {
"type": "integer",
"description": "UNIX timestamp of the beginning of that day"
},
"label": {
"type": "string",
"description": "Short date as label",
"example": "Jul 21"
},
"salesCount": {
"type": "integer",
"example": 21,
"description": "Total sales on that day"
}
}
},
"AppItemStats": {
"type": "object",
"properties": {
"itemCode": {
"type": "string",
"description": "Item ID"
},
"title": {
"type": "string",
"description": "Item Name"
},
"salesCount": {
"type": "integer",
"example": 21,
"description": "Total sales of that item"
},
"total": {
"type": "string",
"format": "decimal",
"description": "The total amount of sales of that item"
},
"totalFormatted": {
"type": "string",
"description": "The formatted total amount of sales of that item",
"example": "615.21 USD"
}
}
},
"FileData": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "The id of the file",
"nullable": false
},
"userId": {
"type": "string",
"description": "The id of the user that uploaded the file",
"nullable": false
},
"uri": {
"type": "string",
"description": "The internal URI of the file",
"nullable": false
},
"url": {
"type": "string",
"description": "The full URL of the file",
"nullable": true
},
"originalName": {
"type": "string",
"description": "The original name of the file",
"nullable": true
},
"storageName": {
"type": "string",
"description": "The storage name of the file",
"nullable": true
},
"created": {
"type": "number",
"nullable": true,
"description": "The creation date of the file as a unix timestamp",
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
]
}
}
},
"ApplicationHealthData": {
"type": "object",
"additionalProperties": false,
"properties": {
"synchronized": {
"type": "boolean",
"description": "True if the instance is fully synchronized, according to NBXplorer"
}
}
},
"InvoiceDataList": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"paymentMethods": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicePaymentMethodDataModel"
}
}
}
},
{
"$ref": "#/components/schemas/InvoiceData"
}
]
}
},
"MarkInvoiceStatusRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"nullable": false,
"description": "Mark an invoice as completed or invalid.",
"allOf": [
{
"$ref": "#/components/schemas/InvoiceStatusMark"
}
]
}
}
},
"InvoiceStatusMark": {
"type": "string",
"description": "",
"x-enumNames": [
"Invalid",
"Settled"
],
"enum": [
"Invalid",
"Settled"
]
},
"InvoiceStatus": {
"type": "string",
"description": "The status of the invoice",
"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": {
"type": "object",
"nullable": true,
"description": "Additional settings to customize the checkout flow",
"allOf": [
{
"$ref": "#/components/schemas/CheckoutOptions"
}
]
},
"receipt": {
"type": "object",
"nullable": true,
"description": "Additional settings to customize the public receipt",
"allOf": [
{
"$ref": "#/components/schemas/ReceiptOptions"
}
]
}
}
},
"InvoiceData": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceDataBase"
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"$ref": "#/components/schemas/InvoiceId"
},
"storeId": {
"description": "The store identifier that the invoice belongs to",
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
]
},
"amount": {
"type": "string",
"format": "decimal",
"description": "The amount of the invoice. Note that the amount will be zero for a top-up invoice that is paid after invoice expiry.",
"example": "5.00"
},
"paidAmount": {
"type": "string",
"format": "decimal",
"description": "The actual amount paid by the customer/buyer.",
"example": "5.00"
},
"currency": {
"type": "string",
"description": "The currency of the invoice",
"example": "USD"
},
"type": {
"$ref": "#/components/schemas/InvoiceType"
},
"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"
}
]
},
"monitoringExpiration": {
"description": "Expiration time for monitoring of the invoice for any changes",
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
]
},
"status": {
"$ref": "#/components/schemas/InvoiceStatus"
},
"additionalStatus": {
"$ref": "#/components/schemas/InvoiceAdditionalStatus"
},
"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"
}
}
}
]
},
"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. See [our documentation](https://docs.btcpayserver.org/Development/InvoiceMetadata/) for more information.",
"example": {
"orderId": "pos-app_346KRC5BjXXXo8cRFKwTBmdR6ZJ4",
"orderUrl": "https://localhost:14142/apps/346KRC5BjXXXo8cRFKwTBmdR6ZJ4/pos",
"itemDesc": "Tea shop",
"posData": {
"tip": 0.48,
"cart": [
{
"id": "pu erh",
"count": 1,
"image": "~/img/pos-sample/pu-erh.jpg",
"price": {
"type": 2,
"value": 2,
"formatted": "$2.00"
},
"title": "Pu Erh",
"inventory": null
},
{
"id": "rooibos",
"count": 1,
"image": "~/img/pos-sample/rooibos.jpg",
"price": {
"type": 2,
"value": 1.2,
"formatted": "$1.20"
},
"title": "Rooibos",
"inventory": null
}
],
"total": 3.68,
"subTotal": 3.2,
"customAmount": 0,
"discountAmount": 0,
"discountPercentage": 0
},
"receiptData": {
"Tip": "$0.48",
"Cart": {
"Pu Erh": "$2.00 x 1 = $2.00",
"Rooibos": "$1.20 x 1 = $1.20"
}
}
},
"anyOf": [
{
"title": "Order information",
"properties": {
"orderId": {
"type": "string",
"nullable": true,
"description": "Refers to the order ID from an external system, such as an e-commerce platform like WooCommerce. This property is indexed, allowing for efficient invoice searches using the `orderId`."
},
"orderUrl": {
"type": "string",
"nullable": true,
"description": "Refers to a URL linking back to the order page of the external system. This link is displayed in the invoice details view."
},
"taxIncluded": {
"type": "number",
"nullable": true,
"description": "Represents the tax amount in the invoice currency. This information will appear in the invoice details view. During invoice creation, the value is automatically rounded to significant digits and ensured not to be greater than the invoice's price."
},
"physical": {
"type": "string",
"nullable": true,
"description": "Indicates if this is a physical good; displayed in the invoice details view and in the BitPay API-compatible endpoints."
}
}
},
{
"title": "Point of Sale (Cart view)",
"properties": {
"posData": {
"type": "object",
"description": "A custom JSON object that represents information displayed in the invoice details view."
}
}
},
{
"title": "Product information",
"properties": {
"itemDesc": {
"type": "string",
"nullable": true,
"description": "When using the Point of Sale (except in keypad or cart view), this field is set to the item description of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view."
},
"itemCode": {
"type": "string",
"nullable": true,
"description": "When using the Point of Sale (except in keypad or cart view), this field is set to the item code of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view."
}
}
},
{
"title": "Payment request information",
"properties": {
"paymentRequestId": {
"type": "string",
"nullable": true,
"description": "In the invoice details view, a link is provided for navigating to the payment request page associated with the invoice."
}
}
},
{
"title": "Buyer informations",
"properties": {
"buyerName": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerEmail": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerCountry": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerZip": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerState": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerCity": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerAddress1": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerAddress2": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
},
"buyerPhone": {
"type": "string",
"description": "Visible in the invoice details view and in the BitPay API-compatible endpoints.",
"nullable": true
}
}
},
{
"title": "Receipt information",
"properties": {
"receiptData": {
"type": "object",
"description": "A custom JSON object that represents information displayed on the receipt page of an invoice.",
"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"
}
}
},
"InvoiceRefundTriggerData": {
"type": "object",
"additionalProperties": false,
"properties": {
"paymentAmountThen": {
"type": "string",
"format": "decimal",
"description": "The amount in crypto at the time the invoice was paid.",
"example": "5.00"
},
"paymentAmountNow": {
"type": "string",
"format": "decimal",
"description": "The current amount in crypto.",
"example": "5.00"
},
"invoiceAmount": {
"type": "string",
"format": "decimal",
"description": "The fiat amount at the rate when the refund will be sent.",
"example": "5.00"
},
"paymentCurrency": {
"type": "string",
"description": "The crypto currency of the invoice",
"example": "BTC"
},
"paymentCurrencyDivisibility": {
"type": "number",
"description": "The maximum divisibility supported by the crypto currency of the invoice"
},
"invoiceCurrencyDivisibility": {
"type": "number",
"description": "The maximum divisibility supported by the fiat currency of the invoice"
},
"invoiceCurrency": {
"type": "string",
"description": "The fiat currency of the invoice",
"example": "USD"
},
"overpaidPaymentAmount": {
"type": "string",
"format": "decimal",
"nullable": true,
"description": "The amount by which the invoice is overpaid",
"example": "2.00"
}
}
},
"CheckoutOptions": {
"type": "object",
"additionalProperties": false,
"properties": {
"speedPolicy": {
"type": "string",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/SpeedPolicy"
}
]
},
"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": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodId"
}
],
"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."
},
"lazyPaymentMethods": {
"type": "boolean",
"nullable": true,
"description": "If true, payment methods are enabled individually upon user interaction in the invoice. Default to store's settings'"
},
"expirationMinutes": {
"type": "number",
"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.0,
"maximum": 100.0,
"default": 0.0,
"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 0)"
},
"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)"
},
"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": {
"paymentMethodId": {
"$ref": "#/components/schemas/PaymentMethodId"
},
"currency": {
"type": "string",
"description": "The currency 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",
"example": "64392.23",
"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"
},
"paymentMethodFee": {
"type": "string",
"format": "decimal",
"description": "The added merchant fee to pay for additional costs incurred by 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",
"title": "*-LNURL",
"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",
"title": "*-CHAIN",
"description": "Bitcoin On-Chain payment information",
"properties": {
"keyPath": {
"type": "string",
"description": "The key path relative to the account derviation key.",
"example": "0/1"
},
"payjoinEnabled": {
"type": "boolean",
"description": "If the payjoin feature is enabled for this payment method."
},
"accountDerivation": {
"type": "string",
"description": "The derivation scheme used to derive addresses (null if `includeSensitive` is `false`)",
"example": "xpub6DVMcQAQCtGbNDTEjQGtR1GRoTKw7AzP6bVivX4gFnewcnRk1r1tbczpfsaYjKKVrmtyiwYqAEnALYzZ8yoTArVsKfZekmwLFqQp4MRgPhy"
},
"recommendedFeeRate": {
"type": "string",
"format": "decimal",
"description": "The recommended fee rate for this payment method.",
"example": "4.107"
},
"paymentMethodFeeRate": {
"type": "string",
"format": "decimal",
"description": "The fee rate charged to the user as `PaymentMethodFee`.",
"example": "3.975"
}
}
},
{
"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"
},
"destination": {
"type": "string",
"description": "The destination the payment was made to"
}
}
},
"PaymentStatus": {
"type": "string",
"description": "The status of the payment",
"x-enumNames": [
"Invalid",
"Processing",
"Settled"
],
"enum": [
"Invalid",
"Processing",
"Settled"
]
},
"InvoiceType": {
"type": "string",
"description": "The type of the invoice",
"x-enumNames": [
"Standard",
"TopUp"
],
"enum": [
"Standard",
"TopUp"
]
},
"RefundInvoiceRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"refundVariant"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the pull payment (Default: 'Refund' followed by the invoice id)",
"nullable": true
},
"description": {
"type": "string",
"description": "Description of the pull payment"
},
"payoutMethodId": {
"$ref": "#/components/schemas/PayoutMethodId"
},
"refundVariant": {
"type": "string",
"description": "* `RateThen`: Refund the crypto currency price, at the rate the invoice got paid.\r\n* `CurrentRate`: Refund the crypto currency price, at the current rate.\r\n*`Fiat`: Refund the invoice currency, at the rate when the refund will be sent.\r\n*`OverpaidAmount`: Refund the crypto currency amount that was overpaid.\r\n*`Custom`: Specify the amount, currency, and rate of the refund. (see `customAmount` and `customCurrency`)",
"x-enumNames": [
"RateThen",
"CurrentRate",
"OverpaidAmount",
"Fiat",
"Custom"
],
"enum": [
"RateThen",
"CurrentRate",
"OverpaidAmount",
"Fiat",
"Custom"
]
},
"subtractPercentage": {
"type": "string",
"format": "decimal",
"description": "Optional percentage by which to reduce the refund, e.g. as processing charge or to compensate for the mining fee.",
"example": "2.1"
},
"customAmount": {
"type": "string",
"format": "decimal",
"description": "The amount to refund if the `refundVariant` is `Custom`.",
"example": "5.00"
},
"customCurrency": {
"type": "string",
"description": "The currency to refund if the `refundVariant` is `Custom`",
"example": "USD"
}
}
},
"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 millisatoshi string. (1000 millisatoshi = 1 satoshi)",
"nullable": false
},
"description": {
"type": "string",
"nullable": true,
"description": "Description of the invoice in the BOLT11"
},
"descriptionHashOnly": {
"type": "boolean",
"nullable": true,
"default": false,
"description": "If `descriptionHashOnly` is `true` (default is `false`), then the BOLT11 returned contains a hash of the `description`, rather than the `description`, itself. This allows for much longer descriptions, but they must be communicated via some other mechanism."
},
"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": {
"type": "number",
"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": {
"type": "number",
"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"
},
"paymentHash": {
"type": "string",
"description": "The payment hash"
},
"preimage": {
"type": "string",
"nullable": true,
"description": "The payment preimage (available when status is complete)"
},
"customRecords": {
"type": "object",
"nullable": true,
"description": "The custom TLV records attached to a keysend payment"
}
}
},
"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"
},
"alias": {
"type": "string",
"nullable": true,
"description": "The alias of the lightning node"
},
"color": {
"type": "string",
"nullable": true,
"description": "The color attribute of the lightning node"
},
"version": {
"type": "string",
"nullable": true,
"description": "The version name of the lightning node"
},
"peersCount": {
"type": "integer",
"nullable": true,
"description": "The number of peers"
},
"activeChannelsCount": {
"type": "integer",
"nullable": true,
"description": "The number of active channels"
},
"inactiveChannelsCount": {
"type": "integer",
"nullable": true,
"description": "The number of inactive channels"
},
"pendingChannelsCount": {
"type": "integer",
"nullable": true,
"description": "The number of pending channels"
}
}
},
"LightningNodeBalanceData": {
"type": "object",
"properties": {
"onchain": {
"type": "object",
"description": "On-chain balance of the Lightning node",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/OnchainBalanceData"
}
]
},
"offchain": {
"type": "object",
"description": "Off-chain balance of the Lightning node",
"nullable": true,
"allOf": [
{
"$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"
},
"sendTimeout": {
"type": "number",
"nullable": true,
"example": 30,
"default": 30,
"description": "The number of seconds after which the payment times out",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanSeconds"
}
]
}
}
},
"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 id of the notification"
},
"identifier": {
"type": "string",
"description": "The identifier of the notification"
},
"type": {
"type": "string",
"description": "The type of the notification"
},
"body": {
"type": "string",
"format": "html",
"description": "The html body of the notifications"
},
"storeId": {
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
],
"type": "string",
"nullable": true,
"description": "If related to a store, the store id of the notification"
},
"link": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "The link of the notification"
},
"createdTime": {
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
],
"description": "The creation time of the notification"
},
"seen": {
"type": "boolean",
"description": "If the notification has been seen by the user"
}
}
},
"UpdateNotificationSettingsRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"disabled": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of the notification type identifiers, which should be disabled. Can also be a single item 'all'.",
"example": [
"newversion",
"pluginupdate"
],
"nullable": false
}
}
},
"NotificationSettingsData": {
"type": "object",
"additionalProperties": false,
"properties": {
"notifications": {
"type": "array",
"description": "The notification types",
"items": {
"$ref": "#/components/schemas/NotificationSettingsItemData"
}
}
},
"example": [
{
"identifier": "newversion",
"name": "New version",
"enabled": false
},
{
"identifier": "newuserrequiresapproval",
"name": "New user requires approval",
"enabled": true
},
{
"identifier": "inviteaccepted",
"name": "User accepted invitation",
"enabled": true
},
{
"identifier": "pluginupdate",
"name": "Plugin update",
"enabled": false
},
{
"identifier": "invoicestate",
"name": "All invoice updates",
"enabled": true
},
{
"identifier": "invoicestate_invoice_paidAfterExpiration",
"name": "Invoice was paid after expiration",
"enabled": true
},
{
"identifier": "invoicestate_invoice_expiredPaidPartial",
"name": "Invoice expired with partial payments",
"enabled": true
},
{
"identifier": "invoicestate_invoice_failedToConfirm",
"name": "Invoice has payments that failed to confirm on time",
"enabled": true
},
{
"identifier": "invoicestate_invoice_confirmed",
"name": "Invoice is settled",
"enabled": true
},
{
"identifier": "payout",
"name": "Payouts",
"enabled": true
},
{
"identifier": "external-payout-transaction",
"name": "External payout approval",
"enabled": true
}
]
},
"NotificationSettingsItemData": {
"type": "object",
"additionalProperties": false,
"properties": {
"identifier": {
"type": "string",
"description": "The identifier of the notification type",
"nullable": false
},
"name": {
"type": "string",
"description": "The description of the notification type",
"nullable": false
},
"enabled": {
"type": "boolean",
"description": "If the notification type is enabled",
"nullable": false
}
},
"example": {
"identifier": "newversion",
"name": "New version",
"enabled": false
}
},
"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",
"nullable": false,
"description": "The store identifier that the payment request belongs to",
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
]
},
"status": {
"type": "string",
"enum": [
"Pending",
"Completed",
"Processing",
"Expired"
],
"description": "Represents the status of a payment request:\n* `Pending`: Not enough has been paid or settled.\n* `Completed`: Paid and fully settled.\n* `Expired`: Expired before full settlement.\n* `Processing`: Paid enough, awaiting full settlement.",
"nullable": false
},
"createdTime": {
"type": "number",
"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": {
"type": "number",
"description": "The expiry date of the payment request",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
]
},
"referenceId": {
"type": "string",
"description": "An optional user-defined identifier for this payment request.",
"nullable": true,
"example": "INV-123493"
},
"allowCustomPaymentAmounts": {
"type": "boolean",
"description": "Whether to allow users to create invoices that partially pay the payment request ",
"nullable": true
},
"formId": {
"type": "string",
"description": "Form ID to request customer data",
"nullable": true
},
"formResponse": {
"type": "object",
"description": "Form data response",
"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"
},
"payoutMethods": {
"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"
}
]
},
"cancelPayoutAfterFailures": {
"description": "How many failures should the processor tolerate before cancelling the payout",
"type": "number",
"nullable": true
},
"processNewPayoutsInstantly": {
"description": "Skip the interval when ane eligible payout has been approved (or created with pre-approval)",
"type": "boolean",
"default": false
}
}
},
"LightningAutomatedTransferSettings": {
"type": "object",
"additionalProperties": false,
"properties": {
"payoutMethodId": {
"$ref": "#/components/schemas/PayoutMethodId"
},
"intervalSeconds": {
"description": "How often should the processor run",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanSeconds"
}
]
},
"cancelPayoutAfterFailures": {
"description": "How many failures should the processor tolerate before cancelling the payout",
"type": "number",
"nullable": true
},
"processNewPayoutsInstantly": {
"description": "Skip the interval when ane eligible payout has been approved (or created with pre-approval)",
"type": "boolean",
"default": false
}
}
},
"UpdateOnChainAutomatedTransferSettings": {
"type": "object",
"additionalProperties": false,
"properties": {
"feeTargetBlock": {
"type": "number",
"description": "How many blocks should the fee rate calculation target to confirm in. Set to 1 if not provided",
"nullable": true
},
"intervalSeconds": {
"description": "How often should the processor run",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanSeconds"
}
]
},
"threshold": {
"type": "string",
"format": "decimal",
"minimum": 0,
"description": "Only process payouts when this payout sum is reached.",
"example": "0.1"
},
"processNewPayoutsInstantly": {
"description": "Skip the interval when ane eligible payout has been approved (or created with pre-approval)",
"type": "boolean",
"default": false
}
}
},
"OnChainAutomatedTransferSettings": {
"type": "object",
"additionalProperties": false,
"properties": {
"payoutMethodId": {
"$ref": "#/components/schemas/PayoutMethodId"
},
"feeTargetBlock": {
"type": "number",
"description": "How many blocks should the fee rate calculation target to confirm in."
},
"intervalSeconds": {
"description": "How often should the processor run",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanSeconds"
}
]
},
"threshold": {
"type": "string",
"format": "decimal",
"minimum": 0,
"description": "Only process payouts when this payout sum is reached.",
"example": "0.1"
},
"processNewPayoutsInstantly": {
"description": "Skip the interval when ane eligible payout has been approved (or created with pre-approval)",
"type": "boolean",
"default": false
}
}
},
"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)."
},
"payoutMethodId": {
"$ref": "#/components/schemas/PayoutMethodId"
}
}
},
"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"
},
"metadata": {
"type": "object",
"description": "Additional metadata to store with the payout"
}
}
}
]
},
"PayoutPaymentProof": {
"type": "object",
"additionalProperties": true,
"description": "Additional information around how the payout is being or has been paid out. The mentioned properties are all optional (except `proofType`) and you can introduce any json format you wish.",
"properties": {
"proofType": {
"type": "string",
"description": "The type of payment proof it is."
}
},
"anyOf": [
{
"properties": {
"link": {
"type": "string",
"format": "url",
"nullable": true,
"description": "A link to the proof of payout payment."
}
}
},
{
"properties": {
"id": {
"type": "string",
"nullable": true,
"description": "A unique identifier to the proof of payout payment."
}
}
}
]
},
"PayoutState": {
"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"
]
},
"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)"
},
"originalCurrency": {
"type": "string",
"example": "USD",
"description": "The currency before being converted into the payout's currency"
},
"originalAmount": {
"type": "string",
"format": "decimal",
"nullable": false,
"example": "10399.18",
"description": "The amount in originalCurrency before being converted into the payout's currency"
},
"payoutCurrency": {
"type": "string",
"example": "BTC",
"description": "The currency of the payout after conversion."
},
"payoutAmount": {
"type": "string",
"format": "decimal",
"nullable": true,
"example": "1.12300000",
"description": "The amount in payoutCurrency after conversion. (This property is set after the payout has been Approved)"
},
"payoutMethodId": {
"$ref": "#/components/schemas/PayoutMethodId"
},
"state": {
"$ref": "#/components/schemas/PayoutState"
},
"paymentProof": {
"$ref": "#/components/schemas/PayoutPaymentProof"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Additional information around the payout that can be supplied. The mentioned properties are all optional and you can introduce any json format you wish.",
"example": {
"source": "Payout created through the API"
},
"anyOf": [
{
"title": "General information",
"properties": {
"source": {
"type": "string",
"nullable": true,
"description": "The source of the payout creation. Shown on the payout list page."
},
"sourceLink": {
"type": "string",
"format": "url",
"nullable": true,
"description": "A link to the source of the payout creation. Shown on the payout list page."
}
}
}
]
}
}
},
"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"
},
"BOLT11Expiration": {
"type": "string",
"example": 30,
"description": "If lightning is activated, do not accept BOLT11 invoices with expiration less than \u2026 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"
}
}
},
"LNURLData": {
"type": "object",
"properties": {
"lnurlBech32": {
"type": "string",
"description": "Bech32 representation of LNURL",
"example": "lightning:lnurl1dp68gup69uhnzv3h9cczuvpwxyarzdp3xsez7sj5gvh42j2vfe24ynp0wa5hg6rywfshwtmswqhngvntdd6x6uzvx4jrvu2kvvur23n8v46rwjpexcc45563fn53w7"
},
"lnurlUri": {
"type": "string",
"description": "URI representation of LNURL",
"example": "lnurlw://example.com/BTC/UILNURL/withdraw/pp/42kktmpL5d6qVc85Fget7H961ZSQ"
}
}
},
"UpdateServerEmailSettings": {
"allOf": [
{
"$ref": "#/components/schemas/UpdateEmailSettings"
},
{
"type": "object",
"properties": {
"enableStoresToUseServerEmailSettings": {
"type": "boolean",
"description": "Indicates if stores can use server email settings"
}
}
}
]
},
"GetServerEmailSettings": {
"allOf": [
{
"$ref": "#/components/schemas/GetEmailSettings"
},
{
"type": "object",
"properties": {
"enableStoresToUseServerEmailSettings": {
"type": "boolean",
"description": "Indicates if stores can use server email settings"
}
}
}
]
},
"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.0,
"maximum": 1.0,
"description": "The current synchronization progress"
}
}
},
"ApplicationServerInfoSyncStatusData": {
"type": "object",
"description": "Detailed sync status",
"properties": {
"paymentMethodId": {
"$ref": "#/components/schemas/PaymentMethodId"
},
"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
}
}
},
"UpdateEmailSettings": {
"allOf": [
{
"$ref": "#/components/schemas/EmailSettingsBase"
},
{
"type": "object",
"properties": {
"password": {
"type": "string",
"description": "SMTP password. Keep null or empty to not update it.",
"nullable": true,
"example": "MyS3cr3t"
}
}
}
]
},
"GetEmailSettings": {
"allOf": [
{
"$ref": "#/components/schemas/EmailSettingsBase"
},
{
"type": "object",
"properties": {
"passwordSet": {
"type": "boolean",
"description": "`true` if the password has been set."
}
}
}
]
},
"EmailSettingsBase": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "The sender email address",
"example": "sender@gmail.com"
},
"server": {
"type": "string",
"description": "SMTP server host",
"example": "smtp.gmail.com"
},
"port": {
"type": "integer",
"description": "SMTP server port",
"example": 587
},
"login": {
"type": "string",
"description": "SMTP username",
"example": "John.Smith"
},
"disableCertificateCheck": {
"type": "boolean",
"description": "Disable TLS certificate security checks",
"example": false
}
}
},
"LightningAddressData": {
"type": "object",
"additionalProperties": false,
"properties": {
"username": {
"type": "string",
"description": "The username of the lightning address"
},
"currencyCode": {
"type": "string",
"nullable": true,
"description": "The currency to generate the invoices for this lightning address in. Leave null lto use the store default."
},
"min": {
"type": "string",
"nullable": true,
"description": "The minimum amount in sats this ln address allows"
},
"max": {
"type": "string",
"nullable": true,
"description": "The maximum amount in sats this ln address allows"
},
"invoiceMetadata": {
"type": "object",
"nullable": true,
"description": "The invoice metadata as JSON."
}
}
},
"UpdatePaymentMethodConfig": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether the payment method is enabled, leave null or unspecified to not change current setting",
"default": null,
"nullable": true,
"example": true
},
"config": {
"type": "object",
"description": "The new payment method config, leave null or unspecified to not change current setting",
"default": null,
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/OnChainPaymentMethodBaseData"
},
{
"$ref": "#/components/schemas/LightningNetworkPaymentMethodBaseData"
},
{
"$ref": "#/components/schemas/LNURLPayPaymentMethodBaseData"
},
{
"type": "string",
"title": "Lightning connection string",
"description": "A lightning connection string or `Internal Node` (See [this documentation](https://github.com/btcpayserver/btcpayserver.lightning) for the format)"
},
{
"type": "string",
"title": "Derivation scheme",
"description": "A derivation scheme in NBXplorer's format (See [this documentation](https://github.com/dgarage/NBXplorer/blob/master/docs/API.md#derivation-scheme) for the format)"
},
{
"type": "string",
"title": "Output descriptor",
"description": "An output descriptor. Only a subset of them are supported. (See [this documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) for the format)"
},
{
"description": "Any other unofficial payment method data",
"type": "object",
"additionalProperties": true
}
]
}
}
},
"GenericPaymentMethodData": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether the payment method is enabled"
},
"paymentMethodId": {
"$ref": "#/components/schemas/PaymentMethodId"
},
"config": {
"type": "object",
"additionalProperties": false,
"description": "Associated dynamic data based on payment method type.",
"oneOf": [
{
"$ref": "#/components/schemas/OnChainPaymentMethodBaseData"
},
{
"$ref": "#/components/schemas/LightningNetworkPaymentMethodBaseData"
},
{
"$ref": "#/components/schemas/LNURLPayPaymentMethodBaseData"
},
{
"description": "Any other unofficial payment method data",
"type": "object",
"additionalProperties": true
}
]
}
}
},
"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=..."
}
}
},
"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. "
},
"lud12Enabled": {
"type": "boolean",
"description": "Allow comments to be passed on via lnurl."
},
"lud21Enabled": {
"type": "boolean",
"description": "Whether to include a [LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) verify URL in LNURL-pay callback responses, enabling external services to verify payment settlement without authentication."
}
}
},
"StoreRateConfiguration": {
"type": "object",
"additionalProperties": false,
"properties": {
"spread": {
"type": "string",
"description": "A spread applies to the rate fetched in `%`. Must be `>= 0` or `<= 100`"
},
"preferredSource": {
"type": "string",
"description": "When `isCustomScript` is `false`, uses this source in the default `effectiveScript`. When `isCustomScript` is `true`, this field is ignored (set to `null`). See `/misc/rate-sources` for available sources."
},
"isCustomScript": {
"type": "boolean",
"description": "Whether to use `preferredSource` with default script or a custom `effectiveScript`."
},
"effectiveScript": {
"type": "string",
"description": "When `isCustomScript` is `true`, this represent the custom script used to calculate a currency pair's exchange rate. Else, it represent the script generated by the default rules and `preferredSource`."
}
}
},
"StoreRateResult": {
"type": "object",
"additionalProperties": false,
"properties": {
"currencyPair": {
"type": "string",
"example": "BTC_USD",
"description": "Currency pair in the format of `BTC_USD`"
},
"errors": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Errors relating to this currency pair fetching based on your config"
},
"rate": {
"type": "string",
"format": "decimal",
"example": "64392.23",
"description": "the rate fetched based on the currency pair"
}
}
},
"StoreUserDataList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreUserData"
}
},
"StoreUserData": {
"allOf": [
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "The id of the user (Deprecated, use `id` instead)",
"nullable": false,
"deprecated": true
},
"role": {
"type": "string",
"description": "The role of the user. Default roles are `Owner`, `Manager`, `Employee` and `Guest` (Deprecated, use `storeRole` instead)",
"nullable": false,
"deprecated": true
},
"storeRole": {
"type": "string",
"description": "The role of the user. Default roles are `Owner`, `Manager`, `Employee` and `Guest`",
"nullable": false
}
}
},
{
"$ref": "#/components/schemas/ApplicationUserData"
}
]
},
"Mnemonic": {
"type": "string",
"description": "A BIP39 mnemonic",
"example": "quality warfare scatter zone report forest potato local swing solve upon candy garment boost lab"
},
"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'"
}
}
},
"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": {
"label": {
"type": "string",
"description": "A label that will be shown in the UI"
},
"existingMnemonic": {
"$ref": "#/components/schemas/Mnemonic"
},
"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!"
},
"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",
"TaprootBIP86"
],
"enum": [
"Legacy",
"Segwit",
"SegwitP2SH",
"TaprootBIP86"
]
}
}
},
"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",
"x-enumNames": [
"Unconfirmed",
"Confirmed"
],
"enum": [
"Unconfirmed",
"Confirmed"
]
},
"LabelData": {
"type": "object",
"additionalProperties": true,
"deprecated": 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": {
"allOf": [
{
"$ref": "#/components/schemas/TransactionStatus"
}
],
"description": "The status of this transaction"
},
"labels": {
"description": "Labels linked to this transaction",
"deprecated": true,
"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",
"deprecated": true,
"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."
},
"signWithSeed": {
"type": "boolean",
"default": true,
"nullable": true,
"description": "If false, build an unsigned PSBT and skip server-side signing (use the CreateOnChainTransactionPSBT client helper)."
},
"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,
"deprecated": true,
"description": "Transaction labels",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"CreateOnChainTransactionResponse": {
"type": "object",
"additionalProperties": false,
"properties": {
"psbt": {
"type": "string",
"description": "Unsigned PSBT in base64 format"
}
}
},
"BroadcastOnChainTransactionRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"transaction": {
"type": "string",
"description": "A finalized PSBT (base64) or raw transaction hex string"
}
},
"required": [
"transaction"
]
},
"OnChainWalletObjectId": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The type of wallet object"
},
"id": {
"type": "string",
"description": "The identifier of the wallet object (unique per type, per wallet)"
}
}
},
"AddOnChainWalletObjectLinkRequest": {
"type": "object",
"additionalProperties": false,
"allOf": [
{
"$ref": "#/components/schemas/OnChainWalletObjectId"
}
],
"properties": {
"data": {
"type": "object",
"additionalProperties": true,
"description": "The data of the link"
}
}
},
"OnChainWalletObjectLink": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "The type of wallet object"
},
"id": {
"type": "string",
"description": "The identifier of the wallet object (unique per type, per wallet)"
},
"linkData": {
"type": "object",
"additionalProperties": true,
"description": "The data of the link"
},
"objectData": {
"type": "object",
"additionalProperties": true,
"description": "The data of the neighbour's node (`null` if there isn't any data or `includeNeighbourData` is `false`)"
}
}
},
"OnChainWalletObjectData": {
"type": "object",
"additionalProperties": false,
"allOf": [
{
"$ref": "#/components/schemas/OnChainWalletObjectId"
}
],
"properties": {
"data": {
"type": "object",
"additionalProperties": true
},
"links": {
"nullable": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/OnChainWalletObjectLink"
},
"description": "Links of this object"
}
}
},
"RoleData": {
"type": "object",
"properties": {
"id": {
"description": "The role's Id (Same as role if the role is created at server level, if the role is created at the store level the format is `STOREID::ROLE`)",
"type": "string",
"nullable": false,
"example": "Owner"
},
"role": {
"description": "The role's name",
"type": "string",
"nullable": false,
"example": "Owner"
},
"permissions": {
"description": "The permissions attached to this role",
"type": "array",
"items": {
"type": "string"
},
"example": [
"btcpay.store.canmodifystoresettings"
]
},
"isServerRole": {
"description": "Whether this role is at the scope of the store or scope of the server",
"type": "boolean",
"example": true
}
}
},
"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
}
}
}
]
},
"PaymentMethodCriteriaData": {
"type": "object",
"properties": {
"paymentMethodId": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodId"
}
],
"nullable": false
},
"currencyCode": {
"type": "string",
"description": "The currency",
"default": "USD",
"example": "USD"
},
"amount": {
"type": "string",
"format": "decimal",
"minimum": 0,
"description": "The amount"
},
"above": {
"type": "boolean",
"default": false,
"description": "If the criterion is for above or below the amount"
}
}
},
"StoreBaseData": {
"type": "object",
"x-abstract": true,
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The name of the store"
},
"website": {
"type": "string",
"nullable": true,
"description": "The absolute url of the store",
"format": "url"
},
"supportUrl": {
"type": "string",
"nullable": true,
"description": "The support URI of the store, can contain the placeholders `{OrderId}` and `{InvoiceId}`. Can be any valid URI, such as a website, email, and nostr.",
"format": "uri"
},
"logoUrl": {
"type": "string",
"nullable": true,
"description": "Absolute URL to a logo file or a reference to an uploaded file id with `fileid:ID`",
"format": "uri"
},
"cssUrl": {
"type": "string",
"nullable": true,
"description": "Absolute URL to CSS file to customize the public/customer-facing pages of the store. (Invoice, Payment Request, Pull Payment, etc.) or a reference to an uploaded file id with `fileid:ID`",
"format": "uri"
},
"paymentSoundUrl": {
"type": "string",
"nullable": true,
"description": "Absolute URL to a sound file or a reference to an uploaded file id with `fileid:ID`",
"format": "uri"
},
"brandColor": {
"type": "string",
"description": "The brand color of the store in HEX format",
"nullable": true,
"example": "#F7931A"
},
"applyBrandColorToBackend": {
"type": "boolean",
"default": false,
"description": "Apply the brand color to the store's backend as well"
},
"defaultCurrency": {
"type": "string",
"description": "The default currency of the store",
"default": "USD",
"example": "USD"
},
"additionalTrackedRates": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional rates to track.\nThe rates of those currencies, in addition to the default currency, will be recorded when a new invoice is created. The rates will then be accessible through reports.",
"default": [],
"example": [
"JPY",
"EUR"
]
},
"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"
}
]
},
"refundBOLT11Expiration": {
"default": 30,
"minimum": 0,
"maximum": 3650,
"description": "The minimum expiry of BOLT11 invoices accepted for refunds by default. (in days)",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanDays"
}
]
},
"displayExpirationTimer": {
"default": 300,
"minimum": 60,
"maximum": 2073600,
"description": "The time left that will trigger the countdown timer on the checkout page to be shown. The value will be rounded down to a minute.",
"allOf": [
{
"$ref": "#/components/schemas/TimeSpanSeconds"
}
]
},
"monitoringExpiration": {
"default": 86400,
"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.0,
"maximum": 100.0,
"default": 0.0,
"description": "Consider an invoice fully paid, even if the payment is missing 'x' % of the full amount."
},
"archived": {
"type": "boolean",
"default": false,
"description": "If true, the store does not appear in the stores list by default."
},
"anyoneCanCreateInvoice": {
"type": "boolean",
"default": false,
"description": "If true, then no authentication is needed to create invoices on this store."
},
"receipt": {
"type": "object",
"nullable": true,
"description": "Additional settings to customize the public receipt",
"allOf": [
{
"$ref": "#/components/schemas/ReceiptOptions"
}
]
},
"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": "Unify on-chain and lightning payment URL."
},
"redirectAutomatically": {
"type": "boolean",
"default": false,
"description": "After successful 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)"
},
"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/))"
},
"autoDetectLanguage": {
"type": "boolean",
"default": false,
"description": "If true, the language on the checkout page will adapt to the language defined by the user's browser settings"
},
"showPayInWalletButton": {
"type": "boolean",
"default": true,
"description": "If true, the \"Pay in wallet\" button will be shown on the checkout page (Checkout V2)"
},
"showStoreHeader": {
"type": "boolean",
"default": true,
"description": "If true, the store header will be shown on the checkout page (Checkout V2)"
},
"celebratePayment": {
"type": "boolean",
"default": true,
"description": "If true, payments on the checkout page will be celebrated with confetti (Checkout V2)"
},
"playSoundOnPayment": {
"type": "boolean",
"default": false,
"description": "If true, sounds on the checkout page will be enabled (Checkout V2)"
},
"lazyPaymentMethods": {
"type": "boolean",
"default": false,
"description": "If true, payment methods are enabled individually upon user interaction in the invoice"
},
"defaultPaymentMethod": {
"$ref": "#/components/schemas/PaymentMethodId"
},
"paymentMethodCriteria": {
"type": "object",
"nullable": true,
"items": {
"$ref": "#/components/schemas/PaymentMethodCriteriaData"
},
"description": "The criteria required to activate specific payment methods."
}
}
},
"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"
]
},
"PortalSessionId": {
"type": "string",
"example": "ps_665afQ23ExGouiY4EZ",
"description": "Identifier of the portal session."
},
"PlanCheckoutId": {
"type": "string",
"description": "Unique identifier of the plan checkout session.",
"example": "plancheckout_Hpm59L1NPCMUj477Q5"
},
"OnPayBehavior": {
"type": "string",
"description": "Defines how the system should behave when payment is processed during a plan checkout or migration.\n* `SoftMigration`: Starts the plan only if payment is due. If no payment is due yet, the amount is added as credit instead of starting the plan.\n* `HardMigration`: Starts the plan immediately, even if payment is not due. If the user already paid for unused time, the unused portion is refunded before starting the plan.",
"enum": [
"SoftMigration",
"HardMigration"
],
"example": "SoftMigration",
"x-enumDescriptions": {
"SoftMigration": "Starts the plan only if payment is due. If no payment is due yet, the amount is added as credit instead of starting the plan.",
"HardMigration": "Starts the plan immediately, even if payment is not due. If the user already paid for unused time, the unused portion is refunded before starting the plan."
}
},
"PlanCheckoutModel": {
"type": "object",
"description": "Represents a checkout session for activating or purchasing a subscription plan.",
"properties": {
"subscriber": {
"$ref": "#/components/schemas/SubscriberModel",
"description": "Subscriber associated with the checkout. (It can be null if the checkout is for a new subscriber, and the users didn't [proceed with the checkout](#operation/ProceedPlanCheckout))"
},
"plan": {
"$ref": "#/components/schemas/OfferingPlanModel",
"description": "Plan being purchased or activated."
},
"baseUrl": {
"$ref": "#/components/schemas/BaseUrl"
},
"id": {
"$ref": "#/components/schemas/PlanCheckoutId"
},
"invoiceId": {
"$ref": "#/components/schemas/InvoiceId"
},
"successRedirectUrl": {
"type": "string",
"description": "URL to redirect the user after checkout success. (The `checkoutPlanId` query parameter will be added to the URL.)",
"example": "https://example.com/success"
},
"expiration": {
"type": "integer",
"format": "unix-time",
"description": "Checkout expiration timestamp.",
"example": 1710602000
},
"redirectUrl": {
"type": "string",
"description": "URL where the user is redirected to proceed with payment.",
"example": "https://pay.example.com/plancheckout_Hpm59L1NPCMUj477Q5"
},
"invoiceMetadata": {
"type": "object",
"description": "Custom metadata that will be attached to the invoice when it is created.",
"additionalProperties": true,
"example": {
"segment": "gold"
}
},
"metadata": {
"type": "object",
"description": "Custom metadata for the checkout.",
"additionalProperties": true,
"example": {
"flow": "upgrade"
}
},
"newSubscriber": {
"type": "boolean",
"description": "Indicates whether the checkout is for a new subscriber.",
"example": false
},
"isTrial": {
"type": "boolean",
"description": "Indicates if the checkout activates a trial.",
"example": false
},
"created": {
"type": "integer",
"format": "unix-time",
"description": "Timestamp when checkout was created.",
"example": 1710500000
},
"planStarted": {
"type": "boolean",
"description": "Indicates if the plan has already been activated.",
"example": false
},
"newSubscriberMetadata": {
"type": "object",
"description": "Metadata for creating a new subscriber.",
"additionalProperties": true,
"example": {
"welcomeTier": "starter"
}
},
"refundAmount": {
"type": "string",
"nullable": true,
"description": "Refund amount applied during migration.",
"example": "3.50"
},
"creditedByInvoice": {
"type": "string",
"description": "Amount credited due to invoice settlement.",
"example": "12.00"
},
"onPayBehavior": {
"$ref": "#/components/schemas/OnPayBehavior",
"description": "Defines how to apply payment behavior."
},
"isExpired": {
"type": "boolean",
"description": "Indicates whether the checkout session has expired.",
"example": false
},
"url": {
"type": "string",
"description": "Public URL for accessing the checkout session.",
"example": "https://btcpay.example.com/plan-checkout/plancheckout_Hpm59L1NPCMUj477Q5"
},
"creditPurchase": {
"type": "string",
"nullable": true,
"description": "Credit amount to purchase to top-up the account. Used when the user wants to top-up his credits. This will not automatically renew the plan.",
"example": "10.00"
}
}
},
"CreatePlanCheckoutRequest": {
"type": "object",
"description": "Request payload for initiating a plan checkout session.",
"properties": {
"storeId": {
"$ref": "#/components/schemas/StoreId"
},
"offeringId": {
"$ref": "#/components/schemas/OfferingId"
},
"planId": {
"$ref": "#/components/schemas/PlanId"
},
"customerSelector": {
"$ref": "#/components/schemas/CustomerSelector"
},
"durationMinutes": {
"type": "integer",
"nullable": true,
"description": "How long the checkout session is valid, in minutes.",
"example": 30
},
"onPayBehavior": {
"$ref": "#/components/schemas/OnPayBehavior",
"nullable": true,
"default": "SoftMigration"
},
"newSubscriberMetadata": {
"type": "object",
"description": "Metadata used when creating a new subscriber.",
"additionalProperties": true,
"example": {
"locale": "en-US"
}
},
"invoiceMetadata": {
"type": "object",
"description": "Metadata attached to the created invoice.",
"additionalProperties": true,
"example": {
"campaign": "winter-sale"
}
},
"metadata": {
"type": "object",
"description": "Custom metadata for the checkout session.",
"additionalProperties": true,
"example": {
"flow": "upgrade"
}
},
"isTrial": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the checkout starts a trial.",
"example": false
},
"creditPurchase": {
"type": "string",
"nullable": true,
"description": "Amount of credit to purchase.",
"example": "20.00"
},
"successRedirectLink": {
"type": "string",
"description": "URL to redirect the user after checkout success. (This default to offering's successRedirectLink, also, the `checkoutPlanId` query parameter will be added to the URL.)",
"example": "https://example.com/thank-you"
},
"newSubscriberEmail": {
"type": "string",
"description": "Email address for creating a new subscriber. Keep `null` to let the user choose an email address in the checkout page.",
"nullable": true,
"example": "user@example.com"
}
}
},
"SuspendSubscriberRequest": {
"type": "object",
"description": "Request payload for suspending a subscriber.",
"properties": {
"reason": {
"type": "string",
"description": "Reason for the suspension.",
"example": "Suspicious behavior detected"
}
}
},
"UpdateSubscriberDatesRequest": {
"type": "object",
"description": "Request payload for updating subscriber dates. All fields are optional \u2014 omitting a field leaves the corresponding date unchanged.",
"properties": {
"startDate": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "New subscription start date as a Unix timestamp. Omit to leave the current start date unchanged.",
"example": 1710000000
},
"expirationDate": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "New expiration date as a Unix timestamp. Updates `trialEnd` if the subscriber is in a trial, otherwise updates `periodEnd`. Grace period end and reminder date are recalculated automatically. Omit to leave the current expiration date unchanged.",
"example": 1712678400
}
}
},
"CustomerSelector": {
"type": "string",
"description": "Flexible identifier for selecting a customer. Supports: customer ID (e.g., `cust_abc123`), an email (e.g., `user@example.com`), or a key/value identity (e.g., `Email:user@example.com`).",
"example": "cust_GUGnpx3311fkaqGk7f"
},
"PlanId": {
"type": "string",
"description": "Plan's ID",
"example": "plan_KZMVyuQp3v2vFWnEUM"
},
"OfferingId": {
"type": "string",
"description": "Offering's ID",
"example": "offering_DKWhZGB6PZsgTcPwpf"
},
"CreateOfferingModel": {
"type": "object",
"description": "New offering data to create.",
"required": [
"appName"
],
"properties": {
"appName": {
"type": "string",
"nullable": true,
"description": "Display name of the related [application](#tag/Apps).",
"example": "Example App"
},
"successRedirectUrl": {
"type": "string",
"nullable": true,
"description": "The default URL to redirect to after a plan checkout is successful.",
"example": "https://example.com/success"
},
"metadata": {
"type": "object",
"description": "Custom metadata for the offering.",
"additionalProperties": true,
"example": {
"category": "saas",
"region": "us"
}
},
"features": {
"type": "array",
"nullable": true,
"description": "List of features included in this offering.",
"items": {
"$ref": "#/components/schemas/FeatureModel"
}
}
}
},
"CustomerId": {
"type": "string",
"description": "Unique identifier of the customer.",
"example": "cust_GUGnpx3311fkaqGk7f"
},
"CustomerModel": {
"type": "object",
"description": "Represents a customer associated with a store.",
"properties": {
"storeId": {
"$ref": "#/components/schemas/StoreId"
},
"id": {
"$ref": "#/components/schemas/CustomerId"
},
"externalId": {
"type": "string",
"description": "External system identifier for the customer.",
"example": "ext_4455"
},
"identities": {
"type": "object",
"description": "Identity attributes for matching and lookup (e.g., email, username).",
"additionalProperties": true,
"example": {
"Email": "subscriber@example.com"
}
},
"metadata": {
"type": "object",
"description": "Custom metadata associated with the customer.",
"additionalProperties": true,
"example": {
"segment": "premium",
"locale": "en-US"
}
}
}
},
"SubscriberModel": {
"type": "object",
"description": "Represents a subscriber of an offering.",
"properties": {
"created": {
"type": "integer",
"format": "unix-time",
"description": "Timestamp when the subscription was created.",
"example": 1710598234
},
"customer": {
"$ref": "#/components/schemas/CustomerModel",
"description": "Customer associated with the subscription."
},
"offering": {
"$ref": "#/components/schemas/OfferingModel",
"description": "Offering associated with the subscription."
},
"plan": {
"$ref": "#/components/schemas/OfferingPlanModel",
"description": "Current active plan of the subscriber."
},
"periodEnd": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "End of the current billing period.",
"example": 1713200000
},
"trialEnd": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "End of the subscriber's trial period.",
"example": 1711000000
},
"gracePeriodEnd": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "End of the grace period.",
"example": 1711500000
},
"isActive": {
"type": "boolean",
"description": "Indicates if the subscription is active. (Phase is not `Expired`, and not suspended)",
"example": true
},
"isSuspended": {
"type": "boolean",
"description": "Indicates if the subscription is suspended.",
"example": false
},
"suspensionReason": {
"type": "string",
"nullable": true,
"description": "Reason for suspension, if applicable.",
"example": "Suspicious activity detected"
},
"autoRenew": {
"type": "boolean",
"description": "Indicates if the subscription renews automatically.",
"example": true
},
"metadata": {
"type": "object",
"description": "Custom metadata for the subscription.",
"additionalProperties": true,
"example": {
"segment": "beta"
}
},
"processingInvoiceId": {
"type": "string",
"nullable": true,
"description": "ID of the invoice being processed.",
"example": "inv_88443"
},
"nextPlan": {
"$ref": "#/components/schemas/OfferingPlanModel",
"nullable": true,
"description": "Plan scheduled for next billing cycle."
},
"scheduledPlan": {
"$ref": "#/components/schemas/OfferingPlanModel",
"nullable": true,
"description": "Plan scheduled to activate at the end of the current billing period."
},
"scheduledPlanActivatesAt": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "Timestamp when the scheduled plan change will activate.",
"example": 1713200000
},
"phase": {
"$ref": "#/components/schemas/SubscriptionPhase"
}
}
},
"OfferingModel": {
"allOf": [
{
"type": "object",
"description": "Represents an offering available in a store.",
"required": [
"appName"
],
"properties": {
"id": {
"$ref": "#/components/schemas/OfferingId"
},
"storeId": {
"$ref": "#/components/schemas/StoreId"
},
"appId": {
"type": "string",
"description": "Identifier of the related [application](#tag/Apps).",
"example": "app-001"
},
"plans": {
"type": "array",
"nullable": true,
"description": "List of plans available for this offering.",
"items": {
"$ref": "#/components/schemas/OfferingPlanModel"
}
}
}
},
{
"$ref": "#/components/schemas/CreateOfferingModel"
}
]
},
"UpdateCreditRequest": {
"type": "object",
"description": "Request payload for updating subscriber credit.",
"properties": {
"credit": {
"type": "string",
"description": "Amount of credit to add as a numeric string.",
"example": "25.00"
},
"charge": {
"type": "string",
"description": "Amount to deduct as a numeric string.",
"example": "10.00"
},
"description": {
"type": "string",
"description": "Short description explaining the credit change.",
"example": "Monthly reward bonus"
},
"allowOverdraft": {
"type": "boolean",
"description": "Indicates if the credit balance is allowed to go negative.",
"example": false
}
}
},
"CreditModel": {
"type": "object",
"description": "Represents a subscriber's credit balance in a specific currency.",
"properties": {
"currency": {
"type": "string",
"description": "Currency code of the credit balance.",
"example": "USD"
},
"value": {
"type": "string",
"description": "Current credit value as a numeric string.",
"example": "150.00"
}
}
},
"CreatePlanRequest": {
"type": "object",
"description": "Request payload for creating a new offering plan.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the plan.",
"example": "Monthly Plan"
},
"description": {
"type": "string",
"description": "Short description of the plan.",
"example": "Standard monthly subscription."
},
"currency": {
"type": "string",
"description": "Currency code for the plan price.",
"example": "USD"
},
"gracePeriodDays": {
"type": "integer",
"nullable": true,
"description": "Number of grace period days after expiry.",
"example": 7
},
"optimisticActivation": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the plan is activated before payment confirmation.",
"example": true
},
"price": {
"type": "string",
"nullable": true,
"description": "Price of the plan as a numeric string.",
"pattern": "^[0-9]+(\\.[0-9]+)?$",
"example": "19.99"
},
"renewable": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the plan can be renewed.",
"example": true
},
"trialDays": {
"type": "integer",
"nullable": true,
"description": "Number of trial days before billing.",
"example": 14
},
"metadata": {
"type": "object",
"description": "Custom metadata for the plan.",
"additionalProperties": true,
"example": {
"tier": "standard"
}
},
"recurringType": {
"type": "string",
"nullable": true,
"description": "Recurring interval for billing.",
"enum": [
"Monthly",
"Quarterly",
"Yearly",
"Lifetime"
],
"example": "Monthly"
},
"features": {
"type": "array",
"nullable": true,
"description": "List of features from the offering included in this plan.",
"items": {
"type": "string"
},
"example": [
"feature-analytics"
]
}
}
},
"CreatePortalSessionRequest": {
"type": "object",
"description": "Request payload for creating a subscriber portal session.",
"properties": {
"storeId": {
"$ref": "#/components/schemas/StoreId"
},
"offeringId": {
"$ref": "#/components/schemas/OfferingId"
},
"customerSelector": {
"$ref": "#/components/schemas/CustomerSelector"
},
"durationMinutes": {
"type": "integer",
"nullable": true,
"description": "Duration in minutes before the portal session expires.",
"example": 30
}
}
},
"PortalSessionModel": {
"type": "object",
"description": "Represents a subscriber portal session used for managing subscriptions, billing, and account details.",
"properties": {
"baseUrl": {
"$ref": "#/components/schemas/BaseUrl"
},
"id": {
"$ref": "#/components/schemas/PortalSessionId"
},
"subscriber": {
"$ref": "#/components/schemas/SubscriberModel",
"description": "The subscriber associated with this portal session."
},
"expiration": {
"type": "integer",
"format": "unix-time",
"nullable": true,
"description": "Expiration timestamp for the portal session.",
"example": 1710602000
},
"isExpired": {
"type": "boolean",
"description": "Indicates whether the portal session is expired.",
"example": false
},
"url": {
"type": "string",
"description": "Public URL where the subscriber can access the portal session.",
"example": "https://btcpay.example.com/subscriber-portal/ps_665afQ23ExGouiY4EZ"
}
}
},
"SubscriptionPhase": {
"type": "string",
"description": "Lifecycle phase of the subscription.",
"enum": [
"Trial",
"Normal",
"Grace",
"Expired"
],
"example": "Normal"
},
"FeatureModel": {
"type": "object",
"description": "Represents a feature that can be included in an offering or plan.",
"required": [
"id",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the feature.",
"example": "feature-analytics"
},
"description": {
"type": "string",
"description": "Short description of the feature.",
"example": "Access to analytics dashboard."
}
}
},
"OfferingPlanModel": {
"type": "object",
"description": "Represents a pricing plan for an offering.",
"properties": {
"id": {
"$ref": "#/components/schemas/PlanId"
},
"name": {
"type": "string",
"description": "Display name of the plan.",
"example": "Starter Plan"
},
"status": {
"type": "string",
"description": "Current status of the plan.",
"enum": [
"Active",
"Retired"
],
"example": "Active"
},
"price": {
"type": "string",
"description": "Price of the plan as a numeric string.",
"pattern": "^[0-9]+(\\.[0-9]+)?$",
"example": "19.99"
},
"currency": {
"type": "string",
"description": "Currency code for the price.",
"example": "USD"
},
"recurringType": {
"type": "string",
"description": "Recurring interval for billing.",
"enum": [
"Monthly",
"Quarterly",
"Yearly",
"Lifetime"
],
"example": "Monthly"
},
"gracePeriodDays": {
"type": "integer",
"description": "Number of grace period days after expiry.",
"example": 7
},
"trialDays": {
"type": "integer",
"description": "Number of trial days before billing.",
"example": 14
},
"description": {
"type": "string",
"description": "Short description of the plan.",
"example": "Standard monthly subscription."
},
"memberCount": {
"type": "integer",
"description": "Maximum number of members allowed under this plan.",
"example": 10
},
"optimisticActivation": {
"type": "boolean",
"description": "Indicates if the plan is activated before payment confirmation.",
"example": true
},
"features": {
"type": "array",
"description": "List of feature identifiers included in this plan.",
"items": {
"type": "string"
},
"example": [
"feature-analytics"
]
},
"renewable": {
"type": "boolean",
"description": "Indicates if the plan can be renewed.",
"example": true
},
"metadata": {
"type": "object",
"description": "Custom metadata for the plan.",
"additionalProperties": true,
"example": {
"tier": "standard"
}
}
}
},
"WebhookSubscriptionEvent": {
"description": "Base data for subscription webhooks.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEvent"
},
{
"type": "object",
"properties": {
"storeId": {
"type": "string",
"description": "The store id of the subscription's event",
"nullable": false,
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
]
}
}
}
]
},
"WebhookSubscriberEvent": {
"description": "Callback sent for subscription events tied to a subscriber.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriptionEvent"
},
{
"type": "object",
"properties": {
"subscriber": {
"$ref": "#/components/schemas/SubscriberModel",
"description": "Subscriber associated with the event."
}
}
}
]
},
"WebhookSubscriberCreditedEvent": {
"description": "Callback sent if the `type` is `SubscriberCredited`",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriberEvent"
},
{
"type": "object",
"properties": {
"total": {
"type": "string",
"format": "decimal",
"description": "Subscriber's total credit after the adjustment.",
"example": "110.00"
},
"amount": {
"type": "string",
"format": "decimal",
"description": "Amount credited to the subscriber.",
"example": "10.00"
},
"currency": {
"type": "string",
"description": "Currency of the credit adjustment.",
"example": "USD"
}
}
}
]
},
"WebhookSubscriberChargedEvent": {
"description": "Callback sent if the `type` is `SubscriberCharged`",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriberEvent"
},
{
"type": "object",
"properties": {
"total": {
"type": "string",
"format": "decimal",
"description": "Subscriber's total credit after the charge.",
"example": "90.00"
},
"amount": {
"type": "string",
"format": "decimal",
"description": "Amount charged from the subscriber.",
"example": "10.00"
},
"currency": {
"type": "string",
"description": "Currency of the charge.",
"example": "USD"
}
}
}
]
},
"WebhookSubscriberPhaseChangedEvent": {
"description": "Callback sent if the `type` is `SubscriberPhaseChanged`",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriberEvent"
},
{
"type": "object",
"properties": {
"previousPhase": {
"allOf": [
{
"$ref": "#/components/schemas/SubscriptionPhase"
}
],
"description": "Previous subscription phase.",
"example": "Trial"
},
"currentPhase": {
"allOf": [
{
"$ref": "#/components/schemas/SubscriptionPhase"
}
],
"description": "Current subscription phase.",
"example": "Normal"
}
}
}
]
},
"WebhookSubscriberDisabledReason": {
"type": "string",
"description": "Reason why the subscriber was disabled.",
"enum": [
"Suspension",
"Expired"
],
"example": "Suspension"
},
"WebhookSubscriberDisabledEvent": {
"description": "Callback sent if the `type` is `SubscriberDisabled`",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriberEvent"
},
{
"type": "object",
"properties": {
"reason": {
"$ref": "#/components/schemas/WebhookSubscriberDisabledReason",
"description": "Whether the subscriber was disabled because of a suspension or expiration.",
"example": "Suspension"
},
"suspensionReason": {
"type": "string",
"nullable": true,
"description": "Suspension reason provided by the merchant when `reason` is `Suspension`.",
"example": "Spam behavior detected."
}
}
}
]
},
"WebhookPlanStartedEvent": {
"description": "Callback sent if the `type` is `PlanStarted`",
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscriberEvent"
},
{
"type": "object",
"properties": {
"autoRenew": {
"type": "boolean",
"description": "Whether the plan got renewed automatically."
}
}
}
]
},
"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
},
"name": {
"type": "string",
"description": "The name of the user",
"nullable": true
},
"imageUrl": {
"type": "string",
"description": "The profile picture URL of the user",
"nullable": true
},
"invitationUrl": {
"type": "string",
"description": "The pending invitation URL of the user",
"nullable": true
},
"emailConfirmed": {
"type": "boolean",
"description": "True if the email has been confirmed by the user"
},
"requiresEmailConfirmation": {
"type": "boolean",
"description": "True if the email requires confirmation to log in"
},
"approved": {
"type": "boolean",
"description": "True if an admin has approved the user"
},
"requiresApproval": {
"type": "boolean",
"description": "True if the instance requires approval to log in"
},
"storeQuota": {
"type": "number",
"nullable": true,
"description": "Per-user override for the max number of stores this user can create. Null means the server default applies"
},
"created": {
"type": "number",
"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"
}
]
},
"disabled": {
"type": "boolean",
"description": "True if an admin has disabled the user"
},
"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"
}
}
},
"ApproveUserRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"approved": {
"type": "boolean",
"description": "Whether to approve or unapprove 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": {
"type": "number",
"nullable": false,
"description": "Timestamp of when the delivery should have been broadcasted",
"allOf": [
{
"$ref": "#/components/schemas/UnixTimestamp"
}
]
},
"deliveryTime": {
"type": "number",
"nullable": false,
"description": "Timestamp of when the delivery has actually been broadcasted. A delay with `timestamp` means your service either failed to process earlier deliveries or is taking too long to respond.",
"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": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of the webhook",
"nullable": false
}
}
},
{
"$ref": "#/components/schemas/WebhookDataBase"
}
]
},
"WebhookDataCreate": {
"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 be auto-generated.",
"nullable": true
}
}
}
]
},
"WebhookDataCreateResult": {
"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/). Value of the auto-generated or custom secret.",
"nullable": true
}
}
}
]
},
"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": {
"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`, `InvoicePaymentSettled`, `PaymentRequestCreated`, `PaymentRequestUpdated`, `PaymentRequestArchived`, `PaymentRequestStatusChanged`, `PayoutCreated`, `PayoutApproved`, `PayoutUpdated`, `SubscriberCreated`, `SubscriberCredited`, `SubscriberCharged`, `SubscriberActivated`, `SubscriberPhaseChanged`, `SubscriberDisabled`, `PaymentReminder`, `PlanStarted`, `SubscriberNeedUpgrade`.",
"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`, `InvoicePaymentSettled`, `PaymentRequestCreated`, `PaymentRequestUpdated`, `PaymentRequestArchived`, `PaymentRequestStatusChanged`, `PayoutCreated`, `PayoutApproved`, `PayoutUpdated`, `SubscriberCreated`, `SubscriberCredited`, `SubscriberCharged`, `SubscriberActivated`, `SubscriberPhaseChanged`, `SubscriberDisabled`, `PaymentReminder`, `PlanStarted`, and `SubscriberNeedUpgrade`."
},
"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,
"allOf": [
{
"$ref": "#/components/schemas/StoreId"
}
]
},
"invoiceId": {
"type": "string",
"description": "The invoice id of the invoice's event",
"nullable": false
},
"metadata": {
"type": "object",
"description": "User-supplied metadata added to the invoice at the time of its creation",
"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 has 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 has 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
},
"paymentMethodId": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethodId"
}
],
"type": "string",
"description": "What payment method was used for this payment",
"nullable": false
},
"payment": {
"description": "Details about the payment",
"allOf": [
{
"$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",
"in": "header",
"name": "Authorization",
"description": "BTCPay Server API key. Format: 'token {apiKey}'"
},
"Basic": {
"type": "http",
"scheme": "basic",
"description": "HTTP Basic Authentication with email and password"
}
}
},
"security": [
{
"API_Key": [],
"Basic": []
}
],
"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/users/{idOrEmail}/api-keys/{apikey}": {
"delete": {
"operationId": "ApiKeys_DeleteUserApiKey",
"tags": [
"API Keys"
],
"summary": "Revoke an API Key of target user",
"description": "Revoke the API key of a target user so that it cannot be used anymore",
"parameters": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
},
{
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmanageusers"
],
"Basic": []
}
]
},
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"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/users/{idOrEmail}/api-keys": {
"post": {
"operationId": "ApiKeys_CreateUserApiKey",
"tags": [
"API Keys"
],
"summary": "Create a new API Key for a user",
"description": "Create a new API Key for a user",
"parameters": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"responses": {
"200": {
"description": "Information about the new API key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKeyData"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"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": [
"btcpay.server.canmanageusers"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/apps/pos": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"post": {
"operationId": "Apps_CreatePointOfSaleApp",
"summary": "Create a new Point of Sale app",
"description": "Point of Sale app allows accepting payments for items in a virtual store",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PointOfSaleAppRequest"
}
}
},
"required": true,
"x-position": 1
},
"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/pos/{appId}": {
"parameters": [
{
"$ref": "#/components/parameters/AppId"
}
],
"put": {
"operationId": "Apps_PutPointOfSaleApp",
"summary": "Update a Point of Sale app",
"description": "Use this endpoint for updating the properties of a POS app",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PointOfSaleAppRequest"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "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": []
}
]
},
"get": {
"tags": [
"Apps",
"Point of Sale"
],
"operationId": "Apps_GetPointOfSaleApp",
"summary": "Get Point of Sale app data",
"description": "Returns POS app data",
"responses": {
"200": {
"description": "POS app data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PointOfSaleAppData"
}
}
}
},
"404": {
"description": "POS app with specified ID was not found"
}
}
}
},
"/api/v1/apps/crowdfund/{appId}": {
"parameters": [
{
"$ref": "#/components/parameters/AppId"
}
],
"put": {
"operationId": "Apps_PutCrowdfundApp",
"summary": "Update a Crowdfund app",
"description": "Full update. GET the app first, modify the data, then PUT the complete payload.",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrowdfundAppRequest"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "App details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrowdfundAppData"
}
}
}
},
"404": {
"description": "Crowdfund app with specified ID was not found"
},
"422": {
"description": "Unable to validate the request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
}
},
"tags": [
"Apps",
"Crowdfund"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"get": {
"tags": [
"Apps",
"Crowdfund"
],
"operationId": "Apps_GetCrowdfundApp",
"summary": "Get crowdfund app data",
"description": "Returns crowdfund app data",
"responses": {
"200": {
"description": "Crowdfund app data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrowdfundAppData"
}
}
}
},
"404": {
"description": "Crowdfund app with specified ID was not found"
}
}
}
},
"/api/v1/stores/{storeId}/apps/crowdfund": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"post": {
"operationId": "Apps_CreateCrowdfundApp",
"summary": "Create a new Crowdfund app",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrowdfundAppRequest"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "Created app details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CrowdfundAppData"
}
}
}
},
"422": {
"description": "Unable to validate the request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
}
},
"tags": [
"Apps",
"Crowdfund"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps/{appId}": {
"get": {
"tags": [
"Apps"
],
"operationId": "Apps_GetApp",
"summary": "Get basic app data",
"description": "Returns basic app data shared between all types of apps",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
}
],
"responses": {
"200": {
"description": "Basic app data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppBaseData"
}
}
}
},
"404": {
"description": "App with specified ID was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Apps"
],
"operationId": "Apps_DeleteApp",
"summary": "Delete app",
"description": "Deletes app with specified ID",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
}
],
"responses": {
"200": {
"description": "App was deleted"
},
"404": {
"description": "App with specified ID was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps/{appId}/image": {
"post": {
"tags": [
"Apps"
],
"summary": "Uploads an image for an app item",
"description": "Uploads an image for an app item",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"file": {
"type": "string",
"description": "The image",
"format": "binary"
}
}
}
}
}
},
"operationId": "Apps_UploadAppItemImage",
"responses": {
"200": {
"description": "Uploads an image for an app item",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileData"
}
}
}
},
"404": {
"description": "The app could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps/{appId}/image/{fileId}": {
"delete": {
"tags": [
"Apps"
],
"summary": "Deletes the app item image",
"description": "Deletes the app item image",
"operationId": "App_DeleteAppItemImage",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
},
{
"name": "fileId",
"in": "path",
"required": true,
"description": "The file ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "App item image deleted successfully"
},
"404": {
"description": "The app could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps/{appId}/sales": {
"get": {
"tags": [
"Apps"
],
"operationId": "Apps_GetAppSales",
"summary": "Get app sales statistics",
"description": "Returns sales statistics for the app",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
},
{
"name": "numberOfDays",
"in": "query",
"required": false,
"description": "How many of the last days",
"schema": {
"nullable": true,
"type": "number",
"default": 7
}
}
],
"responses": {
"200": {
"description": "App sales statistics",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppSalesStats"
}
}
}
},
"404": {
"description": "App with specified ID was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps/{appId}/top-items": {
"get": {
"tags": [
"Apps"
],
"operationId": "Apps_GetAppTopItems",
"summary": "Get app top items statistics",
"description": "Returns top items statistics for the app",
"parameters": [
{
"$ref": "#/components/parameters/AppId"
},
{
"name": "count",
"in": "query",
"required": false,
"description": "How many of the items",
"schema": {
"nullable": true,
"type": "number",
"default": 5
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset for paging",
"schema": {
"nullable": true,
"type": "number",
"default": 0
}
}
],
"responses": {
"200": {
"description": "App top items statistics",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppItemStats"
}
}
}
}
},
"404": {
"description": "App with specified ID was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/apps": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"get": {
"tags": [
"Apps"
],
"operationId": "Apps_GetAllAppsForStore",
"summary": "Get basic app data for all apps for a store",
"description": "Returns basic app data for all apps for a store",
"responses": {
"200": {
"description": "Array of basic app data object",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppBaseData"
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/apps": {
"get": {
"tags": [
"Apps"
],
"operationId": "Apps_GetAllApps",
"summary": "Get basic app data for all apps for all stores for a user",
"description": "Returns basic app data for all apps for all stores",
"responses": {
"200": {
"description": "Array of basic app data object",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppBaseData"
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
}
},
"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"
},
"401": {
"description": "Missing authorization",
"content": {
"text/html": {}
}
}
},
"security": []
}
},
"/api/v1/files": {
"get": {
"operationId": "Files_GetFiles",
"tags": [
"Files"
],
"summary": "Get all files",
"description": "Load all files that exist.",
"parameters": [],
"responses": {
"200": {
"description": "Files found",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileData"
}
}
}
}
},
"401": {
"description": "Missing authorization for loading the files"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Files"
],
"summary": "Uploads a file",
"description": "Uploads a file",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"file": {
"type": "string",
"description": "The profile picture",
"format": "binary"
}
}
}
}
}
},
"operationId": "Files_UploadFile",
"responses": {
"200": {
"description": "Uploads a file",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileData"
}
}
}
},
"415": {
"description": "The upload did not work"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"Basic": []
}
]
}
},
"/api/v1/files/{fileId}": {
"get": {
"operationId": "Files_GetFile",
"tags": [
"Files"
],
"summary": "Get file",
"description": "View information about the specified file",
"parameters": [
{
"name": "fileId",
"in": "path",
"required": true,
"description": "The file information to fetch",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "File found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileData"
}
}
}
},
"401": {
"description": "Missing authorization for loading the file"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Files"
],
"summary": "Delete file",
"description": "Deletes the file",
"operationId": "Files_DeleteFile",
"parameters": [
{
"name": "fileId",
"in": "path",
"required": true,
"description": "The file to delete",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "File deleted successfully"
},
"404": {
"description": "The file could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"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"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": []
}
},
"/api/v1/stores/{storeId}/invoices": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get invoices",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"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"
}
},
{
"name": "includePaymentMethods",
"in": "query",
"required": false,
"description": "Includes payment methods available to the response",
"schema": {
"type": "boolean",
"default": false
}
}
],
"description": "View information about the existing invoices",
"operationId": "Invoices_GetInvoices",
"responses": {
"200": {
"description": "List of invoices",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceDataList"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewinvoices"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Invoices"
],
"summary": "Create a new invoice",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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/invoices/{invoiceId}": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get invoice",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"description": "View information about the specified invoice. The store is resolved automatically from the 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. The store is resolved automatically from the invoice.",
"operationId": "Invoices_ArchiveInvoice",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"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. The store is resolved automatically from the invoice.",
"operationId": "Invoices_UpdateInvoice",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"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/invoices/{invoiceId}/payment-methods": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get invoice payment methods",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
},
{
"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
}
},
{
"name": "includeSensitive",
"in": "query",
"required": false,
"description": "If `true`, `additionalData` might include sensitive data (such as xpub). Requires the permission `btcpay.store.canmodifystoresettings`.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"description": "View information about the specified invoice's payment methods. The store is resolved automatically from the invoice.",
"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/invoices/{invoiceId}/status": {
"post": {
"tags": [
"Invoices"
],
"summary": "Mark invoice status",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"description": "Mark an invoice as invalid or settled. The store is resolved automatically from the invoice.",
"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/invoices/{invoiceId}/unarchive": {
"post": {
"tags": [
"Invoices"
],
"summary": "Unarchive invoice",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"description": "Unarchive an invoice. The store is resolved automatically from the 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/invoices/{invoiceId}/payment-methods/{paymentMethodId}/activate": {
"post": {
"tags": [
"Invoices"
],
"summary": "Activate Payment Method",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"description": "Activate an invoice payment method (if lazy payments mode is enabled). The store is resolved automatically from the invoice.",
"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/invoices/{invoiceId}/refund": {
"post": {
"tags": [
"Invoices"
],
"summary": "Refund invoice",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
}
],
"description": "Refund invoice. The store is resolved automatically from the invoice.",
"operationId": "Invoices_Refund",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundInvoiceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Pull payment for refunding the invoice",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PullPaymentData"
}
}
}
},
"400": {
"description": "A list of errors that occurred when refunding the invoice",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to refund the invoice"
}
},
"security": [
{
"API_Key": [
"btcpay.store.cancreatepullpayments"
],
"Basic": []
}
]
}
},
"/api/v1/invoices/{invoiceId}/refund/{paymentMethodId}": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get invoice refund trigger data",
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"description": "View calculated refund amounts for the specified invoice/payment-method. The store is resolved automatically from the invoice.",
"operationId": "Invoices_GetInvoiceRefundTriggerData",
"responses": {
"200": {
"description": "specified invoice refund trigger data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceRefundTriggerData"
}
}
}
},
"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.cancreatepullpayments"
],
"Basic": []
}
]
}
},
"/api/v1/server/lightning/{cryptoCode}/info": {
"get": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Get node information",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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}/histogram": {
"get": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Get node balance histogram",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"description": "View balance histogram of the lightning node",
"operationId": "InternalLightningNodeApi_GetHistogram",
"responses": {
"200": {
"description": "Lightning node balance histogram for off-chain funds",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistogramData"
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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": "Well-known 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": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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": "Well-known 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": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"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.canviewlightninginvoiceinternalnode"
],
"Basic": []
}
]
}
},
"/api/v1/server/lightning/{cryptoCode}/invoices/pay": {
"post": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Pay Lightning Invoice",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"description": "Pay a lightning invoice. In case the payment response times out, the status will be reported as pending and the final status can be resolved using the [Get payment](#operation/InternalLightningNodeApi_GetPayment) endpoint. The default wait time for payment responses is 30 seconds \u2014 it might take longer if multiple routes are tried or a hold invoice is getting paid.",
"operationId": "InternalLightningNodeApi_PayInvoice",
"responses": {
"200": {
"description": "Successfully paid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningPaymentData"
}
}
}
},
"202": {
"description": "Payment initiated",
"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": "Well-known 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": {
"get": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Get invoices",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"name": "pendingOnly",
"in": "query",
"required": false,
"description": "Limit to pending invoices only",
"schema": {
"type": "boolean",
"nullable": true,
"default": false
}
},
{
"name": "offsetIndex",
"in": "query",
"required": false,
"description": "The index of an invoice that will be used as the start of the list",
"schema": {
"type": "number",
"nullable": true,
"default": 0
}
}
],
"description": "View information about the lightning invoices",
"operationId": "InternalLightningNodeApi_GetInvoices",
"responses": {
"200": {
"description": "Lightning invoice data",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningInvoiceData"
}
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Unable to access the lightning node"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.server.canviewlightninginvoiceinternalnode"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Create lightning invoice",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
}
],
"description": "Create a lightning invoice.",
"operationId": "InternalLightningNodeApi_CreateInvoice",
"responses": {
"200": {
"description": "Successfully created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningInvoiceData"
}
}
}
},
"400": {
"description": "Well-known 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/server/lightning/{cryptoCode}/payments": {
"get": {
"tags": [
"Lightning (Internal Node)"
],
"summary": "Get payments",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"name": "includePending",
"in": "query",
"required": false,
"description": "Also include pending payments",
"schema": {
"type": "boolean",
"nullable": true,
"default": false
}
},
{
"name": "offsetIndex",
"in": "query",
"required": false,
"description": "The index of a payment that will be used as the start of the list",
"schema": {
"type": "number",
"nullable": true,
"default": 0
}
}
],
"description": "View information about the lightning payments",
"operationId": "InternalLightningNodeApi_GetPayments",
"responses": {
"200": {
"description": "Lightning payment data",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningPaymentData"
}
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Unable to access the lightning node"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.server.canuseinternallightningnode"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/lightning/{cryptoCode}/info": {
"get": {
"tags": [
"Lightning (Store)"
],
"summary": "Get node information",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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}/histogram": {
"get": {
"tags": [
"Lightning (Store)"
],
"summary": "Get node balance histogram",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "View balance histogram of the lightning node",
"operationId": "StoreLightningNodeApi_GetHistogram",
"responses": {
"200": {
"description": "Lightning node balance histogram for off-chain funds",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistogramData"
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": "Well-known 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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": "Well-known 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"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
},
{
"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": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
},
{
"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.canviewlightninginvoice"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices/pay": {
"post": {
"tags": [
"Lightning (Store)"
],
"summary": "Pay Lightning Invoice",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Pay a lightning invoice. In case the payment response times out, the status will be reported as pending and the final status can be resolved using the [Get payment](#operation/StoreLightningNodeApi_GetPayment) endpoint. The default wait time for payment responses is 30 seconds \u2014 it might take longer if multiple routes are tried or a hold invoice is getting paid.",
"operationId": "StoreLightningNodeApi_PayInvoice",
"responses": {
"200": {
"description": "Successfully paid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningPaymentData"
}
}
}
},
"202": {
"description": "Payment initiated",
"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": "Well-known 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": {
"get": {
"tags": [
"Lightning (Store)"
],
"summary": "Get invoices",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "pendingOnly",
"in": "query",
"required": false,
"description": "Limit to pending invoices only",
"schema": {
"type": "boolean",
"nullable": true,
"default": false
}
},
{
"name": "offsetIndex",
"in": "query",
"required": false,
"description": "The index of an invoice that will be used as the start of the list",
"schema": {
"type": "number",
"nullable": true,
"default": 0
}
}
],
"description": "View information about the lightning invoices",
"operationId": "StoreLightningNodeApi_GetInvoices",
"responses": {
"200": {
"description": "Lightning invoice data",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningInvoiceData"
}
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Unable to access the lightning node"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewlightninginvoice"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Lightning (Store)"
],
"summary": "Create lightning invoice",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Create a lightning invoice.",
"operationId": "StoreLightningNodeApi_CreateInvoice",
"responses": {
"200": {
"description": "Successfully created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningInvoiceData"
}
}
}
},
"400": {
"description": "Well-known 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}/payments": {
"get": {
"tags": [
"Lightning (Store)"
],
"summary": "Get payments",
"parameters": [
{
"$ref": "#/components/parameters/CryptoCode"
},
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "includePending",
"in": "query",
"required": false,
"description": "Also include pending payments",
"schema": {
"type": "boolean",
"nullable": true,
"default": false
}
},
{
"name": "offsetIndex",
"in": "query",
"required": false,
"description": "The index of an invoice that will be used as the start of the list",
"schema": {
"type": "number",
"nullable": true,
"default": 0
}
}
],
"description": "View information about the lightning payments",
"operationId": "StoreLightningNodeApi_GetPayments",
"responses": {
"200": {
"description": "Lightning payment data",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningPaymentData"
}
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"503": {
"description": "Unable to access the lightning node"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.cancreatelightninginvoice"
],
"Basic": []
}
]
}
},
"/misc/rate-sources": {
"get": {
"tags": [
"Miscelleneous"
],
"summary": "Get available rate sources",
"description": "View available rate providers that you can use in stores",
"operationId": "GetRateSources",
"responses": {
"200": {
"description": "rate providers array",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "The id of the rate provider"
},
"name": {
"type": "string",
"description": "The name of the rate provider"
}
}
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": []
}
},
"/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"
}
}
}
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"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
}
}
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": []
}
},
"/i/{invoiceId}": {
"parameters": [
{
"$ref": "#/components/parameters/InvoiceId"
},
{
"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"
}
}
},
"404": {
"description": "The invoice could not be found"
}
},
"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"
}
},
{
"name": "storeId",
"in": "query",
"required": false,
"description": "Array of store ids to fetch the notifications for",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"example": "&storeId=ABCDE&storeId=FGHIJ"
}
],
"description": "View current user's notifications",
"operationId": "Notifications_GetNotifications",
"responses": {
"200": {
"description": "list of notifications",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationData"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
}
},
"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/users/me/notification-settings": {
"get": {
"tags": [
"Notifications (Current User)"
],
"summary": "Get notification settings",
"description": "View information about your notification settings",
"operationId": "Notifications_GetNotificationSettings",
"responses": {
"200": {
"description": "The current user's notification settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationSettingsData"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to view the notification settings"
}
},
"security": [
{
"API_Key": [
"btcpay.user.canmanagenotificationsforuser"
],
"Basic": []
}
]
},
"put": {
"tags": [
"Notifications (Current User)"
],
"summary": "Update notification settings",
"description": "Updates the current user's notification settings",
"operationId": "Notifications_UpdateNotificationSettings",
"responses": {
"200": {
"description": "The current user's notification settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationSettingsData"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to update the notification settings"
}
},
"security": [
{
"API_Key": [
"btcpay.user.canmanagenotificationsforuser"
],
"Basic": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateNotificationSettingsRequest"
}
}
}
}
}
},
"/api/v1/stores/{storeId}/payment-requests": {
"get": {
"tags": [
"Payment Requests"
],
"summary": "Get payment requests",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewpaymentrequests"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Payment Requests"
],
"summary": "Create a new payment request",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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/payment-requests/{paymentRequestId}": {
"get": {
"tags": [
"Payment Requests"
],
"summary": "Get payment request",
"parameters": [
{
"name": "paymentRequestId",
"in": "path",
"required": true,
"description": "The payment request to fetch",
"schema": {
"type": "string"
}
}
],
"description": "View information about the specified payment request. The store is resolved automatically from the 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. The store is resolved automatically from the payment request.",
"operationId": "PaymentRequests_ArchivePaymentRequest",
"parameters": [
{
"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": "paymentRequestId",
"in": "path",
"required": true,
"description": "The payment request to update",
"schema": {
"type": "string"
}
}
],
"description": "Update a payment request. The store is resolved automatically from the 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/payment-requests/{paymentRequestId}/pay": {
"post": {
"tags": [
"Payment Requests"
],
"summary": "Create a new invoice for the payment request",
"parameters": [
{
"name": "paymentRequestId",
"in": "path",
"required": true,
"description": "The payment request to create",
"schema": {
"type": "string"
}
}
],
"operationId": "PaymentRequests_Pay",
"description": "Create a new invoice for the payment request, or reuse an existing one. The store is resolved automatically from the payment request.",
"requestBody": {
"description": "Invoice creation request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"type": "string",
"format": "decimal",
"minimum": 0,
"exclusiveMinimum": true,
"description": "The amount of the invoice. If `null` or `unspecified`, it will be set to the payment request's due amount. Note that the payment's request `allowCustomPaymentAmounts` must be `true`, or a 422 error will be sent back.'",
"nullable": true,
"example": "0.1"
},
"allowPendingInvoiceReuse": {
"type": "boolean",
"nullable": true,
"default": false,
"description": "If `true`, this endpoint will not necessarily create a new invoice, and instead attempt to give back a pending one for this payment request."
}
}
}
}
}
},
"responses": {
"200": {
"description": "A new invoice",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceData"
}
}
}
},
"422": {
"description": "Unable to validate the request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"400": {
"description": "Well-known error codes are: `archived`, `already-paid`, `expired`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewpaymentrequests"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payout-processors": {
"get": {
"tags": [
"Stores (Payout Processors)"
],
"summary": "Get store configured payout processors",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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}/{paymentMethodId}": {
"delete": {
"tags": [
"Stores (Payout Processors)"
],
"summary": "Remove store configured payout processor",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "processor",
"in": "path",
"required": true,
"description": "The processor",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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"
}
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
}
},
"security": [
{
"API_Key": [],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payout-processors/OnChainAutomatedPayoutSenderFactory/{paymentMethodId}": {
"get": {
"tags": [
"Stores (Payout Processors)"
],
"summary": "Get configured store onchain automated payout processors",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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/LightningAutomatedPayoutSenderFactory/{payoutMethodId}": {
"get": {
"tags": [
"Stores (Payout Processors)"
],
"summary": "Get configured store Lightning automated payout processors",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PayoutMethodId"
}
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PayoutMethodId"
}
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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/LightningAutomatedPayoutSenderFactory": {
"get": {
"tags": [
"Stores (Payout Processors)"
],
"summary": "Get configured store Lightning automated payout processors",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Get configured store Lightning automated payout processors",
"operationId": "GreenfieldStoreAutomatedLightningPayoutProcessorsController_GetStoreLightningAutomatedPayoutSenderFactory",
"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/pull-payments/{pullPaymentId}/boltcards": {
"parameters": [
{
"name": "pullPaymentId",
"in": "path",
"required": true,
"description": "The ID of the pull payment",
"schema": {
"type": "string"
}
}
],
"post": {
"operationId": "PullPayments_LinkBoltcard",
"summary": "Link a boltcard to a pull payment",
"description": "Linking a boltcard to a pull payment will allow you to pay via NFC with it, the money will be sent from the pull payment. The boltcard keys are generated using [Deterministic Boltcard Key Generation](https://github.com/boltcard/boltcard/blob/main/docs/DETERMINISTIC.md).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"UID"
],
"type": "object",
"properties": {
"UID": {
"type": "string",
"example": "46ab87ff36a3b7",
"description": "The `UID` of the NTag424",
"nullable": false
},
"onExisting": {
"type": "string",
"x-enumNames": [
"KeepVersion",
"UpdateVersion"
],
"enum": [
"KeepVersion",
"UpdateVersion"
],
"default": "UpdateVersion",
"description": "What to do if the boltcard is already linked.\n * `KeepVersion` will return the keys (K0-K4) that are already registered.\n * `UpdateVersion` will increment the version of the key, and thus return different keys (K0-K4). (See [Deterministic Boltcard Key Generation](https://github.com/boltcard/boltcard/blob/main/docs/DETERMINISTIC.md))"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The boltcard has been linked to the pull payment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"LNURLW": {
"type": "string",
"description": "The lnurl withdraw of the server",
"example": "lnurlw://example.com/boltcard"
},
"version": {
"type": "number",
"description": "The version of the registration (See [Deterministic Boltcard Key Generation](https://github.com/boltcard/boltcard/blob/main/docs/DETERMINISTIC.md))"
},
"K0": {
"type": "string",
"description": "The public key K0 of the boltcard",
"example": "02a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
},
"K1": {
"type": "string",
"description": "The public key K1 of the boltcard",
"example": "02a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
},
"K2": {
"type": "string",
"description": "The public key K2 of the boltcard",
"example": "02a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
},
"K3": {
"type": "string",
"description": "The public key K3 of the boltcard",
"example": "02a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
},
"K4": {
"type": "string",
"description": "The public key K4 of the boltcard",
"example": "02a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
}
}
}
}
}
},
"404": {
"description": "The pull payment has not been found. Well-known error code is: `pullpayment-not-found`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"tags": [
"Pull payments (Public)"
],
"security": []
}
},
"/api/v1/stores/{storeId}/pull-payments": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the data"
}
},
"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."
},
"BOLT11Expiration": {
"type": "string",
"example": 30,
"default": 30,
"nullable": true,
"description": "If lightning is activated, do not accept BOLT11 invoices with expiration less than \u2026 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."
},
"payoutMethods": {
"type": "array",
"description": "The list of supported payout methods supported by this pull payment. Available options can be queried from the `StorePaymentMethods_GetStorePaymentMethods` endpoint. If `null`, all available payout methods will be supported.",
"items": {
"type": "string",
"example": "BTC"
},
"nullable": true
}
}
}
}
}
},
"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.cancreatepullpayments",
"btcpay.store.cancreatenonapprovedpullpayments"
],
"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": []
},
"delete": {
"operationId": "PullPayments_ArchivePullPayment",
"summary": "Archive a pull payment",
"description": "Archive this pull payment (Will cancel all payouts awaiting for payment). The store is resolved automatically from the pull payment.",
"responses": {
"200": {
"description": "The pull payment has been archived"
},
"404": {
"description": "The pull payment has not been found. Well-known error code is: `pullpayment-not-found`"
}
},
"tags": [
"Pull payments (Management)"
],
"security": [
{
"API_Key": [
"btcpay.store.canarchivepullpayments"
],
"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": "Well-known 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/pull-payments/{pullPaymentId}/lnurl": {
"parameters": [
{
"name": "pullPaymentId",
"in": "path",
"required": true,
"description": "The ID of the pull payment",
"schema": {
"type": "string"
}
}
],
"get": {
"summary": "Get Pull Payment LNURL details",
"operationId": "PullPayments_GetPullPaymentLNURL",
"description": "Get Pull Payment LNURL details",
"responses": {
"200": {
"description": "Pull payment LNURL details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LNURLData"
}
}
}
},
"404": {
"description": "Pull payment not found"
},
"400": {
"description": "Pull payment found but does not support LNURL"
}
},
"tags": [
"Pull payments (Public)"
],
"security": []
}
},
"/api/v1/stores/{storeId}/payouts": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": "Well-known 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.cancreatepullpayments",
"btcpay.store.cancreatenonapprovedpullpayments"
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "payoutId",
"in": "path",
"required": true,
"description": "The ID of the payout",
"schema": {
"type": "string"
}
}
],
"get": {
"summary": "Get Payout",
"operationId": "GetStorePayout",
"description": "Get payout",
"responses": {
"200": {
"description": "A specific payout of a store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PayoutData"
}
}
}
},
"404": {
"description": "Payout not found"
}
},
"tags": [
"Stores (Payouts)"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagepullpayments"
],
"Basic": []
}
]
},
"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": "Well-known 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": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"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": "Well-known 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/stores/{storeId}/payouts/{payoutId}/mark": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "payoutId",
"in": "path",
"required": true,
"description": "The ID of the payout",
"schema": {
"type": "string"
}
}
],
"post": {
"summary": "Mark Payout",
"operationId": "PullPayments_MarkPayout",
"description": "Mark a payout with a state",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"state": {
"$ref": "#/components/schemas/PayoutState"
},
"paymentProof": {
"$ref": "#/components/schemas/PayoutPaymentProof"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The payout has been set to the specified state"
},
"422": {
"description": "Unable to validate the request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"400": {
"description": "Well-known 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/email": {
"get": {
"tags": [
"ServerEmail"
],
"summary": "Get server email settings",
"description": "Retrieve the email settings configured for the server. The password field will be masked if present.",
"operationId": "ServerEmail_GetSettings",
"responses": {
"200": {
"description": "Server email settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetServerEmailSettings"
}
}
}
},
"403": {
"description": "Forbidden - Insufficient permissions"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"Basic": []
}
]
},
"put": {
"tags": [
"ServerEmail"
],
"summary": "Update server email settings",
"description": "Update server's email settings.",
"operationId": "ServerEmail_UpdateSettings",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateServerEmailSettings"
}
}
}
},
"responses": {
"200": {
"description": "Server email settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetServerEmailSettings"
}
}
}
},
"400": {
"description": "Invalid request or email format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden - Insufficient permissions"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [],
"Basic": []
}
]
}
},
"/api/v1/server/roles": {
"get": {
"tags": [
"ServerInfo"
],
"summary": "Get store's roles",
"description": "View information about the store's roles at the server's scope",
"operationId": "Server_GetStoreRoles",
"responses": {
"200": {
"description": "The user roles available at the server's scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleData"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the store's roles"
},
"404": {
"description": "Store not found"
}
},
"security": [
{
"API_Key": [
"btcpay.server.canmodifyserversettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/email": {
"get": {
"tags": [
"Stores (Email)"
],
"summary": "Get store email settings",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Retrieve the email settings configured for specific store. The password field will be masked if present.",
"operationId": "Stores_GetStoreEmailSettings",
"responses": {
"200": {
"description": "specified store email settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetEmailSettings"
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Update a store's email settings",
"operationId": "Stores_UpdateStoreEmailSettings",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEmailSettings"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "The settings were updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetEmailSettings"
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"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."
}
}
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"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}/lightning-addresses": {
"get": {
"tags": [
"Lightning address"
],
"summary": "Get store configured lightning addresses",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Get store configured lightning addresses",
"operationId": "StoreLightningAddresses_GetStoreLightningAddresses",
"responses": {
"200": {
"description": "The lightning addresses configured in the store",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightningAddressData"
}
}
}
}
},
"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}/lightning-addresses/{username}": {
"get": {
"tags": [
"Lightning address"
],
"summary": "Get store configured lightning address",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "username",
"in": "path",
"required": true,
"description": "The lightning address username",
"schema": {
"type": "string"
}
}
],
"description": "Get store configured lightning address",
"operationId": "StoreLightningAddresses_GetStoreLightningAddress",
"responses": {
"200": {
"description": "The lightning address configured in the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningAddressData"
}
}
}
},
"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": []
}
]
},
"post": {
"tags": [
"Lightning address"
],
"summary": "Add or update store configured lightning address",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "username",
"in": "path",
"required": true,
"description": "the lightning address username",
"schema": {
"type": "string"
}
}
],
"description": "Add or update store configured lightning address",
"operationId": "StoreLightningAddresses_AddOrUpdateStoreLightningAddress",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningAddressData"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "The lightning address configured in the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightningAddressData"
}
}
}
},
"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": [
"Lightning address"
],
"summary": "Remove configured lightning address",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "username",
"in": "path",
"required": true,
"description": "The lightning address username",
"schema": {
"type": "string"
}
}
],
"description": "Remove store configured lightning address",
"operationId": "StoreLightningAddresses_RemoveStoreLightningAddress",
"responses": {
"200": {
"description": "Lightning address removed"
},
"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": {
"get": {
"tags": [
"Store (Payment Methods)"
],
"summary": "Get store payment methods",
"description": "View information about the stores' configured payment methods",
"operationId": "StorePaymentMethods_GetStorePaymentMethods",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "onlyEnabled",
"in": "query",
"required": false,
"description": "Fetch payment methods that are enabled/disabled only",
"schema": {
"type": "boolean"
}
},
{
"name": "includeConfig",
"in": "query",
"required": false,
"description": "Fetch the config of the payment methods, if `true`, the permission `btcpay.store.canmodifystoresettings` is required.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "List of payment methods",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GenericPaymentMethodData"
}
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewstoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}": {
"get": {
"tags": [
"Store (Payment Methods)"
],
"summary": "Get store payment method",
"description": "View information about the stores' configured payment method",
"operationId": "StorePaymentMethods_GetStorePaymentMethod",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "includeConfig",
"in": "query",
"required": false,
"description": "Fetch the config of the payment methods, if `true`, the permission `btcpay.store.canmodifystoresettings` is required.",
"schema": {
"type": "boolean"
}
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"responses": {
"200": {
"description": "The payment method config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericPaymentMethodData"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewstoresettings"
],
"Basic": []
}
]
},
"put": {
"tags": [
"Store (Payment Methods)"
],
"summary": "Update store's payment method",
"description": "Update information about the stores' configured payment method",
"operationId": "StorePaymentMethods_UpdateStorePaymentMethod",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePaymentMethodConfig"
}
}
}
},
"responses": {
"200": {
"description": "The payment method config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericPaymentMethodData"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Store (Payment Methods)"
],
"summary": "Delete store's payment method",
"description": "Delete information about the stores' configured payment method",
"operationId": "StorePaymentMethods_DeleteStorePaymentMethod",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"responses": {
"200": {
"description": "The configuration got deleted"
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/rates": {
"get": {
"tags": [
"Stores (Rates)"
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "currencyPair",
"description": "The currency pairs to fetch rates for",
"example": [
"BTC_USD",
"BTC_EUR"
],
"in": "query",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"x-position": 1
}
],
"summary": "Get rates",
"description": "Get rates on the store",
"operationId": "Stores_GetStoreRates",
"responses": {
"200": {
"description": "The settings were executed and a preview was returned",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreRateResult"
}
}
}
}
},
"400": {
"description": "A list of errors that occurred when previewing 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.canviewstoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/rates/configuration/{rateSource}": {
"get": {
"tags": [
"Stores (Rates)"
],
"summary": "Get store rate settings for the specified rate source",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/RateSource"
}
],
"description": "View rate settings for the specified store and rate source (`primary` or `fallback`).",
"operationId": "Stores_GetStoreRateConfiguration",
"responses": {
"200": {
"description": "specified store rate settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRateConfiguration"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to view the specified store"
},
"404": {
"description": "The specified store or rate source was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewstoresettings"
],
"Basic": []
}
]
},
"put": {
"tags": [
"Stores (Rates)"
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/RateSource"
}
],
"summary": "Get store rate settings for the specified rate source",
"description": "Update rate settings for the specified store and rate source (`primary` or `fallback`).",
"operationId": "Stores_UpdateStoreRateConfiguration",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRateConfiguration"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "The settings were updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRateConfiguration"
}
}
}
},
"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}/rates/configuration/preview": {
"post": {
"tags": [
"Stores (Rates)"
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "currencyPair",
"description": "The currency pairs to preview",
"in": "query",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"x-position": 1
}
],
"summary": "Preview rate configuration results",
"description": "Preview rate configuration results before you set it on the store",
"operationId": "Stores_PreviewStoreRateConfiguration",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRateConfiguration"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "The settings were executed and a preview was returned",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreRateResult"
}
}
}
}
},
"400": {
"description": "A list of errors that occurred when previewing 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}/users": {
"get": {
"tags": [
"Stores (Users)"
],
"summary": "Get store users",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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's users"
},
"404": {
"description": "The store could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Stores (Users)"
],
"summary": "Add a store user",
"description": "Add a store user",
"operationId": "Stores_AddStoreUser",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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 adding the store user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to add new store users"
},
"404": {
"description": "The store or user could not be found"
},
"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/{idOrEmail}": {
"put": {
"tags": [
"Stores (Users)"
],
"summary": "Updates a store user",
"description": "Updates a store user",
"operationId": "Stores_UpdateStoreUser",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreUserData"
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"200": {
"description": "The user was updated"
},
"400": {
"description": "A list of errors that occurred when updating the store user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to update store users"
},
"404": {
"description": "The store or user could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"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": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"responses": {
"200": {
"description": "The user has been removed"
},
"400": {
"description": "A list of errors that occurred when removing the store user",
"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 user"
},
"404": {
"description": "The store or user could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet overview",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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.canviewwallet"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/histogram": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet balance histogram",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"description": "View the balance histogram of the specified wallet",
"operationId": "StoreOnChainWallets_ShowOnChainWalletHistogram",
"responses": {
"200": {
"description": "specified wallet",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistogramData"
}
}
}
},
"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.canviewwallet"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/feerate": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet fee rate",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"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.canviewwallet"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/address": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet address",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"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.canviewwallet"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "UnReserve last store on-chain wallet address",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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.canmanagewallettransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet transactions",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"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.canviewwallet"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Create store on-chain wallet transaction",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOnChainTransactionRequest"
}
}
}
},
"description": "Create store on-chain wallet transaction. Requires `btcpay.store.cancreatetransactions` and `btcpay.store.cansigntransactions`. Also requires `btcpay.store.canbroadcasttransactions` when `proceedWithBroadcast` is true, including Payjoin.",
"operationId": "StoreOnChainWallets_CreateOnChainTransaction",
"responses": {
"200": {
"description": "the tx",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"description": "The unbroadcasted transaction in hex format",
"type": "string"
},
{
"description": "An unsigned PSBT in base64 format",
"$ref": "#/components/schemas/CreateOnChainTransactionResponse"
},
{
"$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.cancreatetransactions",
"btcpay.store.cansigntransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/broadcast": {
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Broadcast an on-chain transaction or finalized PSBT",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BroadcastOnChainTransactionRequest"
}
}
}
},
"description": "Broadcast a raw transaction hex string or a finalized PSBT for the specified wallet.",
"operationId": "StoreOnChainWallets_BroadcastOnChainTransaction",
"responses": {
"200": {
"description": "broadcasted 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"
},
"422": {
"description": "The PSBT is not finalized or the transaction payload is invalid."
},
"503": {
"description": "This network only supports read-only features or hotwallets are disabled."
}
},
"security": [
{
"API_Key": [
"btcpay.store.canbroadcasttransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/{transactionId}": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet transaction",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"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.canviewwallet"
],
"Basic": []
}
]
},
"patch": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Patch store on-chain wallet transaction info",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"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.canmanagewallettransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/utxos": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet UTXOS",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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.canviewwallet"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/generate": {
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Generate store on-chain wallet",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"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": {
"allOf": [
{
"$ref": "#/components/schemas/GenericPaymentMethodData"
},
{
"type": "object",
"properties": {
"mnemonic": {
"$ref": "#/components/schemas/Mnemonic"
},
"config": {
"$ref": "#/components/schemas/OnChainPaymentMethodBaseData"
}
}
}
]
}
}
}
},
"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/{paymentMethodId}/wallet/preview": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Preview store on-chain payment method addresses",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"name": "paymentMethodId",
"in": "path",
"required": true,
"description": "The payment method id of the payment method to update",
"schema": {
"type": "string"
},
"example": "BTC-CHAIN"
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "From which index to fetch the addresses",
"schema": {
"type": "number"
}
},
{
"name": "count",
"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.canviewwallet"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Preview proposed store on-chain payment method addresses",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "From which index to fetch the addresses",
"schema": {
"type": "number"
}
},
{
"name": "count",
"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.canmanagewalletsettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet objects",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "type",
"in": "query",
"required": false,
"description": "The type of object to fetch",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "ids",
"in": "query",
"required": false,
"description": "The ids of objects to fetch, if used, type should be specified",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"example": "03abcde..."
},
{
"name": "includeNeighbourData",
"in": "query",
"required": false,
"description": "Whether or not you should include neighbour's node data in the result (ie, `links.objectData`)",
"schema": {
"type": "boolean",
"default": true
}
}
],
"description": "View wallet objects",
"operationId": "StoreOnChainWallets_GetOnChainWalletObjects",
"responses": {
"200": {
"description": "Selected objects and their links",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OnChainWalletObjectData"
}
}
}
}
},
"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.canviewwallet"
],
"Basic": []
}
]
},
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Add/Update store on-chain wallet objects",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
}
],
"description": "Add/Update wallet objects",
"operationId": "StoreOnChainWallets_AddOrUpdateOnChainWalletObjects",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnChainWalletObjectData"
}
}
}
},
"responses": {
"200": {
"description": "Wallet object's data and its links",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnChainWalletObjectData"
}
}
}
},
"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.canmanagewallettransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}": {
"get": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Get store on-chain wallet object",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "objectType",
"in": "path",
"required": true,
"description": "The object type to fetch",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "objectId",
"in": "path",
"required": true,
"description": "The object id to fetch",
"schema": {
"type": "string"
},
"example": "abc392..."
},
{
"name": "includeNeighbourData",
"in": "query",
"required": false,
"description": "Whether or not you should include neighbour's node data in the result (ie, `links.objectData`)",
"schema": {
"type": "boolean",
"default": true
}
}
],
"description": "View wallet object",
"operationId": "StoreOnChainWallets_GetOnChainWalletObject",
"responses": {
"200": {
"description": "Wallet object's data and its links",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnChainWalletObjectData"
}
}
}
},
"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.canviewwallet"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Remove store on-chain wallet objects",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "objectType",
"in": "path",
"required": true,
"description": "The object type to fetch",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "objectId",
"in": "path",
"required": true,
"description": "The object id to fetch",
"schema": {
"type": "string"
},
"example": "abc392..."
}
],
"description": "Remove wallet object",
"operationId": "StoreOnChainWallets_RemoveOnChainWalletObject",
"responses": {
"200": {
"description": "successful removal of filtered object"
},
"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.canmanagewallettransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links": {
"post": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Add/Update store on-chain wallet object link",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "objectType",
"in": "path",
"required": true,
"description": "The object type to fetch",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "objectId",
"in": "path",
"required": true,
"description": "The object id to fetch",
"schema": {
"type": "string"
},
"example": "abc392..."
}
],
"description": "Add/Update wallet object link",
"operationId": "StoreOnChainWallets_AddOrUpdateOnChainWalletLink",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddOnChainWalletObjectLinkRequest"
}
}
}
},
"responses": {
"200": {
"description": "action completed"
},
"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.canmanagewallettransactions"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links/{linkType}/{linkId}": {
"delete": {
"tags": [
"Store Wallet (On Chain)"
],
"summary": "Remove store on-chain wallet object links",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/PaymentMethodId"
},
{
"name": "objectType",
"in": "path",
"required": true,
"description": "The object type to fetch",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "objectId",
"in": "path",
"required": true,
"description": "The object id to fetch",
"schema": {
"type": "string"
},
"example": "abc392..."
},
{
"name": "linkType",
"in": "path",
"required": true,
"description": "The object type of the linked neighbour",
"schema": {
"type": "string"
},
"example": "tx"
},
{
"name": "linkId",
"in": "path",
"required": true,
"description": "The object id of the linked neighbour",
"schema": {
"type": "string"
},
"example": "abc392..."
}
],
"description": "Remove wallet object link",
"operationId": "StoreOnChainWallets_RemoveOnChainWalletLink",
"responses": {
"200": {
"description": "successful removal of filtered object link"
},
"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.canmanagewallettransactions"
],
"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"
}
}
}
},
"401": {
"description": "Missing authorization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"security": [
{
"API_Key": [
"btcpay.store.canviewstoresettings"
],
"Basic": []
}
]
},
"post": {
"operationId": "Stores_CreateStore",
"tags": [
"Stores"
],
"summary": "Create a new store",
"description": "Create a new store (default values can be different if the server settings use a default store template)",
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "Update the specified store (default values can be different if the server settings use a default store template)",
"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": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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/stores/{storeId}/logo": {
"post": {
"tags": [
"Stores"
],
"summary": "Uploads a logo for the store",
"description": "Uploads a logo for the store",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"file": {
"type": "string",
"description": "The logo",
"format": "binary"
}
}
}
}
}
},
"operationId": "Stores_UploadStoreLogo",
"responses": {
"200": {
"description": "Uploads a logo for the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationUserData"
}
}
}
},
"404": {
"description": "The store could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Stores"
],
"summary": "Deletes the store logo",
"description": "Delete the store's logo",
"operationId": "Stores_DeleteStoreLogo",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"responses": {
"200": {
"description": "Store logo deleted successfuly"
},
"404": {
"description": "The store could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/roles": {
"get": {
"tags": [
"Stores"
],
"summary": "Get store's roles",
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"description": "View information about the specified store's roles",
"operationId": "Stores_GetStoreRoles",
"responses": {
"200": {
"description": "The user roles available for this store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleData"
}
}
}
},
"403": {
"description": "If you are authenticated but forbidden to get the store's roles"
},
"404": {
"description": "Store not found"
}
},
"security": [
{
"API_Key": [
"btcpay.store.canmodifystoresettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}": {
"get": {
"summary": "Get an offering",
"description": "Returns a specific offering for a store.",
"operationId": "GetOffering",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canviewofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
}
],
"responses": {
"200": {
"description": "Offering retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingModel"
}
}
}
},
"404": {
"description": "Offering not found."
}
}
},
"put": {
"summary": "Update an offering",
"description": "Updates an existing offering for the specified store.",
"operationId": "UpdateOffering",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifyofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
}
],
"requestBody": {
"required": true,
"description": "Offering data to update.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOfferingModel"
}
}
}
},
"responses": {
"200": {
"description": "Offering updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingModel"
}
}
}
},
"400": {
"description": "Invalid request data."
},
"404": {
"description": "Offering not found."
}
}
}
},
"/api/v1/stores/{storeId}/offerings": {
"get": {
"summary": "List offerings for a store",
"description": "Retrieves all offerings associated with the specified store.",
"operationId": "GetOfferings",
"tags": [
"Subscriptions"
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"security": [
{
"API_Key": [
"btcpay.store.canviewofferings"
],
"Basic": []
}
],
"responses": {
"200": {
"description": "List of offerings retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OfferingModel"
}
}
}
}
}
}
},
"post": {
"summary": "Create an offering",
"description": "Creates a new offering for the specified store.",
"operationId": "CreateOffering",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifyofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"requestBody": {
"required": true,
"description": "Offering data to create.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOfferingModel"
}
}
}
},
"responses": {
"201": {
"description": "Offering created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/plans": {
"post": {
"summary": "Create an offering plan",
"description": "Creates a new plan for a specific offering.",
"operationId": "CreateOfferingPlan",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifyofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
}
],
"requestBody": {
"required": true,
"description": "Plan data to create for the offering.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePlanRequest"
}
}
}
},
"responses": {
"201": {
"description": "Plan created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingPlanModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/plans/{planId}": {
"get": {
"summary": "Get an offering plan",
"description": "Returns a specific plan for a given offering.",
"operationId": "GetOfferingPlan",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canviewofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/PlanId"
}
],
"responses": {
"200": {
"description": "Plan retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingPlanModel"
}
}
}
},
"404": {
"description": "Plan not found."
}
}
},
"put": {
"summary": "Update an offering plan",
"description": "Updates an existing plan for a specific offering.",
"operationId": "UpdateOfferingPlan",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmodifyofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/PlanId"
}
],
"requestBody": {
"required": true,
"description": "Plan data to update for the offering.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePlanRequest"
}
}
}
},
"responses": {
"200": {
"description": "Plan updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfferingPlanModel"
}
}
}
},
"400": {
"description": "Invalid request data."
},
"404": {
"description": "Plan not found."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}": {
"get": {
"summary": "Get a subscriber",
"description": "Retrieves a subscriber for a specific offering by customer selector.",
"operationId": "GetSubscriber",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canviewofferings"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
}
],
"responses": {
"200": {
"description": "Subscriber retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriberModel"
}
}
}
},
"404": {
"description": "Subscriber not found."
}
}
},
"delete": {
"summary": "Delete a subscriber",
"description": "Deletes a subscriber for a specific offering by customer selector.",
"operationId": "DeleteSubscriber",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
}
],
"responses": {
"204": {
"description": "Subscriber deleted successfully."
},
"404": {
"description": "Subscriber not found."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/credits/{currency}": {
"get": {
"summary": "Get subscriber credit balance",
"description": "Retrieves the credit balance for a subscriber in the specified currency.",
"operationId": "GetCredit",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
},
{
"$ref": "#/components/parameters/Subscriptions/Currency"
}
],
"responses": {
"200": {
"description": "Credit retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreditModel"
}
}
}
},
"404": {
"description": "Credit record not found."
}
}
},
"post": {
"summary": "Update subscriber credit balance",
"description": "Adds credit or charges credit for a subscriber in a given currency.",
"operationId": "UpdateCredit",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.cancreditsubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
},
{
"$ref": "#/components/parameters/Subscriptions/Currency"
}
],
"requestBody": {
"required": true,
"description": "Details for modifying subscriber credit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCreditRequest"
}
}
}
},
"responses": {
"200": {
"description": "Credit updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreditModel"
}
}
}
},
"400": {
"description": "Error code: `overdraft`. The subscriber's balance would be overdrawn. Use `allowOverdraft` to allow this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/suspend": {
"post": {
"summary": "Suspend a subscriber",
"description": "Suspends a subscriber for the specified offering.",
"operationId": "SuspendSubscriber",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
}
],
"requestBody": {
"required": true,
"description": "Details about why the subscriber is being suspended.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuspendSubscriberRequest"
}
}
}
},
"responses": {
"200": {
"description": "Subscriber suspended successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriberModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/unsuspend": {
"post": {
"summary": "Unsuspend a subscriber",
"description": "Removes suspension from a subscriber for the specified offering.",
"operationId": "UnsuspendSubscriber",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
}
],
"responses": {
"200": {
"description": "Subscriber unsuspended successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriberModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/dates": {
"put": {
"summary": "Update subscriber dates",
"description": "Manually overrides the subscription start date and/or expiration date for a subscriber.\n\nOmitting a field leaves the corresponding date unchanged. An empty body `{}` is a no-op and returns the subscriber unchanged.\n\nWhen `expirationDate` is provided, the grace period end and reminder date are recalculated automatically from the plan settings.",
"operationId": "UpdateSubscriberDates",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
},
{
"$ref": "#/components/parameters/OfferingId"
},
{
"$ref": "#/components/parameters/CustomerSelector"
}
],
"requestBody": {
"required": true,
"description": "Dates to update. All fields are optional \u2014 omitting a field leaves it unchanged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSubscriberDatesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Subscriber dates updated (or unchanged if no fields were provided).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriberModel"
}
}
}
},
"400": {
"description": "Error code: `invalid-dates`. The expiration date must be after the start date.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Subscriber not found."
}
}
}
},
"/api/v1/plan-checkout/{checkoutId}": {
"get": {
"summary": "Get a plan checkout",
"description": "Retrieves the details of a plan checkout session.",
"operationId": "GetPlanCheckout",
"tags": [
"Subscriptions"
],
"parameters": [
{
"$ref": "#/components/parameters/PlanCheckoutId"
}
],
"responses": {
"200": {
"description": "Checkout retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanCheckoutModel"
}
}
}
},
"404": {
"description": "Checkout session not found."
}
}
},
"post": {
"summary": "Proceed with a plan checkout",
"description": "Continues a plan checkout session.\n\n**Behavior:**\n- If payment is required, the checkout assigns a BTCPay Server invoice and `invoiceId` will be set.\n- If no payment is required (for example, the subscriber already has enough credit or no credit purchase is needed), the plan will start immediately and `planStarted` will be `true`.",
"operationId": "ProceedPlanCheckout",
"tags": [
"Subscriptions"
],
"parameters": [
{
"$ref": "#/components/parameters/PlanCheckoutId"
},
{
"name": "email",
"in": "query",
"required": false,
"description": "Optional customer email used when proceeding with the checkout.",
"schema": {
"type": "string"
},
"example": "user@example.com"
}
],
"responses": {
"200": {
"description": "Checkout processed successfully.\n\n**Behavior:**\n- If payment is required, `invoiceId` contains the BTCPay Server invoice the user must pay.\n- If no payment is required, the subscription is activated immediately and `planStarted` will be `true`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanCheckoutModel"
}
}
}
},
"400": {
"description": "Error code: `invoice-creation-error`. Error during the creation of the invoice.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Checkout session not found."
}
}
}
},
"/api/v1/plan-checkout": {
"post": {
"summary": "Create a plan checkout session",
"description": "Creates a checkout session for purchasing or activating a plan.",
"operationId": "CreatePlanCheckout",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"requestBody": {
"required": true,
"description": "Details required to create a checkout session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePlanCheckoutRequest"
}
}
}
},
"responses": {
"200": {
"description": "Checkout created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlanCheckoutModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/subscriber-portal": {
"post": {
"summary": "Create a subscriber portal session",
"description": "Creates a portal session that allows a subscriber to manage their subscriptions, view billing details, or update account information.",
"operationId": "CreatePortalSession",
"tags": [
"Subscriptions"
],
"security": [
{
"API_Key": [
"btcpay.store.canmanagesubscribers"
],
"Basic": []
}
],
"requestBody": {
"required": true,
"description": "Information required to create a subscriber portal session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePortalSessionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Portal session created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PortalSessionModel"
}
}
}
},
"400": {
"description": "Invalid request data."
}
}
}
},
"/api/v1/subscriber-portal/{portalSessionId}": {
"get": {
"summary": "Get a subscriber portal session",
"description": "Retrieves the details of an existing subscriber portal session.",
"operationId": "GetPortalSession",
"tags": [
"Subscriptions"
],
"parameters": [
{
"$ref": "#/components/parameters/PortalSessionId"
}
],
"responses": {
"200": {
"description": "Portal session retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PortalSessionModel"
}
}
}
},
"404": {
"description": "Portal session not found."
}
}
}
},
"/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": []
}
]
},
"put": {
"tags": [
"Users"
],
"summary": "Update current user information",
"description": "Update the current user",
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"email": {
"type": "string",
"description": "The email of the user",
"nullable": true
},
"name": {
"type": "string",
"description": "The name of the user",
"nullable": true
},
"imageUrl": {
"type": "string",
"description": "The profile picture URL of the user",
"nullable": true
},
"currentPassword": {
"type": "string",
"description": "The current password of the user",
"nullable": true
},
"newPassword": {
"type": "string",
"description": "The new password of the user",
"nullable": true
}
}
}
}
},
"required": true,
"x-position": 1
},
"operationId": "Users_UpdateCurrentUser",
"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.canmodifyprofile"
],
"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/me/picture": {
"post": {
"tags": [
"Users"
],
"summary": "Uploads a profile picture for the current user",
"description": "Uploads a profile picture for the current user",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"file": {
"type": "string",
"description": "The profile picture",
"format": "binary"
}
}
}
}
}
},
"operationId": "Users_UploadCurrentUserProfilePicture",
"responses": {
"200": {
"description": "Uploads a profile picture for the current user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationUserData"
}
}
}
},
"404": {
"description": "The user could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.user.canmodifyprofile"
],
"Basic": []
}
]
},
"delete": {
"tags": [
"Users"
],
"summary": "Deletes user profile picture",
"description": "Deletes the user profile picture",
"operationId": "Users_DeleteCurrentUserProfilePicture",
"responses": {
"200": {
"description": "Profile picture deleted successfully"
},
"404": {
"description": "The user could not be found"
}
},
"security": [
{
"API_Key": [
"btcpay.user.canmodifyprofile"
],
"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* User registrations are not disabled in the server's policies.\n\nIf the first administrator is created by this call, user registrations 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
},
"name": {
"type": "string",
"description": "The name of the new user",
"nullable": true
},
"imageUrl": {
"type": "string",
"description": "The profile picture URL of the new user",
"nullable": true
},
"password": {
"type": "string",
"description": "The password of the new user (if no password is set, an email will be sent to the user requiring him to set the password)",
"nullable": true
},
"isAdministrator": {
"type": "boolean",
"description": "Make this user administrator (only if you have the `unrestricted` permission of a server administrator)",
"nullable": true,
"default": false
},
"sendInvitationEmail": {
"type": "boolean",
"description": "Flag to specify if an email invitation should be sent to the user",
"nullable": true,
"default": true
}
}
}
}
},
"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 user 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": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"responses": {
"200": {
"description": "User found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationUserData"
}
}
}
},
"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": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"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": {
"post": {
"operationId": "Users_ToggleUserLock",
"tags": [
"Users"
],
"summary": "Toggle user lock out",
"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": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"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 locking the user"
},
"403": {
"description": "Authorized but forbidden to lock 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/users/{idOrEmail}/approve": {
"post": {
"operationId": "Users_ToggleUserApproval",
"tags": [
"Users"
],
"summary": "Toggle user approval",
"description": "Approve or unapprove a user.\n\nMust be an admin to perform this operation.\n\nAttempting to (un)approve a user for which this requirement does not exist will not succeed.",
"parameters": [
{
"$ref": "#/components/parameters/UserIdOrEmail"
}
],
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveUserRequest"
}
}
}
},
"responses": {
"200": {
"description": "User has been successfully toggled"
},
"401": {
"description": "Missing authorization for approving the user"
},
"403": {
"description": "Authorized but forbidden to approve the user. Can happen if you attempt to set the status of a user that does not have the approval requirement."
},
"404": {
"description": "User with provided ID was not found"
}
},
"security": [
{
"API_Key": [
"btcpay.user.canmodifyserversettings"
],
"Basic": []
}
]
}
},
"/api/v1/stores/{storeId}/webhooks": {
"parameters": [
{
"$ref": "#/components/parameters/StoreId"
}
],
"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/WebhookDataCreateResult"
}
}
}
},
"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/webhooks/{webhookId}": {
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
}
],
"get": {
"tags": [
"Webhooks"
],
"summary": "Get a webhook",
"description": "View webhook",
"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/webhooks/{webhookId}/deliveries": {
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
}
],
"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/webhooks/{webhookId}/deliveries/{deliveryId}": {
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/DeliveryId"
}
],
"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 exist."
}
},
"security": [
{
"API_Key": [
"btcpay.store.webhooks.canmodifywebhooks"
],
"Basic": []
}
]
}
},
"/api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/request": {
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/DeliveryId"
}
],
"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 exist."
},
"409": {
"description": "`webhookdelivery-pruned`: This webhook delivery has been pruned, so it can't be redelivered."
}
},
"security": [
{
"API_Key": [
"btcpay.store.webhooks.canmodifywebhooks"
],
"Basic": []
}
]
}
},
"/api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver": {
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/DeliveryId"
}
],
"post": {
"operationId": "Webhooks_RedeliverWebhookDelivery",
"tags": [
"Webhooks"
],
"summary": "Redeliver the delivery",
"description": "Redeliver the delivery",
"responses": {
"200": {
"description": "The new delivery id being broadcasted. (Broadcast happens asynchronously with this call)",
"content": {
"application/json": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The delivery does not exist."
},
"409": {
"description": "`webhookdelivery-pruned`: This webhook delivery has been pruned, so it can't be redelivered."
}
},
"security": [
{
"API_Key": [
"btcpay.store.webhooks.canmodifywebhooks"
],
"Basic": []
}
]
}
}
},
"tags": [
{
"name": "API Keys",
"description": "API Key operations"
},
{
"name": "Apps",
"description": "App operations"
},
{
"name": "Crowdfund",
"description": "Crowdfund operations"
},
{
"name": "Point of Sale",
"description": "Point of Sale operations"
},
{
"name": "Authorization",
"description": "Authorization operations"
},
{
"name": "Files",
"description": "File operations"
},
{
"name": "Health",
"description": "Health operations"
},
{
"name": "Invoices",
"description": "Invoice operations"
},
{
"name": "Lightning (Internal Node)",
"description": "Lightning (Internal Node) operations"
},
{
"name": "Lightning (Store)",
"description": "Lightning (Store) operations"
},
{
"name": "Miscelleneous",
"description": "Miscelleneous operations"
},
{
"name": "Notifications (Current User)",
"description": "Notifications operations"
},
{
"name": "Payment Requests",
"description": "Payment Requests operations"
},
{
"name": "Stores (Payout Processors)",
"description": "Stores (Payout Processors) operations"
},
{
"name": "Payout Processors",
"description": "Payout Processors operations"
},
{
"name": "Pull payments (Management)",
"description": "Pull payments (Management) operations"
},
{
"name": "Pull payments (Public)",
"description": "Pull payments (Public) operations"
},
{
"name": "Pull payments payout (Public)",
"description": "Pull payments payout (Public) operations"
},
{
"name": "Stores (Payouts)",
"description": "Store pull payment payout operations"
},
{
"name": "ServerEmail",
"description": "Server Email Settings operations"
},
{
"name": "ServerInfo",
"description": "Server Info operations"
},
{
"name": "Stores (Email)",
"description": "Store Emails operations"
},
{
"name": "Lightning address",
"description": "Lightning address configuration"
},
{
"name": "Store (Payment Methods)",
"description": "Store Payment Methods operations"
},
{
"name": "Stores (Rates)",
"description": "Stores rate information and configuration"
},
{
"name": "Stores (Users)",
"description": "Store Users operations"
},
{
"name": "Store Wallet (On Chain)",
"description": "Store Wallet (On Chain) operations"
},
{
"name": "Stores",
"description": "Store operations"
},
{
"name": "Subscriptions",
"description": "Subscription operations"
},
{
"name": "Users",
"description": "User operations"
},
{
"name": "Webhooks",
"description": "Webhook operations"
}
]
}