BTCPay Server

BUSINESS · COMMERCE & FINANCE

Stores, invoices, payment requests, payouts, and apps on their own BTCPay server.

Connect BTCPay Server with Fabriq Developer

Your user pastes their BTCPay Server credential on a page Agentic Fabriq hosts, so it never reaches your backend and never becomes one shared key across all of your users. Same call as OAuth, one more argument.

from af_sdk import AgenticFabriq

af = AgenticFabriq()                      # reads AF_APP_ID / AF_APP_SECRET

url = await af.initiate_connection(request, provider="btc_pay_server", method="api_key")
return redirect(url)                      # an AF-hosted page, not yours

async with await af.for_user(request) as session:
    tools = await session.get_tools()     # only what this user granted

Provider names are surfaces, not vendors, and the authoritative list is the capabilities endpoint rather than any page including this one — an unknown name returns 400 with the valid list. Fabriq Developer is free to start and needs no provider paperwork. Start free or read the quickstart.

Connecting BTCPay Server in practice

BTCPay is self-hosted, so there is no app registry and no central consent screen: an agent sends the user to their own server with a permissions list in the URL and the user mints a key. The trap is the default — BTCPay warns that "Omitting permissions when creating a key can produce unrestricted access", so a blank permission list is the widest key, not the narrowest.

Scopes that draw scrutiny

no permissions specified BTCPay’s own warning: "Omitting permissions when creating a key can produce unrestricted access." The empty case is the dangerous one.
btcpay.store.cancreateinvoice Creates invoices on a store — the permission an agent that takes payments actually needs, and the one to ask for instead of a blank list.
btcpay.store.canviewinvoices Reads a store’s invoices, which is the customer payment history.
btcpay.store.cancreateinvoice:STORE_ID Any permission can be narrowed to one store by appending :STORE_ID, and selectiveStores=true on the authorization URL is what lets the user do it. Without the suffix the permission covers every store the user has.

Rate limits

Basic authentication "is rate limited and intended mainly to bootstrap an API key"; no figure is published for API-key requests, which is consistent with every instance being self-hosted.

Who has to approve

The server’s own user is the gate. An integration builds a URL to the user’s BTCPay instance carrying applicationName, permissions, optional selectiveStores=true and strict=true, and an HTTPS redirect, and the user approves it in their own UI. strict=true stops the user editing the requested permission list; selectiveStores=true lets them narrow each permission to a single store. applicationIdentifier lets the app recognise a prior authorization instead of asking again.

Worth knowing

The redirect URL must be HTTPS, which rules out a plain localhost callback during development.
Basic authentication has to be switched on per user under "Allow Basic authentication for Greenfield API" before it works at all, so a password-based fallback fails on a default install.
BTCPay states plainly: "Do not ask users to disclose their password to a third-party application and do not retain it as an integration credential" — basic auth is for bootstrapping a key and nothing else.
Because every deployment is a different server on a different version, permissions and endpoints an agent relies on may simply not exist on the instance it is pointed at.

Checked against Greenfield API authentication (2026-09-29), BTCPay Greenfield API reference (2026-09-29)

Acts as the person, not as itself

Each user connects their own account. Every call carries both identities — the agent and the person it is acting for — so the agent can never reach past what that individual can already do.

Credentials never touch the agent

Tokens live in the vault and attach server-side at call time. The agent holds a session, not a secret, and revoking access does not mean rotating a key.

Every call on the record

Who asked, which agent acted, which action ran, and the verdict that let it through — one audit trail across every integration, not one per vendor.

What an agent can do

Each action is granted on its own. An agent allowed to read is not thereby allowed to write, and the scope beside each row is what the acting user must have connected for it to run at all.

btc_pay_server_delete_api_v1_api_keys_by_apikeyidWRITE

Revoke the current API key so that it cannot be used anymore. DELETE /api/v1/api-keys/{apiKeyId}. The API key must carry the BTCPay permission `unrestricted`, which is chosen when the key is minted. Revokes the named key. The id is the `id` field, NOT the secret -- BTCPay's own schema says `id` exists 'to revoke it without sending the secret'. Passing this connection's own key id here has the same effect as 'Revoke the current API Key' and will disconnect this integration.

unrestricted

btc_pay_server_delete_api_v1_api_keys_currentWRITE

Revoke the current API key so that it cannot be used anymore. DELETE /api/v1/api-keys/current. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it. SELF-DESTRUCT. This revokes the key THIS CONNECTION IS AUTHENTICATING WITH, so every other Agentic Fabriq tool on this connection stops working the moment it succeeds and the connection has to be remade with a freshly minted key. It is not the tool for tidying up someone else's key: 'Revoke an API Key' (DELETE /api/v1/api-keys/{apiKeyId}) takes an id and leaves this connection alive.

api

btc_pay_server_delete_api_v1_apps_by_appidWRITE

