> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to BTCPay Server

The BTCPay Server connector lets your AI agent act in each user's BTCPay Server account. Each user connects their own BTCPay Server API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

**Authentication:** API Key
**Categories:** Accounting & Finance
**Tools:** 60: 33 read, 21 write, 6 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=BTCPAY)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the BTCPay Server connection

   In **AgentKit > Connections**, create a BTCPay Server connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'btcpay'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize BTCPay Server:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'btcpay_current_user_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "btcpay"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize BTCPay Server:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="btcpay_current_user_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their BTCPay Server credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'btcpay_app_sales_get',
  toolInput: {
    app_id: '<app_id>',
  },
  connector: 'btcpay',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="btcpay_app_sales_get",
    tool_input={
        "app_id": "<app_id>",
    },
    connection_name="btcpay",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `btcpay_app_sales_get`

Get App Sales · Read-only

Get sales statistics for a Point of Sale or Crowdfund app over recent days.
Returns the total sales count and a per-day series.
Use it to report app activity.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `app_id` (`string`, required): App ID. Example: 3Ki9vC6eF2ZsEXbXV2tQWQ8d1Sp.
- `number_of_days` (`number`, optional): How many of the last days. Defaults to 7. Example: 7.

Example input: `{"app_id":"<app_id>"}`

### `btcpay_apps_list`

List Store Apps · Read-only

List the apps of a store (Point of Sale, Crowdfund and others).
Returns each app's id, name, type and creation time.
Use app_sales_get for an app's sales.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_current_user_get`

Get Current User · Read-only

Get the BTCPay user that owns the API key.
Returns the user's id, email, name, roles and creation date.
Use it to confirm which account the connection acts as.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `btcpay_invoice_get`

Get Invoice · Read-only

Get one invoice by ID.
Returns its status, additionalStatus, amount, currency, checkoutLink, metadata, checkout settings and timestamps.
Use invoice_payment_methods_get to see addresses, rates and received payments.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_payment_methods` (`boolean`, optional): Includes payment methods available to the response. Defaults to false. Example: false.

Example input: `{"invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_invoice_payment_methods_get`

Get Invoice Payment Methods · Read-only

Get the payment methods of an invoice.
Returns, per method, the destination address or BOLT11, payment link, rate, amount due, amount paid and the list of received payments.
Use it to check how and how much an invoice has been paid.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_sensitive` (`boolean`, optional): If true, additionalData might include sensitive data (such as xpub). Requires the permission btcpay.store.canmodifystoresettings. Defaults to false. Example: false.
- `only_accounted_payments` (`boolean`, optional): If default or true, only returns payments which are accounted (in Bitcoin, this mean not returning RBF'd or double spent payments). Example: true.

Example input: `{"invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_invoices_list`

List Invoices · Read-only

List a store's invoices, newest first, with optional filters by order ID, status, text and date range.
Returns each invoice's id, status, amount, currency, checkout link, metadata and timestamps.
Use invoice_get for one invoice and invoice_payment_methods_get for its payments.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `end_date` (`integer`, optional): End date of the period to retrieve invoices. Example: 1592312018.
- `include_payment_methods` (`boolean`, optional): Includes payment methods available to the response. Defaults to false. Example: false.
- `order_id` (`array`, optional): Array of OrderIds to fetch the invoices for. Example: ["order-1001"]
- `skip` (`integer`, optional): Number of records to skip. Example: 0.
- `start_date` (`integer`, optional): Start date of the period to retrieve invoices. Example: 1592312018.
- `status` (`string`, optional): Array of statuses of invoices to be fetched. Example: Settled. One of: `Expired`, `Invalid`, `New`, `Processing`, `Settled`.
- `take` (`integer`, optional): Number of records returned in response. Example: 10.
- `text_search` (`string`, optional): A term that can help locating specific invoices. Example: order-1001.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_lightning_balance_get`

Get Lightning Balance · Read-only

Get the balance of the store's Lightning node.
Returns on-chain and off-chain (channel) balances in millisatoshi.
Use lightning_info_get for node details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `crypto_code` (`string`, required): The cryptoCode of the lightning-node to query. Example: BTC.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"crypto_code":"<crypto_code>","store_id":"<store_id>"}`

### `btcpay_lightning_info_get`

Get Lightning Node Info · Read-only

Get information about the Lightning node connected to a store.
Returns the node URIs, block height, alias, color, version and channel counts.
Use lightning_balance_get for balances.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `crypto_code` (`string`, required): The cryptoCode of the lightning-node to query. Example: BTC.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"crypto_code":"<crypto_code>","store_id":"<store_id>"}`

### `btcpay_lightning_invoice_get`

Get Lightning Invoice · Read-only

Get one invoice from the store's Lightning node.
Returns its BOLT11, status, amount, amount received and payment time.
Use lightning_invoice_create to create one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `crypto_code` (`string`, required): The cryptoCode of the lightning-node to query. Example: BTC.
- `invoice_id` (`string`, required): The id of the lightning invoice. Example: e2c4d8a5b3f1.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"crypto_code":"<crypto_code>","invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_lightning_payments_list`

List Lightning Payments · Read-only

List outgoing payments made by the store's Lightning node.
Returns each payment's hash, status, amount, fee and creation time.
Set includePending=true to also see in-flight payments.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `crypto_code` (`string`, required): The cryptoCode of the lightning-node to query. Example: BTC.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_pending` (`boolean`, optional): Also include pending payments. Defaults to false. Example: false.
- `offset_index` (`number`, optional): The index of an invoice that will be used as the start of the list. Defaults to 0. Example: 0.

Example input: `{"crypto_code":"<crypto_code>","store_id":"<store_id>"}`

### `btcpay_notifications_list`

List Notifications · Read-only

List notifications for the API key's user, newest first, with paging.
Returns each notification's id, body, link, type, seen flag and creation time.
Use seen=false to show only unread notifications.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `seen` (`string`, optional): filter by seen notifications. Example: false.
- `skip` (`integer`, optional): Number of records to skip. Example: 0.
- `store_ids` (`array`, optional): Array of store ids to fetch the notifications for. Example: ["9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2"]
- `take` (`integer`, optional): Number of records returned in response. Example: 10.

Example input: `{}`

### `btcpay_payment_method_get`

Get Store Payment Method · Read-only

Get one payment method of a store, such as BTC-CHAIN.
Returns its id, enabled flag and (with includeConfig) its configuration, such as the derivation scheme.
Use payment_methods_list to see which methods exist.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_method_id` (`string`, required): The payment method id of the payment method to update. Example: BTC-CHAIN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_config` (`boolean`, optional): Fetch the config of the payment methods, if true, the permission btcpay.store.canmodifystoresettings is required. Example: true.

Example input: `{"payment_method_id":"<payment_method_id>","store_id":"<store_id>"}`

### `btcpay_payment_methods_list`

List Store Payment Methods · Read-only

List a store's configured payment methods, such as BTC-CHAIN and BTC-LN.
Returns each method's id, enabled flag and (with includeConfig) its configuration.
Use the payment method ID with the wallet tools.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_config` (`boolean`, optional): Fetch the config of the payment methods, if true, the permission btcpay.store.canmodifystoresettings is required. Example: true.
- `only_enabled` (`boolean`, optional): Fetch payment methods that are enabled/disabled only. Example: true.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_payment_request_get`

Get Payment Request · Read-only

Get one payment request by ID.
Returns its title, description, amount, currency, status, expiry date and settings.
Use payment_requests_list to find request IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_request_id` (`string`, required): The payment request to fetch. Example: 7hSrXAvKtyMqSVZzWJp4Zd.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"payment_request_id":"<payment_request_id>","store_id":"<store_id>"}`

### `btcpay_payment_requests_list`

List Payment Requests · Read-only

List a store's payment requests.
Returns each request's id, title, amount, currency, status, expiry date and creation time.
Use payment_request_get for one request.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_payout_get`

