BTCPay Server Store (Payment Methods) API

openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Store (Payment Methods) API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Store (Payment Methods)
  description: Store Payment Methods operations
paths:
  /api/v1/stores/{storeId}/payment-methods:
    get:
      tags:
      - Store (Payment Methods)
      summary: Get store payment methods
      description: View information about the stores' configured payment methods
      operationId: StorePaymentMethods_GetStorePaymentMethods
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: onlyEnabled
        in: query
        required: false
        description: Fetch payment methods that are enabled/disabled only
        schema:
          type: boolean
      - name: includeConfig
        in: query
        required: false
        description: Fetch the config of the payment methods, if `true`, the permission `btcpay.store.canmodifystoresettings` is required.
        schema:
          type: boolean
      responses:
        '200':
          description: List of payment methods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GenericPaymentMethodData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}:
    get:
      tags:
      - Store (Payment Methods)
      summary: Get store payment method
      description: View information about the stores' configured payment method
      operationId: StorePaymentMethods_GetStorePaymentMethod
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: includeConfig
        in: query
        required: false
        description: Fetch the config of the payment methods, if `true`, the permission `btcpay.store.canmodifystoresettings` is required.
        schema:
          type: boolean
      - $ref: '#/components/parameters/PaymentMethodId'
      responses:
        '200':
          description: The payment method config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericPaymentMethodData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Store (Payment Methods)
      summary: Update store's payment method
      description: Update information about the stores' configured payment method
      operationId: StorePaymentMethods_UpdateStorePaymentMethod
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentMethodConfig'
      responses:
        '200':
          description: The payment method config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericPaymentMethodData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    delete:
      tags:
      - Store (Payment Methods)
      summary: Delete store's payment method
      description: Delete information about the stores' configured payment method
      operationId: StorePaymentMethods_DeleteStorePaymentMethod
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      responses:
        '200':
          description: The configuration got deleted
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
components:
  parameters:
    PaymentMethodId:
      name: paymentMethodId
      in: path
      required: true
      description: The payment method id of the payment method to update
      schema:
        $ref: '#/components/schemas/PaymentMethodId'
      example: BTC-CHAIN
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  schemas:
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          nullable: false
          description: An error code describing the error
        message:
          type: string
          nullable: false
          description: User friendly error message about the error
    OnChainPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        derivationScheme:
          type: string
          description: The derivation scheme
          example: xpub...
        label:
          type: string
          description: A label that will be shown in the UI
        accountKeyPath:
          type: string
          description: The wallet fingerprint followed by the keypath to derive the account key used for signing operation or creating PSBTs
          example: abcd82a1/84'/0'/0'
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    LightningNetworkPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        connectionString:
          type: string
          description: The lightning connection string. Set to 'Internal Node' to use the internal node. (See [this doc](https://github.com/btcpayserver/BTCPayServer.Lightning/blob/master/README.md#examples) for some example)
          example: type=clightning;server=...
    GenericPaymentMethodData:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Whether the payment method is enabled
        paymentMethodId:
          $ref: '#/components/schemas/PaymentMethodId'
        config:
          type: object
          additionalProperties: false
          description: Associated dynamic data based on payment method type.
          oneOf:
          - $ref: '#/components/schemas/OnChainPaymentMethodBaseData'
          - $ref: '#/components/schemas/LightningNetworkPaymentMethodBaseData'
          - $ref: '#/components/schemas/LNURLPayPaymentMethodBaseData'
          - description: Any other unofficial payment method data
            type: object
            additionalProperties: true
    PaymentMethodId:
      type: string
      description: "Payment method IDs. Available payment method IDs for Bitcoin are:  \n- `\"BTC-CHAIN\"`: Onchain   \n-`\"BTC-LN\"`: Lightning   \n- `\"BTC-LNURL\"`: LNURL"
      example: BTC-CHAIN
    LNURLPayPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        useBech32Scheme:
          type: boolean
          description: 'Whether to use [LUD-01](https://github.com/fiatjaf/lnurl-rfc/blob/luds/01.md)''s bech32 format or to use [LUD-17](https://github.com/fiatjaf/lnurl-rfc/blob/luds/17.md) url formatting. '
        lud12Enabled:
          type: boolean
          description: Allow comments to be passed on via lnurl.
        lud21Enabled:
          type: boolean
          description: Whether to include a [LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) verify URL in LNURL-pay callback responses, enabling external services to verify payment settlement without authentication.
    UpdatePaymentMethodConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the payment method is enabled, leave null or unspecified to not change current setting
          default: null
          nullable: true
          example: true
        config:
          type: object
          description: The new payment method config, leave null or unspecified to not change current setting
          default: null
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/OnChainPaymentMethodBaseData'
          - $ref: '#/components/schemas/LightningNetworkPaymentMethodBaseData'
          - $ref: '#/components/schemas/LNURLPayPaymentMethodBaseData'
          - type: string
            title: Lightning connection string
            description: A lightning connection string or `Internal Node` (See [this documentation](https://github.com/btcpayserver/btcpayserver.lightning) for the format)
          - type: string
            title: Derivation scheme
            description: A derivation scheme in NBXplorer's format (See [this documentation](https://github.com/dgarage/NBXplorer/blob/master/docs/API.md#derivation-scheme) for the format)
          - type: string
            title: Output descriptor
            description: An output descriptor. Only a subset of them are supported. (See [this documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) for the format)
          - description: Any other unofficial payment method data
            type: object
            additionalProperties: true
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/