Deletes app with specified ID. DELETE /api/v1/apps/{appId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_apps_by_appid_image_by_fileidWRITE

Deletes the app item image. DELETE /api/v1/apps/{appId}/image/{fileId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_files_by_fileidWRITE

Deletes the file. DELETE /api/v1/files/{fileId}. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted.

btcpay.server.canmodifyserversettings

btc_pay_server_delete_api_v1_invitations_by_tokenWRITE

Decline the current user's invitation identified by its token. DELETE /api/v1/invitations/{token}. The API key must carry the BTCPay permission `btcpay.user.canmodifyprofile`, which is chosen when the key is minted. Declines a store invitation. The token is single-use: declining it cannot be undone and a new invitation has to be sent.

btcpay.user.canmodifyprofile

btc_pay_server_delete_api_v1_invoices_by_invoiceidWRITE

Archives the specified invoice. The store is resolved automatically from the invoice. DELETE /api/v1/invoices/{invoiceId}. The API key must carry the BTCPay permission `btcpay.store.canmodifyinvoices`, which is chosen when the key is minted. ARCHIVES rather than erases, despite the DELETE verb: the invoice stops appearing in the default listing and can be brought back with 'Unarchive invoice'. Payments already received are not affected. This is the gentlest of this provider's 27 deletes and is safe to use for tidying.

btcpay.store.canmodifyinvoices

btc_pay_server_delete_api_v1_payment_requests_by_paymentrequestidWRITE

Archives the specified payment request. The store is resolved automatically from the payment request. DELETE /api/v1/payment-requests/{paymentRequestId}. The API key must carry the BTCPay permission `btcpay.store.canmodifypaymentrequests`, which is chosen when the key is minted. ARCHIVES the payment request rather than erasing it; invoices already created from it survive.

btcpay.store.canmodifypaymentrequests

btc_pay_server_delete_api_v1_payouts_by_payoutidWRITE

Cancel the payout. DELETE /api/v1/payouts/{payoutId}. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_delete_api_v1_pull_payments_by_pullpaymentidWRITE

Archive this pull payment (Will cancel all payouts awaiting for payment). The store is resolved automatically from the pull payment. DELETE /api/v1/pull-payments/{pullPaymentId}. The API key must carry the BTCPay permission `btcpay.store.canarchivepullpayments`, which is chosen when the key is minted. ARCHIVES the pull payment, which stops anyone claiming against it. Payouts already approved are not withdrawn by this -- cancel those individually with 'Cancel a payout'.

btcpay.store.canarchivepullpayments

btc_pay_server_delete_api_v1_stores_by_storeidWRITE

Removes the specified store. If there is another user with access, only your access will be removed. DELETE /api/v1/stores/{storeId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted. BLAST RADIUS DEPENDS ON WHO ELSE HAS ACCESS, and BTCPay says so: 'If there is another user with access, only your access will be removed.' So the same call is a soft leave on a shared store and a permanent deletion on a store only this account can reach -- invoices, payment requests, apps and webhooks included. Check 'List a store's users' first if which one it will be matters.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_lightning_addresses_by_usernameWRITE

Remove store configured lightning address. DELETE /api/v1/stores/{storeId}/lightning-addresses/{username}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_logoWRITE

Delete the store's logo. DELETE /api/v1/stores/{storeId}/logo. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselectorWRITE

Deletes a subscriber for a specific offering by customer selector. DELETE /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_delete_api_v1_stores_by_storeid_payment_methods_by_paymentmethodidWRITE

Delete information about the stores' configured payment method. DELETE /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_addressWRITE

UnReserve address. DELETE /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/address. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_delete_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objects_by_objecttype_by_objectid

WRITE

Remove wallet object. DELETE /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_delete_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objects_by_objecttype_by_objectid_links_by_linktype_by_linkid

WRITE

Remove wallet object link. DELETE /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links/{linkType}/{linkId}. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_delete_api_v1_stores_by_storeid_payout_processors_by_processor_by_paymentmethodidWRITE

Remove store configured payout processor. DELETE /api/v1/stores/{storeId}/payout-processors/{processor}/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_users_by_idoremailWRITE

Removes the specified store user. If there is no other owner, this endpoint will fail. DELETE /api/v1/stores/{storeId}/users/{idOrEmail}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_stores_by_storeid_users_by_idoremail_invitationWRITE

Cancel the specified user's pending store invitation. DELETE /api/v1/stores/{storeId}/users/{idOrEmail}/invitation. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_delete_api_v1_users_by_idoremailWRITE

Delete a user. Must be an admin to perform this operation. Attempting to delete the only admin user will not succeed. All data associated with the user will be deleted as well if the operation succeeds. DELETE /api/v1/users/{idOrEmail}. The API key must carry the BTCPay permission `btcpay.user.candeleteuser`, which is chosen when the key is minted.

btcpay.user.candeleteuser

btc_pay_server_delete_api_v1_users_by_idoremail_api_keys_by_apikeyidWRITE

Revoke the API key of a target user so that it cannot be used anymore. DELETE /api/v1/users/{idOrEmail}/api-keys/{apiKeyId}. The API key must carry the BTCPay permission `unrestricted`, which is chosen when the key is minted.

unrestricted

btc_pay_server_delete_api_v1_users_meWRITE

Deletes user profile and associated user data for user making the request. DELETE /api/v1/users/me. The API key must carry the BTCPay permission `btcpay.user.candeleteuser`, which is chosen when the key is minted. DELETES THE ACCOUNT THIS CONNECTION ACTS AS, and its data with it. There is no undo and the connection dies with the account. It is almost never the tool anyone wanted: removing a user from a STORE is 'Remove a store user', and disconnecting Agentic Fabriq is done here in the console.

btcpay.user.candeleteuser

btc_pay_server_delete_api_v1_users_me_notifications_by_idWRITE

Removes the specified notification. DELETE /api/v1/users/me/notifications/{id}. The API key must carry the BTCPay permission `btcpay.user.canmanagenotificationsforuser`, which is chosen when the key is minted.

btcpay.user.canmanagenotificationsforuser

btc_pay_server_delete_api_v1_users_me_pictureWRITE

Deletes the user profile picture. DELETE /api/v1/users/me/picture. The API key must carry the BTCPay permission `btcpay.user.canmodifyprofile`, which is chosen when the key is minted.

btcpay.user.canmodifyprofile

btc_pay_server_delete_api_v1_webhooks_by_webhookidWRITE

Delete a webhook. DELETE /api/v1/webhooks/{webhookId}. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_api_v1_api_keys_currentREAD

View information about the current API key. GET /api/v1/api-keys/current. The API key must carry the BTCPay permission `btcpay.server.canmanageusers`, which is chosen when the key is minted. THE `apiKey` FIELD IS REMOVED BEFORE YOU SEE IT, and that is this integration's doing rather than BTCPay's: the reply schema documents `apiKey` as 'The API Key to use for API Key Authentication' -- this connection's own credential, verbatim, from a read BTCPay requires no permission for. A tool result is not redacted anywhere downstream, so the connector replaces that one value with a marker. Everything else survives: `id` (which is what revokes a key without sending the secret), `label`, `created` and `permissions`, which is the useful part -- it tells you exactly what this connection's key is allowed to do, including any `:<storeId>` narrowing. Nothing here can hand back the credential.

btcpay.server.canmanageusers

btc_pay_server_get_api_v1_appsREAD

Returns basic app data for all apps for all stores. GET /api/v1/apps. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_apps_by_appidREAD

Returns basic app data shared between all types of apps. GET /api/v1/apps/{appId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_apps_by_appid_salesREAD

Returns sales statistics for the app. GET /api/v1/apps/{appId}/sales. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_apps_by_appid_top_itemsREAD

Returns top items statistics for the app. GET /api/v1/apps/{appId}/top-items. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_apps_crowdfund_by_appidREAD

Returns crowdfund app data. GET /api/v1/apps/crowdfund/{appId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_apps_pos_by_appidREAD

Returns POS app data. GET /api/v1/apps/pos/{appId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_filesREAD

Load all files that exist. GET /api/v1/files. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted.

btcpay.server.canmodifyserversettings

btc_pay_server_get_api_v1_files_by_fileidREAD

View information about the specified file. GET /api/v1/files/{fileId}. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted.

btcpay.server.canmodifyserversettings

btc_pay_server_get_api_v1_healthREAD

Check the instance health status. GET /api/v1/health. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it. The only endpoint on this surface that needs no credential at all (`security: []` in the specification, measured 200 against the public demo instance with no Authorization header). Useful as a control: if this answers and 'Get server info' 401s, the instance is up and the key is the problem.

api

btc_pay_server_get_api_v1_invitations_by_tokenREAD

Get invitation details from its token before accepting or declining it. GET /api/v1/invitations/{token}. The API key must carry the BTCPay permission `btcpay.user.canmodifyprofile`, which is chosen when the key is minted.

btcpay.user.canmodifyprofile

btc_pay_server_get_api_v1_invoices_by_invoiceidREAD

View information about the specified invoice. The store is resolved automatically from the invoice. GET /api/v1/invoices/{invoiceId}. The API key must carry the BTCPay permission `btcpay.store.canviewinvoices`, which is chosen when the key is minted.

btcpay.store.canviewinvoices

btc_pay_server_get_api_v1_invoices_by_invoiceid_payment_methodsREAD

View information about the specified invoice's payment methods. The store is resolved automatically from the invoice. GET /api/v1/invoices/{invoiceId}/payment-methods. The API key must carry the BTCPay permission `btcpay.store.canviewinvoices`, which is chosen when the key is minted.

btcpay.store.canviewinvoices

btc_pay_server_get_api_v1_invoices_by_invoiceid_refund_by_paymentmethodidREAD

View calculated refund amounts for the specified invoice/payment-method. The store is resolved automatically from the invoice. GET /api/v1/invoices/{invoiceId}/refund/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.cancreatepullpayments`, which is chosen when the key is minted.

btcpay.store.cancreatepullpayments

btc_pay_server_get_api_v1_payment_requests_by_paymentrequestidREAD

View information about the specified payment request. The store is resolved automatically from the payment request. GET /api/v1/payment-requests/{paymentRequestId}. The API key must carry the BTCPay permission `btcpay.store.canviewpaymentrequests`, which is chosen when the key is minted.

btcpay.store.canviewpaymentrequests

btc_pay_server_get_api_v1_payout_processorsREAD

Get payout processors available in this instance. GET /api/v1/payout-processors. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_payouts_by_payoutidREAD

Get payout. GET /api/v1/payouts/{payoutId}. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_get_api_v1_plan_checkout_by_checkoutidREAD

Retrieves the details of a plan checkout session. GET /api/v1/plan-checkout/{checkoutId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_pull_payments_by_pullpaymentidREAD

Get a pull payment. GET /api/v1/pull-payments/{pullPaymentId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_pull_payments_by_pullpaymentid_lnurlREAD

Get Pull Payment LNURL details. GET /api/v1/pull-payments/{pullPaymentId}/lnurl. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_pull_payments_by_pullpaymentid_payoutsREAD

Get payouts. GET /api/v1/pull-payments/{pullPaymentId}/payouts. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_pull_payments_by_pullpaymentid_payouts_by_payoutidREAD

Get payout. GET /api/v1/pull-payments/{pullPaymentId}/payouts/{payoutId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_server_emailREAD

Retrieve the email settings configured for the server. The password field will be masked if present. GET /api/v1/server/email. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted.

btcpay.server.canmodifyserversettings

btc_pay_server_get_api_v1_server_infoREAD

Information about the server, chains and sync states. GET /api/v1/server/info. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it. THE CONNECTION'S HEALTH CHECK, and the probe this provider declares. Chosen because the `API_Key` scheme requires NO permission for it, unlike `GET /api/v1/users/me` (`btcpay.user.canviewprofile`) and `GET /api/v1/api-keys/current` (documented against `btcpay.server.canmanageusers`), either of which would report a perfectly valid store-scoped key as invalid. Also the fastest way to see whether the instance's node and indexer are synced: an unsynced instance answers 200 here while invoice creation behaves oddly.

api

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_balanceREAD

View balance of the lightning node. GET /api/v1/server/lightning/{cryptoCode}/balance. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_channelsREAD

View information about the current channels of the lightning node. GET /api/v1/server/lightning/{cryptoCode}/channels. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_histogramREAD

View balance histogram of the lightning node. GET /api/v1/server/lightning/{cryptoCode}/histogram. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_infoREAD

View information about the lightning node. GET /api/v1/server/lightning/{cryptoCode}/info. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_invoicesREAD

View information about the lightning invoices. GET /api/v1/server/lightning/{cryptoCode}/invoices. The API key must carry the BTCPay permission `btcpay.server.canviewlightninginvoiceinternalnode`, which is chosen when the key is minted.

btcpay.server.canviewlightninginvoiceinternalnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_invoices_by_idREAD

View information about the requested lightning invoice. GET /api/v1/server/lightning/{cryptoCode}/invoices/{id}. The API key must carry the BTCPay permission `btcpay.server.canviewlightninginvoiceinternalnode`, which is chosen when the key is minted.

btcpay.server.canviewlightninginvoiceinternalnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_paymentsREAD

View information about the lightning payments. GET /api/v1/server/lightning/{cryptoCode}/payments. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_lightning_by_cryptocode_payments_by_paymenthashREAD

View information about the requested lightning payment. GET /api/v1/server/lightning/{cryptoCode}/payments/{paymentHash}. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_get_api_v1_server_rolesREAD

View information about the store's roles at the server's scope. GET /api/v1/server/roles. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted.

btcpay.server.canmodifyserversettings

btc_pay_server_get_api_v1_storesREAD

View information about the available stores. GET /api/v1/stores. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeidREAD

View information about the specified store. GET /api/v1/stores/{storeId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_appsREAD

Returns basic app data for all apps for a store. GET /api/v1/stores/{storeId}/apps. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_stores_by_storeid_emailREAD

Retrieve the email settings configured for specific store. The password field will be masked if present. GET /api/v1/stores/{storeId}/email. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_stores_by_storeid_invoicesREAD

View information about the existing invoices. GET /api/v1/stores/{storeId}/invoices. The API key must carry the BTCPay permission `btcpay.store.canviewinvoices`, which is chosen when the key is minted.

btcpay.store.canviewinvoices

btc_pay_server_get_api_v1_stores_by_storeid_lightning_addressesREAD

Get store configured lightning addresses. GET /api/v1/stores/{storeId}/lightning-addresses. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_lightning_addresses_by_usernameREAD

Get store configured lightning address. GET /api/v1/stores/{storeId}/lightning-addresses/{username}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_balanceREAD

View balance of the lightning node. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance. The API key must carry the BTCPay permission `btcpay.store.canuselightningnode`, which is chosen when the key is minted.

btcpay.store.canuselightningnode

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_channelsREAD

View information about the current channels of the lightning node. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted.

btcpay.store.cancreatelightninginvoice

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_histogramREAD

View balance histogram of the lightning node. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/histogram. The API key must carry the BTCPay permission `btcpay.store.canuselightningnode`, which is chosen when the key is minted.

btcpay.store.canuselightningnode

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_infoREAD

View information about the lightning node. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info. The API key must carry the BTCPay permission `btcpay.store.canuselightningnode`, which is chosen when the key is minted.

btcpay.store.canuselightningnode

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_invoicesREAD

View information about the lightning invoices. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices. The API key must carry the BTCPay permission `btcpay.store.canviewlightninginvoice`, which is chosen when the key is minted.

btcpay.store.canviewlightninginvoice

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_invoices_by_idREAD

View information about the requested lightning invoice. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices/{id}. The API key must carry the BTCPay permission `btcpay.store.canviewlightninginvoice`, which is chosen when the key is minted.

btcpay.store.canviewlightninginvoice

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_paymentsREAD

View information about the lightning payments. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/payments. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted.

btcpay.store.cancreatelightninginvoice

btc_pay_server_get_api_v1_stores_by_storeid_lightning_by_cryptocode_payments_by_paymenthashREAD

View information about the requested lightning payment. GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/payments/{paymentHash}. The API key must carry the BTCPay permission `btcpay.store.canuselightningnode`, which is chosen when the key is minted.

btcpay.store.canuselightningnode

btc_pay_server_get_api_v1_stores_by_storeid_offeringsREAD

Retrieves all offerings associated with the specified store. GET /api/v1/stores/{storeId}/offerings. The API key must carry the BTCPay permission `btcpay.store.canviewofferings`, which is chosen when the key is minted.

btcpay.store.canviewofferings

btc_pay_server_get_api_v1_stores_by_storeid_offerings_by_offeringidREAD

Returns a specific offering for a store. GET /api/v1/stores/{storeId}/offerings/{offeringId}. The API key must carry the BTCPay permission `btcpay.store.canviewofferings`, which is chosen when the key is minted.

btcpay.store.canviewofferings

btc_pay_server_get_api_v1_stores_by_storeid_offerings_by_offeringid_plans_by_planidREAD

Returns a specific plan for a given offering. GET /api/v1/stores/{storeId}/offerings/{offeringId}/plans/{planId}. The API key must carry the BTCPay permission `btcpay.store.canviewofferings`, which is chosen when the key is minted.

btcpay.store.canviewofferings

btc_pay_server_get_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselectorREAD

Retrieves a subscriber for a specific offering by customer selector. GET /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}. The API key must carry the BTCPay permission `btcpay.store.canviewofferings`, which is chosen when the key is minted.

btcpay.store.canviewofferings

btc_pay_server_get_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselector_credits_by_currencyREAD

Retrieves the credit balance for a subscriber in the specified currency. GET /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/credits/{currency}. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_get_api_v1_stores_by_storeid_payment_methodsREAD

View information about the stores' configured payment methods. GET /api/v1/stores/{storeId}/payment-methods. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted. `includeConfig=true` RETURNS CREDENTIALS FOR THE CUSTOMER'S OWN INFRASTRUCTURE and is not redacted: a lightning payment method's config carries `connectionString`, which routinely embeds a node macaroon, and an on-chain method's carries the wallet's derivation scheme. It is left intact because the matching PUT takes the same value back, so redacting it would break the read-modify-write BTCPay documents -- but do not pass `includeConfig=true` unless the config is what you need, and treat the result as secret when you do. BTCPay gates the flag on `btcpay.store.canmodifystoresettings` for the same reason.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodidREAD

View information about the stores' configured payment method. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted. Same warning as the listing: `includeConfig=true` can return a lightning `connectionString` (often with a macaroon in it) or a wallet's derivation scheme, unredacted, and BTCPay gates the flag on `btcpay.store.canmodifystoresettings`.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_walletREAD

View information about the specified wallet. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_addressREAD

Get or generate address for wallet. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/address. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_feerateREAD

Get wallet onchain fee rate. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/feerate. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_histogramREAD

View the balance histogram of the specified wallet. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/histogram. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objectsREAD

View wallet objects. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objects_by_objecttype_by_objectidREAD

View wallet object. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_previewREAD

View addresses of the current payment method of the store. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/preview. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_transactionsREAD

Get store on-chain wallet transactions. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_transactions_by_transactionidREAD

Get store on-chain wallet transaction. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/{transactionId}. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_utxosREAD

Get store on-chain wallet utxos. GET /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/utxos. The API key must carry the BTCPay permission `btcpay.store.canviewwallet`, which is chosen when the key is minted.

btcpay.store.canviewwallet

btc_pay_server_get_api_v1_stores_by_storeid_payment_requestsREAD

View information about the existing payment requests. GET /api/v1/stores/{storeId}/payment-requests. The API key must carry the BTCPay permission `btcpay.store.canviewpaymentrequests`, which is chosen when the key is minted.

btcpay.store.canviewpaymentrequests

btc_pay_server_get_api_v1_stores_by_storeid_payout_processorsREAD

Get store configured payout processors. GET /api/v1/stores/{storeId}/payout-processors. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payout_processors_lightningautomatedpayoutsenderfactoryREAD

Get configured store Lightning automated payout processors. GET /api/v1/stores/{storeId}/payout-processors/LightningAutomatedPayoutSenderFactory. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payout_processors_lightningautomatedpayoutsenderfactory_by_payoutmethodidREAD

Get configured store Lightning automated payout processors. GET /api/v1/stores/{storeId}/payout-processors/LightningAutomatedPayoutSenderFactory/{payoutMethodId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payout_processors_onchainautomatedpayoutsenderfactory_by_paymentmethodidREAD

Get configured store onchain automated payout processors. GET /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedPayoutSenderFactory/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payout_processors_onchainautomatedtransfersenderfactoryREAD

Get configured store onchain automated payout processors. GET /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedTransferSenderFactory. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_payoutsREAD

Get payouts. GET /api/v1/stores/{storeId}/payouts. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_stores_by_storeid_pull_paymentsREAD

Get the pull payments of a store. GET /api/v1/stores/{storeId}/pull-payments. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_get_api_v1_stores_by_storeid_ratesREAD

Get rates on the store. GET /api/v1/stores/{storeId}/rates. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_rates_configuration_by_ratesourceREAD

View rate settings for the specified store and rate source (`primary` or `fallback`). GET /api/v1/stores/{storeId}/rates/configuration/{rateSource}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_rolesREAD

View information about the specified store's roles. GET /api/v1/stores/{storeId}/roles. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_get_api_v1_stores_by_storeid_usersREAD

View users of the specified store. GET /api/v1/stores/{storeId}/users. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_users_invitationsREAD

View pending and expired invitations for the specified store. GET /api/v1/stores/{storeId}/users/invitations. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_get_api_v1_stores_by_storeid_webhooksREAD

View webhooks of a store. GET /api/v1/stores/{storeId}/webhooks. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_api_v1_subscriber_portal_by_portalsessionidREAD

Retrieves the details of an existing subscriber portal session. GET /api/v1/subscriber-portal/{portalSessionId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_api_v1_usersREAD

Load all users that exist. GET /api/v1/users. The API key must carry the BTCPay permission `btcpay.server.canviewusers`, which is chosen when the key is minted.

btcpay.server.canviewusers

btc_pay_server_get_api_v1_users_by_idoremailREAD

Get 1 user by ID or Email. GET /api/v1/users/{idOrEmail}. The API key must carry the BTCPay permission `btcpay.server.canviewusers`, which is chosen when the key is minted.

btcpay.server.canviewusers

btc_pay_server_get_api_v1_users_meREAD

View information about the current user. GET /api/v1/users/me. The API key must carry the BTCPay permission `btcpay.user.canviewprofile`, which is chosen when the key is minted.

btcpay.user.canviewprofile

btc_pay_server_get_api_v1_users_me_notification_settingsREAD

View information about your notification settings. GET /api/v1/users/me/notification-settings. The API key must carry the BTCPay permission `btcpay.user.canmanagenotificationsforuser`, which is chosen when the key is minted.

btcpay.user.canmanagenotificationsforuser

btc_pay_server_get_api_v1_users_me_notificationsREAD

View current user's notifications. GET /api/v1/users/me/notifications. The API key must carry the BTCPay permissions `btcpay.user.canmanagenotificationsforuser`, `btcpay.user.canviewnotificationsforuser`, which are chosen when the key is minted.

btcpay.user.canmanagenotificationsforuserbtcpay.user.canviewnotificationsforuser

btc_pay_server_get_api_v1_users_me_notifications_by_idREAD

View information about the specified notification. GET /api/v1/users/me/notifications/{id}. The API key must carry the BTCPay permissions `btcpay.user.canmanagenotificationsforuser`, `btcpay.user.canviewnotificationsforuser`, which are chosen when the key is minted.

btcpay.user.canmanagenotificationsforuserbtcpay.user.canviewnotificationsforuser

btc_pay_server_get_api_v1_webhooks_by_webhookidREAD

View webhook. GET /api/v1/webhooks/{webhookId}. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_api_v1_webhooks_by_webhookid_deliveriesREAD

List the latest deliveries to the webhook, ordered from the most recent. GET /api/v1/webhooks/{webhookId}/deliveries. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_api_v1_webhooks_by_webhookid_deliveries_by_deliveryidREAD

Information about a webhook delivery. GET /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_api_v1_webhooks_by_webhookid_deliveries_by_deliveryid_requestREAD

The delivery's JSON request sent to the endpoint. GET /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/request. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_get_misc_langREAD

The supported language codes. GET /misc/lang. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_get_misc_permissionsREAD

The metadata of available permissions. GET /misc/permissions. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it. BTCPay'S OWN COPY OF THE PERMISSION VOCABULARY, from the instance you are connected to, with an `included` array per permission saying which other permissions it implies. Call this when you need to know what to tick while minting a key for a particular set of tools -- it is the authoritative answer for THIS instance and version, where the scope list Agentic Fabriq renders is read from the Greenfield specification. Needs no permission.

api

btc_pay_server_get_misc_rate_sourcesREAD

View available rate providers that you can use in stores. GET /misc/rate-sources. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_patch_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_transactions_by_transactionidWRITE

Patch store on-chain wallet transaction info. PATCH /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/{transactionId}. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_post_api_v1_api_keysWRITE

Create a new API Key. POST /api/v1/api-keys. The API key must carry the BTCPay permission `unrestricted`, which is chosen when the key is minted. THE REPLY CONTAINS A LIVE CREDENTIAL AND IT IS NOT REDACTED, because that is the entire point of this call and BTCPay never shows the value again. Treat the result as a secret. Requires an `unrestricted` key (or HTTP Basic, which this integration does not implement), so a store-scoped e-commerce key cannot call it -- which is deliberate on BTCPay's part: a key that could mint keys could escalate itself. The new key inherits nothing it does not ask for, and an API key can never expand its creator's own rights.

unrestricted

btc_pay_server_post_api_v1_invitations_by_tokenWRITE

Accept the current user's pending invitation identified by its token. POST /api/v1/invitations/{token}. The API key must carry the BTCPay permission `btcpay.user.canmodifyprofile`, which is chosen when the key is minted. Accepts a store invitation ON BEHALF OF THE ACCOUNT THIS CONNECTION ACTS AS, granting that account access to somebody else's store. The token comes from the invitation e-mail.

btcpay.user.canmodifyprofile

btc_pay_server_post_api_v1_invoices_by_invoiceid_payment_methods_by_paymentmethodid_activateWRITE

Activate an invoice payment method (if lazy payments mode is enabled). The store is resolved automatically from the invoice. POST /api/v1/invoices/{invoiceId}/payment-methods/{paymentMethodId}/activate. The API key must carry the BTCPay permission `btcpay.store.canviewinvoices`, which is chosen when the key is minted.

btcpay.store.canviewinvoices

btc_pay_server_post_api_v1_invoices_by_invoiceid_refundWRITE

Refund invoice. The store is resolved automatically from the invoice. POST /api/v1/invoices/{invoiceId}/refund. The API key must carry the BTCPay permission `btcpay.store.cancreatepullpayments`, which is chosen when the key is minted. Creates a PULL PAYMENT the payer can claim against; it does not push coins anywhere by itself and nothing leaves the wallet until a payout is approved and processed. Archive the pull payment to withdraw the offer.

btcpay.store.cancreatepullpayments

btc_pay_server_post_api_v1_invoices_by_invoiceid_statusWRITE

Mark an invoice as invalid or settled. The store is resolved automatically from the invoice. POST /api/v1/invoices/{invoiceId}/status. The API key must carry the BTCPay permission `btcpay.store.canmodifyinvoices`, which is chosen when the key is minted. FORCES an invoice's status rather than observing it -- marking an unpaid invoice `Settled` tells the rest of BTCPay, and anything listening to webhooks, that money arrived when it did not. It exists for reconciling out-of-band payments. Reversible only by marking it again.

btcpay.store.canmodifyinvoices

btc_pay_server_post_api_v1_invoices_by_invoiceid_unarchiveWRITE

Unarchive an invoice. The store is resolved automatically from the invoice. POST /api/v1/invoices/{invoiceId}/unarchive. The API key must carry the BTCPay permission `btcpay.store.canmodifyinvoices`, which is chosen when the key is minted.

btcpay.store.canmodifyinvoices

btc_pay_server_post_api_v1_payment_requests_by_paymentrequestid_payWRITE

Create a new invoice for the payment request, or reuse an existing one. The store is resolved automatically from the payment request. POST /api/v1/payment-requests/{paymentRequestId}/pay. The API key must carry the BTCPay permission `btcpay.store.canviewpaymentrequests`, which is chosen when the key is minted.

btcpay.store.canviewpaymentrequests

btc_pay_server_post_api_v1_payouts_by_payoutidWRITE

Approve a payout. POST /api/v1/payouts/{payoutId}. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_post_api_v1_payouts_by_payoutid_markWRITE

Mark a payout with a state. POST /api/v1/payouts/{payoutId}/mark. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_post_api_v1_payouts_by_payoutid_mark_paidWRITE

Mark a payout as paid. POST /api/v1/payouts/{payoutId}/mark-paid. The API key must carry the BTCPay permission `btcpay.store.canmanagepullpayments`, which is chosen when the key is minted.

btcpay.store.canmanagepullpayments

btc_pay_server_post_api_v1_plan_checkoutWRITE

Creates a checkout session for purchasing or activating a plan. POST /api/v1/plan-checkout. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_post_api_v1_plan_checkout_by_checkoutidWRITE

Continues a plan checkout session. **Behavior:** - If payment is required, the checkout assigns a BTCPay Server invoice and `invoiceId` will be set. - 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`. POST /api/v1/plan-checkout/{checkoutId}. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_post_api_v1_pull_payments_by_pullpaymentid_boltcardsWRITE

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). POST /api/v1/pull-payments/{pullPaymentId}/boltcards. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_post_api_v1_pull_payments_by_pullpaymentid_payoutsWRITE

Create a new payout. POST /api/v1/pull-payments/{pullPaymentId}/payouts. Needs no BTCPay permission: the specification declares this endpoint with an empty permission list, so any valid API key reaches it.

api

btc_pay_server_post_api_v1_server_lightning_by_cryptocode_addressWRITE

Get an on-chain deposit address for the lightning node. POST /api/v1/server/lightning/{cryptoCode}/address. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_post_api_v1_server_lightning_by_cryptocode_channelsWRITE

Open a channel with another lightning node. You should connect to that node first. POST /api/v1/server/lightning/{cryptoCode}/channels. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_post_api_v1_server_lightning_by_cryptocode_connectWRITE

Connect to another lightning node. POST /api/v1/server/lightning/{cryptoCode}/connect. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted.

btcpay.server.canuseinternallightningnode

btc_pay_server_post_api_v1_server_lightning_by_cryptocode_invoicesWRITE

Create a lightning invoice. POST /api/v1/server/lightning/{cryptoCode}/invoices. The API key must carry the BTCPay permission `btcpay.server.cancreatelightninginvoiceinternalnode`, which is chosen when the key is minted.

btcpay.server.cancreatelightninginvoiceinternalnode

btc_pay_server_post_api_v1_server_lightning_by_cryptocode_invoices_payWRITE

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 — it might take longer if multiple routes are tried or a hold invoice is getting paid. POST /api/v1/server/lightning/{cryptoCode}/invoices/pay. The API key must carry the BTCPay permission `btcpay.server.canuseinternallightningnode`, which is chosen when the key is minted. SPENDS REAL BITCOIN from the SERVER'S INTERNAL node, which every store on the instance may be sharing. Irreversible once settled. BTCPay waits about 30 seconds for a result and then reports `pending`; that is NOT a failure and must not be retried blindly -- resolve it with 'Get a lightning payment made by the server's internal node' using the payment hash, because paying twice is how a retry loses the money twice.

btcpay.server.canuseinternallightningnode

btc_pay_server_post_api_v1_storesWRITE

Create a new store (default values can be different if the server settings use a default store template). POST /api/v1/stores. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_apps_crowdfundWRITE

Create a new Crowdfund app. POST /api/v1/stores/{storeId}/apps/crowdfund. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_apps_posWRITE

Point of Sale app allows accepting payments for items in a virtual store. POST /api/v1/stores/{storeId}/apps/pos. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_email_sendWRITE

Send an email using the store's SMTP server. POST /api/v1/stores/{storeId}/email/send. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted. Sends e-mail as the STORE, through the store's own SMTP settings, to whatever addresses the body names. It reaches real inboxes; there is no sandbox.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_invoicesWRITE

Create a new invoice. POST /api/v1/stores/{storeId}/invoices. The API key must carry the BTCPay permission `btcpay.store.cancreateinvoice`, which is chosen when the key is minted.

btcpay.store.cancreateinvoice

btc_pay_server_post_api_v1_stores_by_storeid_lightning_addresses_by_usernameWRITE

Add or update store configured lightning address. POST /api/v1/stores/{storeId}/lightning-addresses/{username}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_lightning_by_cryptocode_addressWRITE

Get an on-chain deposit address for the lightning node. POST /api/v1/stores/{storeId}/lightning/{cryptoCode}/address. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted.

btcpay.store.cancreatelightninginvoice

btc_pay_server_post_api_v1_stores_by_storeid_lightning_by_cryptocode_channelsWRITE

Open a channel with another lightning node. You should connect to that node first. POST /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted.

btcpay.store.cancreatelightninginvoice

btc_pay_server_post_api_v1_stores_by_storeid_lightning_by_cryptocode_connectWRITE

Connect to another lightning node. POST /api/v1/stores/{storeId}/lightning/{cryptoCode}/connect. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted.

btcpay.store.cancreatelightninginvoice

btc_pay_server_post_api_v1_stores_by_storeid_lightning_by_cryptocode_invoicesWRITE

Create a lightning invoice. POST /api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices. The API key must carry the BTCPay permission `btcpay.server.cancreatelightninginvoiceinternalnode`, which is chosen when the key is minted.

btcpay.server.cancreatelightninginvoiceinternalnode

btc_pay_server_post_api_v1_stores_by_storeid_lightning_by_cryptocode_invoices_payWRITE

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 — it might take longer if multiple routes are tried or a hold invoice is getting paid. POST /api/v1/stores/{storeId}/lightning/{cryptoCode}/invoices/pay. The API key must carry the BTCPay permission `btcpay.store.cancreatelightninginvoice`, which is chosen when the key is minted. SPENDS REAL BITCOIN from the store's lightning node. Irreversible once settled. Same 30-second timeout and the same `pending` reply as the internal-node form: resolve it with 'Get a lightning payment made by a store's node' rather than retrying, because a retry can pay twice.

btcpay.store.cancreatelightninginvoice

btc_pay_server_post_api_v1_stores_by_storeid_offeringsWRITE

Creates a new offering for the specified store. POST /api/v1/stores/{storeId}/offerings. The API key must carry the BTCPay permission `btcpay.store.canmodifyofferings`, which is chosen when the key is minted.

btcpay.store.canmodifyofferings

btc_pay_server_post_api_v1_stores_by_storeid_offerings_by_offeringid_plansWRITE

Creates a new plan for a specific offering. POST /api/v1/stores/{storeId}/offerings/{offeringId}/plans. The API key must carry the BTCPay permission `btcpay.store.canmodifyofferings`, which is chosen when the key is minted.

btcpay.store.canmodifyofferings

btc_pay_server_post_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselector_credits_by_currencyWRITE

Adds credit or charges credit for a subscriber in a given currency. POST /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/credits/{currency}. The API key must carry the BTCPay permission `btcpay.store.cancreditsubscribers`, which is chosen when the key is minted.

btcpay.store.cancreditsubscribers

btc_pay_server_post_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselector_suspendWRITE

Suspends a subscriber for the specified offering. POST /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/suspend. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_post_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselector_unsuspendWRITE

Removes suspension from a subscriber for the specified offering. POST /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/unsuspend. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_generateWRITE

Generate a wallet and update the specified store's payment method to it. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/generate. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted. GENERATES A NEW WALLET AND POINTS THE STORE AT IT, which makes this the most dangerous call on the surface. If the store already has a wallet configured, it is REPLACED: BTCPay will stop watching the old one, and any funds there become unreachable through this store. THE REPLY CARRIES THE SEED PHRASE (`mnemonic`) and Agentic Fabriq does not redact it -- BTCPay's own field description says 'BE SURE TO backup the mnemonic', and it is the only copy that will ever exist, so removing it would destroy the customer's recovery material rather than protect a credential. Capture it somewhere safe and treat the tool result as secret. `savePrivateKeys: false` with no `existingMnemonic` means BTCPay keeps nothing: lose the mnemonic and the funds are gone.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objectsWRITE

Add/Update wallet objects. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_objects_by_objecttype_by_objectid_links

WRITE

Add/Update wallet object link. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links. The API key must carry the BTCPay permission `btcpay.store.canmanagewallettransactions`, which is chosen when the key is minted.

btcpay.store.canmanagewallettransactions

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_previewWRITE

View addresses of a proposed payment method of the store. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/preview. The API key must carry the BTCPay permission `btcpay.store.canmanagewalletsettings`, which is chosen when the key is minted.

btcpay.store.canmanagewalletsettings

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_transactionsWRITE

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. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions. The API key must carry the BTCPay permissions `btcpay.store.cancreatetransactions`, `btcpay.store.cansigntransactions`, which are chosen when the key is minted. MOVES REAL BITCOIN AND CANNOT BE UNDONE once broadcast. BTCPay's own description names three permissions: `btcpay.store.cancreatetransactions` and `btcpay.store.cansigntransactions` always, plus `btcpay.store.canbroadcasttransactions` when `proceedWithBroadcast` is true (including Payjoin). Send `proceedWithBroadcast: false` to get a signed transaction back WITHOUT publishing it, which is the safe way to have an agent prepare a payment for a human to release. There is no cancel: a broadcast transaction is final.

btcpay.store.cancreatetransactionsbtcpay.store.cansigntransactions

btc_pay_server_post_api_v1_stores_by_storeid_payment_methods_by_paymentmethodid_wallet_transactions_broadcastWRITE

Broadcast a raw transaction hex string or a finalized PSBT for the specified wallet. POST /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/broadcast. The API key must carry the BTCPay permission `btcpay.store.canbroadcasttransactions`, which is chosen when the key is minted. PUBLISHES A TRANSACTION TO THE BITCOIN NETWORK. Irreversible, and it does not care where the hex or the finalized PSBT came from -- this is the release step for anything 'Create store on-chain wallet transaction' prepared with `proceedWithBroadcast: false`.

btcpay.store.canbroadcasttransactions

btc_pay_server_post_api_v1_stores_by_storeid_payment_requestsWRITE

Create a new payment request. POST /api/v1/stores/{storeId}/payment-requests. The API key must carry the BTCPay permission `btcpay.store.canmodifypaymentrequests`, which is chosen when the key is minted.

btcpay.store.canmodifypaymentrequests

btc_pay_server_post_api_v1_stores_by_storeid_payoutsWRITE

Create a new payout. POST /api/v1/stores/{storeId}/payouts. The API key must carry the BTCPay permissions `btcpay.store.cancreatenonapprovedpullpayments`, `btcpay.store.cancreatepullpayments`, which are chosen when the key is minted.

btcpay.store.cancreatenonapprovedpullpaymentsbtcpay.store.cancreatepullpayments

btc_pay_server_post_api_v1_stores_by_storeid_pull_paymentsWRITE

A pull payment allows its receiver to ask for payouts up to `amount` of `currency` every `period`. POST /api/v1/stores/{storeId}/pull-payments. The API key must carry the BTCPay permissions `btcpay.store.cancreatenonapprovedpullpayments`, `btcpay.store.cancreatepullpayments`, which are chosen when the key is minted.

btcpay.store.cancreatenonapprovedpullpaymentsbtcpay.store.cancreatepullpayments

btc_pay_server_post_api_v1_stores_by_storeid_rates_configuration_previewWRITE

Preview rate configuration results before you set it on the store. POST /api/v1/stores/{storeId}/rates/configuration/preview. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_usersWRITE

Add a store user. By default, this creates a store invitation. To add the user directly, set `requireInvitation` to `false`; this requires server settings permission. POST /api/v1/stores/{storeId}/users. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_users_by_idoremail_invitationWRITE

Generate and deliver a new token for an existing pending store invitation. POST /api/v1/stores/{storeId}/users/{idOrEmail}/invitation. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_post_api_v1_stores_by_storeid_webhooksWRITE

Create a new webhook. POST /api/v1/stores/{storeId}/webhooks. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted. THE REPLY CONTAINS THE WEBHOOK SECRET, deliberately and only here: it is the HMAC key your receiver needs to verify the `BTCPay-Sig` header (`sha256=HMAC256(UTF8(secret), body)`), and `GET /api/v1/webhooks/{webhookId}` does NOT return it -- checked against the sealed schema. Leave `secret` out of the request and BTCPay generates one.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_post_api_v1_subscriber_portalWRITE

Creates a portal session that allows a subscriber to manage their subscriptions, view billing details, or update account information. POST /api/v1/subscriber-portal. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_post_api_v1_usersWRITE

Create a new user. This operation can be called without authentication in any of this cases: * There is not any administrator yet on the server, * User registrations are not disabled in the server's policies. If the first administrator is created by this call, user registrations are automatically disabled. POST /api/v1/users. The API key must carry the BTCPay permission `btcpay.server.cancreateuser`, which is chosen when the key is minted. Creates a BTCPay user. Whether an unauthenticated caller may do this depends on the instance's registration policy, and the FIRST user created on a fresh instance becomes the server administrator -- so on a new instance this is an administrator-creation call. Omit `password` and BTCPay e-mails the new user a link to set their own, which keeps the secret out of this request and out of any log that records it.

btcpay.server.cancreateuser

btc_pay_server_post_api_v1_users_by_idoremail_api_keysWRITE

Create a new API Key for a user. POST /api/v1/users/{idOrEmail}/api-keys. The API key must carry the BTCPay permission `btcpay.server.canmanageusers`, which is chosen when the key is minted. THE REPLY CONTAINS A LIVE CREDENTIAL FOR ANOTHER USER and is not redacted, for the same reason as 'Create a new API Key': it is shown once. This is the server-administrator form -- it mints a key that acts as somebody else -- so it is the sharpest privilege on this surface after the wallet tools. Requires an `unrestricted` key.

btcpay.server.canmanageusers

btc_pay_server_post_api_v1_users_by_idoremail_approveWRITE

Approve or unapprove a user. Must be an admin to perform this operation. Attempting to (un)approve a user for which this requirement does not exist will not succeed. POST /api/v1/users/{idOrEmail}/approve. The API key must carry the BTCPay permission `btcpay.user.canmodifyserversettings`, which is chosen when the key is minted. Approves or un-approves another user on an instance whose registration policy requires approval; an un-approved user cannot sign in. Like the lock toggle, the direction comes from the body rather than the verb. THE PERMISSION THIS NEEDS IS UNDOCUMENTED in the same way -- see 'Lock or approve other users' in the permission list.

btcpay.user.canmodifyserversettings

btc_pay_server_post_api_v1_users_by_idoremail_lockWRITE

Lock or unlock a user. Must be an admin to perform this operation. Attempting to lock the only admin user will not succeed. POST /api/v1/users/{idOrEmail}/lock. The API key must carry the BTCPay permission `btcpay.user.canmodifyserversettings`, which is chosen when the key is minted. Locks or unlocks another user, which immediately stops their keys working. It is a toggle keyed on the body, not on the verb, so read the current state first if you need to be sure which way it will go. THE PERMISSION THIS NEEDS IS UNDOCUMENTED: the specification declares `btcpay.user.canmodifyserversettings` here, and that string is not in the API_Key scheme's permission table -- which lists the administrator permission as `btcpay.server.canmodifyserversettings` instead. Call 'Permissions metadata' on your own instance to see which spelling it really has, and mint the key with the server-administrator permission if the `user.` one is absent.

btcpay.user.canmodifyserversettings

btc_pay_server_post_api_v1_webhooks_by_webhookid_deliveries_by_deliveryid_redeliverWRITE

Redeliver the delivery. POST /api/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted.

btcpay.store.webhooks.canmodifywebhooks

btc_pay_server_put_api_v1_apps_crowdfund_by_appidWRITE

Full update. GET the app first, modify the data, then PUT the complete payload. PUT /api/v1/apps/crowdfund/{appId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_apps_pos_by_appidWRITE

Use this endpoint for updating the properties of a POS app. PUT /api/v1/apps/pos/{appId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_invoices_by_invoiceidWRITE

Updates the specified invoice. The store is resolved automatically from the invoice. PUT /api/v1/invoices/{invoiceId}. The API key must carry the BTCPay permission `btcpay.store.canmodifyinvoices`, which is chosen when the key is minted.

btcpay.store.canmodifyinvoices

btc_pay_server_put_api_v1_payment_requests_by_paymentrequestidWRITE

Update a payment request. The store is resolved automatically from the payment request. PUT /api/v1/payment-requests/{paymentRequestId}. The API key must carry the BTCPay permission `btcpay.store.canmodifypaymentrequests`, which is chosen when the key is minted.

btcpay.store.canmodifypaymentrequests

btc_pay_server_put_api_v1_server_emailWRITE

Update server's email settings. PUT /api/v1/server/email. The API key must carry the BTCPay permission `btcpay.server.canmodifyserversettings`, which is chosen when the key is minted. Rewrites the SERVER-WIDE outbound mail configuration, which every store without its own settings falls back to -- a wrong value here silently stops password resets and invoice e-mails for the whole instance. BTCPay never returns the password on the matching GET (it answers a boolean `passwordSet` instead), so read-modify-write does NOT round-trip the password: leave it null to keep the stored one.

btcpay.server.canmodifyserversettings

btc_pay_server_put_api_v1_stores_by_storeidWRITE

Update the specified store (default values can be different if the server settings use a default store template). PUT /api/v1/stores/{storeId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_stores_by_storeid_emailWRITE

Update a store's email settings. PUT /api/v1/stores/{storeId}/email. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_stores_by_storeid_offerings_by_offeringidWRITE

Updates an existing offering for the specified store. PUT /api/v1/stores/{storeId}/offerings/{offeringId}. The API key must carry the BTCPay permission `btcpay.store.canmodifyofferings`, which is chosen when the key is minted.

btcpay.store.canmodifyofferings

btc_pay_server_put_api_v1_stores_by_storeid_offerings_by_offeringid_plans_by_planidWRITE

Updates an existing plan for a specific offering. PUT /api/v1/stores/{storeId}/offerings/{offeringId}/plans/{planId}. The API key must carry the BTCPay permission `btcpay.store.canmodifyofferings`, which is chosen when the key is minted.

btcpay.store.canmodifyofferings

btc_pay_server_put_api_v1_stores_by_storeid_offerings_by_offeringid_subscribers_by_customerselector_datesWRITE

Manually overrides the subscription start date and/or expiration date for a subscriber. Omitting a field leaves the corresponding date unchanged. An empty body `{}` is a no-op and returns the subscriber unchanged. When `expirationDate` is provided, the grace period end and reminder date are recalculated automatically from the plan settings. PUT /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/dates. The API key must carry the BTCPay permission `btcpay.store.canmanagesubscribers`, which is chosen when the key is minted.

btcpay.store.canmanagesubscribers

btc_pay_server_put_api_v1_stores_by_storeid_payment_methods_by_paymentmethodidWRITE

Update information about the stores' configured payment method. PUT /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_stores_by_storeid_payout_processors_lightningautomatedpayoutsenderfactory_by_payoutmethodidWRITE

Update configured store Lightning automated payout processors. PUT /api/v1/stores/{storeId}/payout-processors/LightningAutomatedPayoutSenderFactory/{payoutMethodId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_put_api_v1_stores_by_storeid_payout_processors_onchainautomatedpayoutsenderfactory_by_paymentmethodidWRITE

Update configured store onchain automated payout processors. PUT /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedPayoutSenderFactory/{paymentMethodId}. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_put_api_v1_stores_by_storeid_payout_processors_onchainautomatedtransfersenderfactoryWRITE

Update configured store onchain automated payout processors. PUT /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedTransferSenderFactory. The API key must carry the BTCPay permission `btcpay.store.canviewstoresettings`, which is chosen when the key is minted.

btcpay.store.canviewstoresettings

btc_pay_server_put_api_v1_stores_by_storeid_rates_configuration_by_ratesourceWRITE

Update rate settings for the specified store and rate source (`primary` or `fallback`). PUT /api/v1/stores/{storeId}/rates/configuration/{rateSource}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_stores_by_storeid_usersWRITE

Update the role of an existing store user. The user id or email must be provided in the request body. PUT /api/v1/stores/{storeId}/users. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_stores_by_storeid_users_by_idoremailWRITE

Update the role of an existing store user. PUT /api/v1/stores/{storeId}/users/{idOrEmail}. The API key must carry the BTCPay permission `btcpay.store.canmodifystoresettings`, which is chosen when the key is minted.

btcpay.store.canmodifystoresettings

btc_pay_server_put_api_v1_users_meWRITE

Update the current user. PUT /api/v1/users/me. The API key must carry the BTCPay permission `btcpay.user.canmodifyprofile`, which is chosen when the key is minted. This is where a BTCPay account's PASSWORD and e-mail change, so `currentPassword` is required to move either. It also carries `allowGreenfieldBasicAuth`, the switch that decides whether this instance accepts an e-mail-and-password HTTP Basic credential at all. Agentic Fabriq never uses that path (see the adapter), and turning it OFF is a sensible hardening step that does not affect this connection.

btcpay.user.canmodifyprofile

btc_pay_server_put_api_v1_users_me_notification_settingsWRITE

Updates the current user's notification settings. PUT /api/v1/users/me/notification-settings. The API key must carry the BTCPay permission `btcpay.user.canmanagenotificationsforuser`, which is chosen when the key is minted.

btcpay.user.canmanagenotificationsforuser

btc_pay_server_put_api_v1_users_me_notifications_by_idWRITE

Updates the notification. PUT /api/v1/users/me/notifications/{id}. The API key must carry the BTCPay permission `btcpay.user.canmanagenotificationsforuser`, which is chosen when the key is minted.

btcpay.user.canmanagenotificationsforuser

btc_pay_server_put_api_v1_webhooks_by_webhookidWRITE

Update a webhook. PUT /api/v1/webhooks/{webhookId}. The API key must carry the BTCPay permission `btcpay.store.webhooks.canmodifywebhooks`, which is chosen when the key is minted. Sending `secret` here ROTATES it, and every delivery after that is signed with the new value -- a receiver still checking the old one will reject genuine deliveries. Omit the field to leave it alone.

btcpay.store.webhooks.canmodifywebhooks

Often connected alongside

Put BTCPay Server behind one governed endpoint.

Same permissions, same audit trail, whatever else you connect next.

Start free See pricing