Get Payout · Read-only

Get one payout by ID.
Returns its amount, payout method, destination, state, proof and creation time.
Use payouts_list to find payout IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payout_id` (`string`, required): The ID of the payout. Example: 3gKtx5NnLbP8u6ycmCQbJq.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"payout_id":"<payout_id>","store_id":"<store_id>"}`

### `btcpay_payouts_list`

List Payouts · Read-only

List all payouts of a store.
Returns each payout's id, pull payment id, amount, payout method, destination, state and creation time.
Use payout_get for one payout.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_cancelled` (`boolean`, optional): Whether this should list cancelled payouts. Defaults to false. Example: false.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_pull_payment_get`

Get Pull Payment · Read-only

Get one pull payment by ID.
Returns its name, description, amount, currency, period, expiry, archived flag and viewLink.
Use pull_payment_payouts_list for the payouts claimed against it.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `pull_payment_id` (`string`, required): The ID of the pull payment. Example: 4X4fTqSZJ3Z7xYzVJhWYnZ.

Example input: `{"pull_payment_id":"<pull_payment_id>"}`

### `btcpay_pull_payment_payouts_list`

List Pull Payment Payouts · Read-only

List the payouts claimed against a pull payment.
Returns each payout's id, amount, payout method, destination, state and creation time.
Use payouts_list for every payout of a store.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `pull_payment_id` (`string`, required): The ID of the pull payment. Example: 4X4fTqSZJ3Z7xYzVJhWYnZ.
- `include_cancelled` (`boolean`, optional): Whether this should list cancelled payouts. Defaults to false. Example: false.

Example input: `{"pull_payment_id":"<pull_payment_id>"}`

### `btcpay_pull_payments_list`

List Pull Payments · Read-only

List a store's pull payments.
Returns each pull payment's id, name, amount, currency, period, archived flag and viewLink.
Use pull_payment_payouts_list to see claims against one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `include_archived` (`boolean`, optional): Whether this should list archived pull payments. Defaults to false. Example: false.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_rates_get`

Get Store Rates · Read-only

Get the store's current exchange rates for currency pairs.
Returns each pair's rate and any errors.
Pass currencyPair values like BTC_USD; omit to get the store's default pairs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `currency_pair` (`array`, optional): The currency pairs to fetch rates for. Example: ["BTC_USD"]

Example input: `{"store_id":"<store_id>"}`

### `btcpay_report_run`

Run Store Report · Read-only

Run one of the store's built-in reports (such as Invoices or Payments) over a date range.
Returns the report fields and data rows.
Use it to export sales and payment data.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `search` (`string`, required): A report search string containing a report view and date range. Example: view:Invoices,daterange:thismonth,timezone:UTC.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"search":"<search>","store_id":"<store_id>"}`

### `btcpay_server_info_get`

Get Server Info · Read-only

Get information about the BTCPay Server instance.
Returns the version, onion URL, supported payment methods and sync status of each network.
Use it to check the server is reachable and fully synced before creating invoices.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `btcpay_store_get`

Get Store · Read-only

Get one store by ID.
Returns the store's name, website, default currency, invoice expiration, speed policy and checkout settings.
Use stores_list to find the store ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_store_users_list`

List Store Users · Read-only

List the users of a store and their roles.
Returns each user's id, email, name and store role.
Use store_user_add to add or invite someone.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_stores_list`

List Stores · Read-only

List the stores the API key can access.
Returns each store's id, name, website, default currency and checkout settings.
Use the store id with every store-scoped tool.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `btcpay_wallet_address_get`

Get Wallet Address · Read-only

Get a receive address from a store's on-chain wallet, reusing the last unused one unless forceGenerate=true.
Returns the address, its key path and a payment link.
Use it to receive funds outside an invoice.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_method_id` (`string`, required): The payment method id of the payment method to update. Example: BTC-CHAIN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `force_generate` (`boolean`, optional): Whether to generate a new address for this request even if the previous one was not used. Defaults to false. Example: false.

Example input: `{"payment_method_id":"<payment_method_id>","store_id":"<store_id>"}`

### `btcpay_wallet_overview_get`

Get Wallet Overview · Read-only

Get the balance of a store's on-chain wallet.
Returns the confirmed, unconfirmed and total balance.
Use wallet_transactions_list for the transaction history.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_method_id` (`string`, required): The payment method id of the payment method to update. Example: BTC-CHAIN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"payment_method_id":"<payment_method_id>","store_id":"<store_id>"}`

### `btcpay_wallet_transaction_get`

Get Wallet Transaction · Read-only

Get one on-chain wallet transaction by ID.
Returns its amount, confirmations, block height, labels, comment and timestamp.
Use wallet_transactions_list to find transaction IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_method_id` (`string`, required): The payment method id of the payment method to update. Example: BTC-CHAIN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `transaction_id` (`string`, required): The transaction id to fetch. Example: 1b3a9e8f6d5c4b2a19e8f7d6c5b4a3928170f6e5d4c3b2a1908f7e6d5c4b3a29.

Example input: `{"payment_method_id":"<payment_method_id>","store_id":"<store_id>","transaction_id":"<transaction_id>"}`

### `btcpay_wallet_transactions_list`

List Wallet Transactions · Read-only

List a store's on-chain wallet transactions, with optional status and label filters.
Returns each transaction's id, amount, confirmations, labels, comment and timestamp.
Use wallet_transaction_get for one transaction.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `payment_method_id` (`string`, required): The payment method id of the payment method to update. Example: BTC-CHAIN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `label_filter` (`string`, optional): Transaction label to filter by. Example: invoice.
- `limit` (`integer`, optional): Maximum number of transactions to return. Example: 10.
- `skip` (`integer`, optional): Number of transactions to skip from the start. Example: 0.
- `status_filter` (`array`, optional): Statuses to filter the transactions with. Example: ["Confirmed"]

Example input: `{"payment_method_id":"<payment_method_id>","store_id":"<store_id>"}`

### `btcpay_webhook_deliveries_list`

List Webhook Deliveries · Read-only

List a webhook's latest deliveries, newest first.
Returns each delivery's id, timestamp, HTTP code, error message and status.
Use it to debug failed webhook calls.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `webhook_id` (`string`, required): The webhook id. Example: Gp4nTtCfAP1wiTTbH4oRrP.
- `count` (`integer`, optional): The number of latest deliveries to fetch. Example: 10.

Example input: `{"store_id":"<store_id>","webhook_id":"<webhook_id>"}`

### `btcpay_webhook_get`

Get Webhook · Read-only

Get one webhook by ID.
Returns its url, enabled flag, events and redelivery settings.
Use webhooks_list to find webhook IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `webhook_id` (`string`, required): The webhook id. Example: Gp4nTtCfAP1wiTTbH4oRrP.

Example input: `{"store_id":"<store_id>","webhook_id":"<webhook_id>"}`

### `btcpay_webhooks_list`

List Webhooks · Read-only

List a store's webhooks.
Returns each webhook's id, url, enabled flag, events and redelivery settings.
Use webhook_deliveries_list to check recent deliveries.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_invoice_archive`

Archive Invoice · Write

Archive an invoice so it no longer shows in the default invoice list.
Returns an empty response on success.
Use invoice_unarchive to restore it; the invoice is not deleted.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_invoice_create`

Create Invoice · Write

Create an invoice for a store. Leave amount empty for a top-up invoice the payer chooses the amount for.
Returns the invoice id, status, checkoutLink to send to the payer, amount, currency and expiration time.
Use invoice_get or webhooks to follow its status.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `additional_search_terms` (`array`, optional): Additional search term to help you find this invoice via text search. Example: ["march", "consulting"]
- `amount` (`string`, optional): 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.
- `checkout` (`object`, optional): Additional settings to customize the checkout flow. Example: {"speedPolicy": "MediumSpeed", "expirationMinutes": 30, "redirectURL": "https://example.com/thanks"}
- `currency` (`string`, optional): The currency of the invoice (if null, empty or unspecified, the currency will be the store's settings default)'. Example: USD.
- `metadata` (`object`, optional): 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 for more information. Example: {"orderId": "order-1001", "buyerEmail": "jane@example.com", "itemDesc": "Tea shop"}
- `receipt` (`object`, optional): Additional settings to customize the public receipt. Example: {"enabled": true, "showQR": true}

Example input: `{"store_id":"<store_id>"}`

### `btcpay_invoice_refund`

Refund Invoice · Write

Create a refund for a paid invoice. BTCPay creates a pull payment the customer claims from the returned link.
Returns the refund pull payment with its id and viewLink to share with the customer.
Choose refundVariant to decide which rate and amount are refunded.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `refund_variant` (`string`, required): * RateThen: Refund the crypto currency price, at the rate the invoice got paid. * CurrentRate: Refund the crypto currency price, at the current rate. *Fiat: Refund the invoice currency, at the rate when the refund will be sent. *OverpaidAmount: Refund the crypto currency amount that was overpaid. *Custom: Specify the amount, currency, and rate of the refund. (see customAmount and customCurrency). Example: CurrentRate. One of: `CurrentRate`, `Custom`, `Fiat`, `OverpaidAmount`, `RateThen`.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `custom_amount` (`string`, optional): The amount to refund if the refundVariant is Custom. Example: 5.00.
- `custom_currency` (`string`, optional): The currency to refund if the refundVariant is Custom. Example: USD.
- `description` (`string`, optional): Description of the pull payment. Example: Payment for March consulting work.
- `name` (`string`, optional): Name of the pull payment (Default: 'Refund' followed by the invoice id). Example: Acme Store.
- `payout_methods` (`array`, optional): The list of payout methods the refund can be claimed in. Available options can be queried from the StorePaymentMethods_GetStorePaymentMethods endpoint. If null, falls back to the deprecated single payout method, and if that is also null, to the default payout method of the original invoice. Example: ["BTC-CHAIN", "BTC-LN"]
- `subtract_percentage` (`string`, optional): Optional percentage by which to reduce the refund, e.g. as processing charge or to compensate for the mining fee. Example: 2.1.

Example input: `{"invoice_id":"<invoice_id>","refund_variant":"CurrentRate","store_id":"<store_id>"}`

### `btcpay_invoice_status_mark`

Mark Invoice Status · Write

Manually mark an invoice as Settled or Invalid, for example after confirming an off-chain payment.
Returns the updated invoice.
Only use this when the payment was verified outside BTCPay.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `status` (`string`, required): Mark an invoice as completed or invalid. Example: Settled. One of: `Settled`, `Invalid`.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"invoice_id":"<invoice_id>","status":"Settled","store_id":"<store_id>"}`

### `btcpay_invoice_unarchive`

Unarchive Invoice · Write

Restore an archived invoice to the default invoice list.
Returns the invoice.
Use after invoice_archive.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_invoice_update`

Update Invoice Metadata · Write

Replace an invoice's metadata (order ID, buyer details, item description and any custom fields).
Returns the updated invoice.
Only metadata can change; amount and currency are fixed once the invoice exists.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): The invoice ID. Example: HMprBnL9BTXWuPvpoKBS6e.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `metadata` (`object`, optional): 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 for more information. Example: {"orderId": "order-1001", "buyerEmail": "jane@example.com", "itemDesc": "Tea shop"}

Example input: `{"invoice_id":"<invoice_id>","store_id":"<store_id>"}`

### `btcpay_lightning_invoice_create`

Create Lightning Invoice · Write

Create a BOLT11 invoice directly on the store's Lightning node.
Returns the invoice id, BOLT11 string, amount, status and expiry.
Use invoice_create instead for a full BTCPay checkout page.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): Amount wrapped in a string, represented in a millisatoshi string. (1000 millisatoshi = 1 satoshi). Example: 10.00.
- `crypto_code` (`string`, required): The cryptoCode of the lightning-node to query. Example: BTC.
- `expiry` (`number`, required): Expiration time in seconds. Example: 90.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `description` (`string`, optional): Description of the invoice in the BOLT11. Example: Payment for March consulting work.
- `description_hash_only` (`boolean`, optional): 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. Example: false.
- `private_route_hints` (`boolean`, optional): True if the invoice should include private route hints. Defaults to false. Example: false.

Example input: `{"amount":"<amount>","crypto_code":"<crypto_code>","expiry":90,"store_id":"<store_id>"}`

### `btcpay_payment_request_create`

Create Payment Request · Write

Create a payment request: a reusable page where a customer can pay an amount, in one or several payments.
Returns the request's id, status and settings. Its public page is https://<your BTCPay host>/payment-requests/<id>.
Use payment_request_pay to create an invoice for it directly.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): The amount of the payment request. Example: 10.00.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `allow_custom_payment_amounts` (`boolean`, optional): Whether to allow users to create invoices that partially pay the payment request. Example: true.
- `currency` (`string`, optional): The currency of the payment request. If empty, the store's default currency code will be used. Example: USD.
- `description` (`string`, optional): The description of the payment request. Example: Payment for March consulting work.
- `email` (`string`, optional): The email used in invoices generated by the payment request. Example: jane@example.com.
- `expiry_date` (`integer`, optional): The expiry date of the payment request. Example: 1592312018.
- `form_id` (`string`, optional): Form ID to request customer data. Example: Email.
- `form_response` (`object`, optional): Form data response. Example: {"buyerEmail": "jane@example.com"}
- `reference_id` (`string`, optional): An optional user-defined identifier for this payment request. Example: INV-123493.
- `title` (`string`, optional): The title of the payment request. Example: Consulting - March.

Example input: `{"amount":"<amount>","store_id":"<store_id>"}`

### `btcpay_payment_request_pay`

Create Invoice for Payment Request · Write

Create an invoice for a payment request, or reuse its open invoice. Leave amount empty to request the remaining due.
Returns the invoice with its id and checkoutLink.
Use invoice_get to follow the invoice's status.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `payment_request_id` (`string`, required): The payment request to create. Example: 7hSrXAvKtyMqSVZzWJp4Zd.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `allow_pending_invoice_reuse` (`boolean`, optional): If true, this endpoint will not necessarily create a new invoice, and instead attempt to give back a pending one for this payment request. Defaults to false. Example: false.
- `amount` (`string`, optional): 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.'. Example: 0.1.

Example input: `{"payment_request_id":"<payment_request_id>","store_id":"<store_id>"}`

### `btcpay_payment_request_update`

Update Payment Request · Write

Update a payment request's title, amount, currency, expiry and other settings.
Returns the updated payment request.
Pass amount again, as BTCPay requires it on update.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount` (`string`, required): The amount of the payment request. Example: 10.00.
- `payment_request_id` (`string`, required): The payment request to update. Example: 7hSrXAvKtyMqSVZzWJp4Zd.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `allow_custom_payment_amounts` (`boolean`, optional): Whether to allow users to create invoices that partially pay the payment request. Example: true.
- `currency` (`string`, optional): The currency of the payment request. If empty, the store's default currency code will be used. Example: USD.
- `description` (`string`, optional): The description of the payment request. Example: Payment for March consulting work.
- `email` (`string`, optional): The email used in invoices generated by the payment request. Example: jane@example.com.
- `expiry_date` (`integer`, optional): The expiry date of the payment request. Example: 1592312018.
- `form_id` (`string`, optional): Form ID to request customer data. Example: Email.
- `form_response` (`object`, optional): Form data response. Example: {"buyerEmail": "jane@example.com"}
- `reference_id` (`string`, optional): An optional user-defined identifier for this payment request. Example: INV-123493.
- `title` (`string`, optional): The title of the payment request. Example: Consulting - March.

Example input: `{"amount":"<amount>","payment_request_id":"<payment_request_id>","store_id":"<store_id>"}`

### `btcpay_payout_approve`

Approve Payout · Write

Approve a payout that is awaiting approval so it can be paid, locking the amount at the given rate rule.
Returns the approved payout.
Requires the revision number from payout_get.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `payout_id` (`string`, required): The ID of the payout. Example: 3gKtx5NnLbP8u6ycmCQbJq.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `rate_rule` (`string`, optional): 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). Example: kraken(BTC_USD)
- `revision` (`integer`, optional): The revision number of the payout being modified. Example: 1.

Example input: `{"payout_id":"<payout_id>","store_id":"<store_id>"}`

### `btcpay_payout_create`

Create Payout · Write

Create a payout from the store to a destination address or Lightning invoice, optionally against a pull payment.
Returns the payout with its id and state (AwaitingApproval unless approved=true).
Use payout_approve to approve it later.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `destination` (`string`, required): The destination of the payout (can be an address or a BIP21 url). Example: 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2.
- `payout_method_id` (`string`, required): Payout method IDs. Available payment method IDs for Bitcoin are: - "BTC-CHAIN": Onchain -"BTC-LN": Lightning. Example: BTC-LN.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `amount` (`string`, optional): The amount of the payout in the currency of the pull payment (eg. USD). Example: 10399.18.
- `approved` (`boolean`, optional): Whether to approve this payout automatically upon creation. Example: true.
- `metadata` (`object`, optional): Additional metadata to store with the payout. Example: {"orderId": "order-1001", "buyerEmail": "jane@example.com", "itemDesc": "Tea shop"}
- `pull_payment_id` (`string`, optional): The pull payment to create this for. Optional. Example: 4X4fTqSZJ3Z7xYzVJhWYnZ.

Example input: `{"destination":"<destination>","payout_method_id":"<payout_method_id>","store_id":"<store_id>"}`

### `btcpay_payout_mark`

Mark Payout State · Write

Set a payout's state, for example Completed after paying it outside BTCPay, with optional proof of payment.
Returns an empty response on success.
Completed and Cancelled are final states.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `payout_id` (`string`, required): The ID of the payout. Example: 3gKtx5NnLbP8u6ycmCQbJq.
- `state` (`string`, required): The state of the payout (AwaitingApproval, AwaitingPayment, InProgress, Completed, Cancelled). Example: AwaitingPayment. One of: `AwaitingApproval`, `AwaitingPayment`, `Cancelled`, `Completed`, `InProgress`.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `payment_proof` (`object`, optional): 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. Example: {"proofType": "PayoutTransactionOnChainBlob", "transactionId": "a1b2c3"}

Example input: `{"payout_id":"<payout_id>","state":"AwaitingApproval","store_id":"<store_id>"}`

### `btcpay_pos_app_create`

Create Point of Sale App · Write

Create a Point of Sale app for a store.
Returns the app with its id and settings.
Pass items as a JSON string in template to define the products for sale.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `app_name` (`string`, required): Name given to the app when it was created. Example: my test app.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `app_type` (`string`, optional): Type of the app which was created. Example: PointOfSale.
- `archived` (`boolean`, optional): If true, the app does not appear in the apps list by default. Example: false.
- `created` (`integer`, optional): UNIX timestamp for when the app was created. Example: 1651554744.
- `currency` (`string`, optional): Currency used for the app. Example: BTC.
- `custom_amount_pay_button_text` (`string`, optional): Payment button text which appears for items which allow user to input a custom amount. Example: Pay.
- `custom_tip_percentages` (`array`, optional): Array of predefined tip percentage amounts. Defaults to [15, 18, 20]. Example: [15, 18, 20]
- `default_view` (`string`, optional): App view type (e.g., static, cart, etc...). Example: Cart. One of: `Static`, `Cart`, `Light`, `Print`.
- `description` (`string`, optional): App description. Example: Payment for March consulting work.
- `enable_tips` (`boolean`, optional): Whether the option to enter a tip is shown. Defaults to false. Example: true.
- `fixed_amount_pay_button_text` (`string`, optional): Payment button text template for items with a set price. Example: Buy for {0}
- `form_id` (`string`, optional): Form ID to request customer data. Example: Email.
- `html_lang` (`string`, optional): Used for SEO, the HTML Lang of the page. Example: en.
- `html_meta_tags` (`string`, optional): Used for SEO, the Meta tags of the page. Example: <meta name="description" content="Your description">.
- `id` (`string`, optional): Id of the app. Example: jane@example.com.
- `redirect_automatically` (`boolean`, optional): Whether user is redirected to specified redirect URL automatically after the invoice is paid. Example: true.
- `redirect_url` (`string`, optional): URL user is redirected to once invoice is paid. Example: https://shop.example.com/thanks.
- `show_categories` (`boolean`, optional): Display the list of categories. Defaults to true. Example: false.
- `show_custom_amount` (`boolean`, optional): Whether the option to enter a custom amount is shown. Example: true.
- `show_discount` (`boolean`, optional): Whether the option to enter a discount is shown. Defaults to false. Example: false.
- `show_items` (`boolean`, optional): Display item selection for keypad. Defaults to false. Example: true.
- `show_search` (`boolean`, optional): Display the search bar. Defaults to true. Example: false.
- `template` (`string`, optional): JSON of item available in the app. Example: [{"id": "tea", "title": "Green tea", "price": "2.50"}]
- `tip_text` (`string`, optional): Prompt which appears next to the tip amount field if tipping is enabled. Example: Do you want to leave a tip?.
- `title` (`string`, optional): Display title of the app. Example: Consulting - March.

Example input: `{"app_name":"<app_name>","store_id":"<store_id>"}`

### `btcpay_pull_payment_create`

Create Pull Payment · Write

Create a pull payment, which lets a receiver claim payouts up to an amount (optionally every period).
Returns the pull payment with its id and viewLink to share with the receiver.
Use payouts_list or pull_payment_payouts_list to review the claims.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): The amount in currency of this pull payment as a decimal string. Example: 0.1.
- `currency` (`string`, required): The currency of the amount. Example: BTC.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `auto_approve_claims` (`boolean`, optional): Any payouts created for this pull payment will skip the approval phase upon creation. Defaults to false. Example: false.
- `bolt11_expiration` (`string`, optional): If lightning is activated, do not accept BOLT11 invoices with expiration less than … days. Defaults to 30. Example: 30.
- `description` (`string`, optional): The description of the pull payment. Example: Payment for March consulting work.
- `expires_at` (`integer`, optional): When this pull payment expires. Never expires if null or unspecified. Example: 1593129600.
- `name` (`string`, optional): The name of the pull payment. Example: Acme Store.
- `payout_methods` (`array`, optional): 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. Example: ["BTC-CHAIN", "BTC-LN"]
- `starts_at` (`integer`, optional): When this pull payment is effective. Already started if null or unspecified. Example: 1592312018.

Example input: `{"amount":"<amount>","currency":"<currency>","store_id":"<store_id>"}`

### `btcpay_store_create`

Create Store · Write

Create a new store.
Returns the created store with its id and settings.
After creating it, set up a wallet or Lightning node in BTCPay before invoices can be paid.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): The name of the store. Example: Acme Store.
- `additional_tracked_rates` (`array`, optional): Additional rates to track. The 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. Example: ["EUR", "JPY"]
- `allow_zero_amount_invoices` (`boolean`, optional): If true, fixed-amount invoices with an amount of 0 can be created. Defaults to false. Example: false.
- `anyone_can_create_invoice` (`boolean`, optional): If true, then no authentication is needed to create invoices on this store. Defaults to false. Example: false.
- `apply_brand_color_to_backend` (`boolean`, optional): Apply the brand color to the store's backend as well. Defaults to false. Example: false.
- `archived` (`boolean`, optional): If true, the store does not appear in the stores list by default. Example: false.
- `auto_detect_language` (`boolean`, optional): If true, the language on the checkout page will adapt to the language defined by the user's browser settings. Defaults to false. Example: false.
- `brand_color` (`string`, optional): The brand color of the store in HEX format. Example: #F7931A.
- `celebrate_payment` (`boolean`, optional): If true, payments on the checkout page will be celebrated with confetti (Checkout V2). Defaults to true. Example: true.
- `css_url` (`string`, optional): Absolute HTTP or HTTPS 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. Example: https://shop.example.com/custom.css.
- `default_currency` (`string`, optional): The default currency of the store. Example: USD.
- `default_lang` (`string`, optional): The default language to use in the checkout page. (The different translations available are listed here. Example: en.
- `default_payment_method` (`string`, optional): Payment method IDs. Available payment method IDs for Bitcoin are: - "BTC-CHAIN": Onchain -"BTC-LN": Lightning - "BTC-LNURL": LNURL. Example: BTC-CHAIN.
- `display_expiration_timer` (`number`, optional): 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. Defaults to 300. Maximum 2073600. Example: 300.
- `html_title` (`string`, optional): The HTML title of the checkout page (when you over the tab in your browser). Example: Acme Checkout.
- `invoice_expiration` (`number`, optional): The time after which an invoice is considered expired if not paid. The value will be rounded down to a minute. Defaults to 900. Maximum 2073600. Example: 900.
- `lazy_payment_methods` (`boolean`, optional): If true, payment methods are enabled individually upon user interaction in the invoice. Defaults to false. Example: false.
- `lightning_amount_in_satoshi` (`boolean`, optional): If true, lightning payment methods show amount in satoshi in the checkout page. Defaults to false. Example: false.
- `lightning_description_template` (`string`, optional): The BOLT11 description of the lightning invoice in the checkout. You can use placeholders '{StoreName}', '{ItemDescription}' and '{OrderId}'. Example: Paid to {StoreName} (Order ID: {OrderId})
- `lightning_private_route_hints` (`boolean`, optional): Should private route hints be included in the lightning payment of the checkout page. Defaults to false. Example: false.
- `logo_url` (`string`, optional): Absolute URL to a logo file or a reference to an uploaded file id with fileid:ID. Example: https://shop.example.com/logo.png.
- `monitoring_expiration` (`number`, optional): 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. Defaults to 86400. Maximum 2073600. Example: 3600.
- `network_fee_mode` (`string`, optional): Check whether network fee should be added to the invoice if on-chain payment is used. (More information). Example: Always. One of: `Always`, `MultiplePaymentsOnly`, `Never`.
- `on_chain_with_ln_invoice_fallback` (`boolean`, optional): Unify on-chain and lightning payment URL. Defaults to false. Example: false.
- `pay_join_enabled` (`boolean`, optional): If true, payjoin will be proposed in the checkout page if possible. (More information). Defaults to false. Example: false.
- `payment_method_criteria` (`array`, optional): The criteria required to activate specific payment methods. Example: [{"paymentMethodId": "BTC-LN", "currencyCode": "USD", "amount": "5.00", "above": false}]
- `payment_sound_url` (`string`, optional): Absolute URL to a sound file or a reference to an uploaded file id with fileid:ID. Example: https://shop.example.com/ding.mp3.
- `payment_tolerance` (`number`, optional): Consider an invoice fully paid, even if the payment is missing 'x' % of the full amount. Defaults to 0.0. Maximum 100.0. Example: 0.0.
- `play_sound_on_payment` (`boolean`, optional): If true, sounds on the checkout page will be enabled (Checkout V2). Defaults to false. Example: false.
- `receipt` (`object`, optional): Additional settings to customize the public receipt. Example: {"enabled": true, "showQR": true}
- `recommended_fee_block_target` (`integer`, optional): The fee rate recommendation in the checkout page for the on-chain payment to be confirmed after 'x' blocks. Defaults to 1. Example: 1.
- `redirect_automatically` (`boolean`, optional): After successful payment, should the checkout page redirect the user automatically to the redirect URL of the invoice? Defaults to false. Example: false.
- `refund_bolt11_expiration` (`number`, optional): The minimum expiry of BOLT11 invoices accepted for refunds by default. (in days). Maximum 3650. Example: 30.
- `show_pay_in_wallet_button` (`boolean`, optional): If true, the "Pay in wallet" button will be shown on the checkout page (Checkout V2). Defaults to true. Example: true.
- `show_recommended_fee` (`boolean`, optional): Show Recommended Fee. Defaults to true. Example: true.
- `show_store_header` (`boolean`, optional): If true, the store header will be shown on the checkout page (Checkout V2). Defaults to true. Example: true.
- `speed_policy` (`string`, optional): 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. "HighSpeed": 0 confirmations (1 confirmation if RBF enabled in transaction) "MediumSpeed": 1 confirmation "LowMediumSpeed": 2 confirmations "LowSpeed": 6 confirmations. Example: HighSpeed. One of: `HighSpeed`, `LowMediumSpeed`, `LowSpeed`, `MediumSpeed`.
- `support_url` (`string`, optional): 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. Example: https://shop.example.com/support.
- `website` (`string`, optional): The absolute HTTP or HTTPS URL of the store. Example: https://shop.example.com.

Example input: `{"name":"<name>"}`

### `btcpay_store_email_send`

Send Store Email · Write

Send a plain-text email using the store's SMTP settings.
Returns an empty response on success.
The store must have email settings configured in BTCPay.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`string`, required): Body of the email to send as plain text. Example: Thanks for your payment.
- `email` (`string`, required): Email of the recipient. Example: jane@example.com.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `subject` (`string`, required): Subject of the email. Example: Your receipt.

Example input: `{"body":"<body>","email":"<email>","store_id":"<store_id>","subject":"<subject>"}`

### `btcpay_store_update`

Update Store · Write

Update a store's settings. The update replaces the store's settings, so pass every value you want to keep, including name.
Returns the updated store.
Use store_get first to read the current values.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, required): The name of the store. Example: Acme Store.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `additional_tracked_rates` (`array`, optional): Additional rates to track. The 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. Example: ["EUR", "JPY"]
- `allow_zero_amount_invoices` (`boolean`, optional): If true, fixed-amount invoices with an amount of 0 can be created. Defaults to false. Example: false.
- `anyone_can_create_invoice` (`boolean`, optional): If true, then no authentication is needed to create invoices on this store. Defaults to false. Example: false.
- `apply_brand_color_to_backend` (`boolean`, optional): Apply the brand color to the store's backend as well. Defaults to false. Example: false.
- `archived` (`boolean`, optional): If true, the store does not appear in the stores list by default. Example: false.
- `auto_detect_language` (`boolean`, optional): If true, the language on the checkout page will adapt to the language defined by the user's browser settings. Defaults to false. Example: false.
- `brand_color` (`string`, optional): The brand color of the store in HEX format. Example: #F7931A.
- `celebrate_payment` (`boolean`, optional): If true, payments on the checkout page will be celebrated with confetti (Checkout V2). Defaults to true. Example: true.
- `css_url` (`string`, optional): Absolute HTTP or HTTPS 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. Example: https://shop.example.com/custom.css.
- `default_currency` (`string`, optional): The default currency of the store. Example: USD.
- `default_lang` (`string`, optional): The default language to use in the checkout page. (The different translations available are listed here. Example: en.
- `default_payment_method` (`string`, optional): Payment method IDs. Available payment method IDs for Bitcoin are: - "BTC-CHAIN": Onchain -"BTC-LN": Lightning - "BTC-LNURL": LNURL. Example: BTC-CHAIN.
- `display_expiration_timer` (`number`, optional): 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. Defaults to 300. Maximum 2073600. Example: 300.
- `html_title` (`string`, optional): The HTML title of the checkout page (when you over the tab in your browser). Example: Acme Checkout.
- `invoice_expiration` (`number`, optional): The time after which an invoice is considered expired if not paid. The value will be rounded down to a minute. Defaults to 900. Maximum 2073600. Example: 900.
- `lazy_payment_methods` (`boolean`, optional): If true, payment methods are enabled individually upon user interaction in the invoice. Defaults to false. Example: false.
- `lightning_amount_in_satoshi` (`boolean`, optional): If true, lightning payment methods show amount in satoshi in the checkout page. Defaults to false. Example: false.
- `lightning_description_template` (`string`, optional): The BOLT11 description of the lightning invoice in the checkout. You can use placeholders '{StoreName}', '{ItemDescription}' and '{OrderId}'. Example: Paid to {StoreName} (Order ID: {OrderId})
- `lightning_private_route_hints` (`boolean`, optional): Should private route hints be included in the lightning payment of the checkout page. Defaults to false. Example: false.
- `logo_url` (`string`, optional): Absolute URL to a logo file or a reference to an uploaded file id with fileid:ID. Example: https://shop.example.com/logo.png.
- `monitoring_expiration` (`number`, optional): 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. Defaults to 86400. Maximum 2073600. Example: 3600.
- `network_fee_mode` (`string`, optional): Check whether network fee should be added to the invoice if on-chain payment is used. (More information). Example: Always. One of: `Always`, `MultiplePaymentsOnly`, `Never`.
- `on_chain_with_ln_invoice_fallback` (`boolean`, optional): Unify on-chain and lightning payment URL. Defaults to false. Example: false.
- `pay_join_enabled` (`boolean`, optional): If true, payjoin will be proposed in the checkout page if possible. (More information). Defaults to false. Example: false.
- `payment_method_criteria` (`array`, optional): The criteria required to activate specific payment methods. Example: [{"paymentMethodId": "BTC-LN", "currencyCode": "USD", "amount": "5.00", "above": false}]
- `payment_sound_url` (`string`, optional): Absolute URL to a sound file or a reference to an uploaded file id with fileid:ID. Example: https://shop.example.com/ding.mp3.
- `payment_tolerance` (`number`, optional): Consider an invoice fully paid, even if the payment is missing 'x' % of the full amount. Defaults to 0.0. Maximum 100.0. Example: 0.0.
- `play_sound_on_payment` (`boolean`, optional): If true, sounds on the checkout page will be enabled (Checkout V2). Defaults to false. Example: false.
- `receipt` (`object`, optional): Additional settings to customize the public receipt. Example: {"enabled": true, "showQR": true}
- `recommended_fee_block_target` (`integer`, optional): The fee rate recommendation in the checkout page for the on-chain payment to be confirmed after 'x' blocks. Defaults to 1. Example: 1.
- `redirect_automatically` (`boolean`, optional): After successful payment, should the checkout page redirect the user automatically to the redirect URL of the invoice? Defaults to false. Example: false.
- `refund_bolt11_expiration` (`number`, optional): The minimum expiry of BOLT11 invoices accepted for refunds by default. (in days). Maximum 3650. Example: 30.
- `show_pay_in_wallet_button` (`boolean`, optional): If true, the "Pay in wallet" button will be shown on the checkout page (Checkout V2). Defaults to true. Example: true.
- `show_recommended_fee` (`boolean`, optional): Show Recommended Fee. Defaults to true. Example: true.
- `show_store_header` (`boolean`, optional): If true, the store header will be shown on the checkout page (Checkout V2). Defaults to true. Example: true.
- `speed_policy` (`string`, optional): 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. "HighSpeed": 0 confirmations (1 confirmation if RBF enabled in transaction) "MediumSpeed": 1 confirmation "LowMediumSpeed": 2 confirmations "LowSpeed": 6 confirmations. Example: HighSpeed. One of: `HighSpeed`, `LowMediumSpeed`, `LowSpeed`, `MediumSpeed`.
- `support_url` (`string`, optional): 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. Example: https://shop.example.com/support.
- `website` (`string`, optional): The absolute HTTP or HTTPS URL of the store. Example: https://shop.example.com.

Example input: `{"name":"<name>","store_id":"<store_id>"}`

### `btcpay_store_user_add`

Add Store User · Write

Add a user to a store with a role, or send them a store invitation.
Returns an empty response on success.
Use store_users_list to confirm the user's role.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): The id or email of the user. Example: jane@example.com.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `require_invitation` (`boolean`, optional): Whether to create a store invitation instead of adding the user directly. Defaults to true. Setting this to false requires server settings permission. Example: true.
- `store_role` (`string`, optional): The role of the user. Default roles are Owner, Manager, Employee and Guest. Example: Employee.

Example input: `{"id":"<id>","store_id":"<store_id>"}`

### `btcpay_webhook_create`

Create Webhook · Write

Create a webhook that sends store events (such as InvoiceSettled) to a URL.
Returns the webhook with its id and the secret used to sign deliveries.
Store the secret to verify the BTCPay-Sig header.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `url` (`string`, required): The endpoint where BTCPay Server will make the POST request with the webhook body. Example: https://shop.example.com.
- `authorized_events` (`object`, optional): Which event should be received by this endpoint. Example: {"everything": false, "specificEvents": ["InvoiceSettled", "InvoiceExpired"]}
- `automatic_redelivery` (`boolean`, optional): If true, BTCPay Server will retry to redeliver any failed delivery after 10 seconds, 1 minutes and up to 6 times after 10 minutes. Defaults to true. Example: true.
- `enabled` (`boolean`, optional): Whether this webhook is enabled or not. Defaults to true. Example: true.
- `secret` (`string`, optional): 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. If left out, null, or empty, the secret will be auto-generated. Example: my-webhook-secret.

Example input: `{"store_id":"<store_id>","url":"<url>"}`

### `btcpay_webhook_update`

Update Webhook · Write

Update a webhook's URL, events, enabled flag or secret.
Returns the updated webhook.
Pass url again, as the update replaces the webhook's settings.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `url` (`string`, required): The endpoint where BTCPay Server will make the POST request with the webhook body. Example: https://shop.example.com.
- `webhook_id` (`string`, required): The webhook id. Example: Gp4nTtCfAP1wiTTbH4oRrP.
- `authorized_events` (`object`, optional): Which event should be received by this endpoint. Example: {"everything": false, "specificEvents": ["InvoiceSettled", "InvoiceExpired"]}
- `automatic_redelivery` (`boolean`, optional): If true, BTCPay Server will retry to redeliver any failed delivery after 10 seconds, 1 minutes and up to 6 times after 10 minutes. Defaults to true. Example: true.
- `enabled` (`boolean`, optional): Whether this webhook is enabled or not. Defaults to true. Example: true.
- `secret` (`string`, optional): 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. If left out, null, or empty, the secret will not be changed. Example: my-webhook-secret.

Example input: `{"store_id":"<store_id>","url":"<url>","webhook_id":"<webhook_id>"}`

### `btcpay_payment_request_archive`

Archive Payment Request · Destructive

Archive a payment request so it can no longer be paid.
Returns an empty response on success.
Archived requests are hidden but not deleted.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `payment_request_id` (`string`, required): The payment request to remove. Example: 7hSrXAvKtyMqSVZzWJp4Zd.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"payment_request_id":"<payment_request_id>","store_id":"<store_id>"}`

### `btcpay_payout_cancel`

Cancel Payout · Destructive

Cancel a payout that has not been completed.
Returns an empty response on success.
Cancelled payouts are final.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `payout_id` (`string`, required): The ID of the payout. Example: 3gKtx5NnLbP8u6ycmCQbJq.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"payout_id":"<payout_id>","store_id":"<store_id>"}`

### `btcpay_pull_payment_archive`

Archive Pull Payment · Destructive

Archive a pull payment so no more payouts can be claimed, and cancel its payouts awaiting approval.
Returns an empty response on success.
This cannot be undone.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `pull_payment_id` (`string`, required): The ID of the pull payment. Example: 4X4fTqSZJ3Z7xYzVJhWYnZ.
- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"pull_payment_id":"<pull_payment_id>","store_id":"<store_id>"}`

### `btcpay_store_delete`

Delete Store · Destructive

Permanently delete a store and its settings.
Returns an empty response on success.
This cannot be undone; prefer setting archived=true with store_update to hide a store.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"store_id":"<store_id>"}`

### `btcpay_store_user_remove`

Remove Store User · Destructive

Remove a user from a store.
Returns an empty response on success.
The user keeps their BTCPay account; only their access to this store is removed.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id_or_email` (`string`, required): The user's id or email. Example: jane@example.com.
- `store_id` (`string`, required): The store ID. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.

Example input: `{"id_or_email":"<id_or_email>","store_id":"<store_id>"}`

### `btcpay_webhook_delete`

Delete Webhook · Destructive

Delete a webhook so it stops receiving events.
Returns an empty response on success.
To pause it instead, set enabled=false with webhook_update.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `store_id` (`string`, required): ID of the BTCPay store. Get it from List Stores. Example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2.
- `webhook_id` (`string`, required): The webhook id. Example: Gp4nTtCfAP1wiTTbH4oRrP.

Example input: `{"store_id":"<store_id>","webhook_id":"<webhook_id>"}`

## Related

Other Accounting & Finance connectors ([all 82](/agentkit/connectors/?category=accounting-finance)):

- [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools
- [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools
- [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
