openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Stores (Payout Processors) 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: Stores (Payout Processors)
  description: Stores (Payout Processors) operations
paths:
  /api/v1/stores/{storeId}/payout-processors:
    get:
      tags:
      - Stores (Payout Processors)
      summary: Get store configured payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Get store configured payout processors
      operationId: StorePayoutProcessors_GetStorePayoutProcessors
      responses:
        '200':
          description: configured payout processors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayoutProcessorData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/payout-processors/{processor}/{paymentMethodId}:
    delete:
      tags:
      - Stores (Payout Processors)
      summary: Remove store configured payout processor
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: processor
        in: path
        required: true
        description: The processor
        schema:
          type: string
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Remove store configured payout processor
      operationId: StorePayoutProcessors_RemoveStorePayoutProcessor
      responses:
        '200':
          description: removed
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedPayoutSenderFactory/{paymentMethodId}:
    get:
      tags:
      - Stores (Payout Processors)
      summary: Get configured store onchain automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Get configured store onchain automated payout processors
      operationId: GreenfieldStoreAutomatedOnChainPayoutProcessorsController_GetStoreOnChainAutomatedPayoutProcessorsForPaymentMethod
      responses:
        '200':
          description: configured processors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnChainAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Stores (Payout Processors)
      summary: Update configured store onchain automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Update configured store onchain automated payout processors
      operationId: GreenfieldStoreAutomatedOnChainPayoutProcessorsController_UpdateStoreOnChainAutomatedPayoutProcessorForPaymentMethod
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOnChainAutomatedTransferSettings'
        required: true
        x-position: 1
      responses:
        '200':
          description: configured processor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/payout-processors/LightningAutomatedPayoutSenderFactory/{payoutMethodId}:
    get:
      tags:
      - Stores (Payout Processors)
      summary: Get configured store Lightning automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PayoutMethodId'
      description: Get configured store Lightning automated payout processors
      operationId: GreenfieldStoreAutomatedLightningPayoutProcessorsController_GetStoreLightningAutomatedPayoutProcessorsForPaymentMethod
      responses:
        '200':
          description: configured processors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LightningAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Stores (Payout Processors)
      summary: Update configured store Lightning automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PayoutMethodId'
      description: Update configured store Lightning automated payout processors
      operationId: GreenfieldStoreAutomatedLightningPayoutProcessorsController_UpdateStoreLightningAutomatedPayoutProcessor
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLightningAutomatedTransferSettings'
        required: true
        x-position: 1
      responses:
        '200':
          description: configured processor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LightningAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/payout-processors/OnChainAutomatedTransferSenderFactory:
    get:
      tags:
      - Stores (Payout Processors)
      summary: Get configured store onchain automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Get configured store onchain automated payout processors
      operationId: GreenfieldStoreAutomatedOnChainPayoutProcessorsController_GetStoreOnChainAutomatedTransferSenderFactory
      responses:
        '200':
          description: configured processors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnChainAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Stores (Payout Processors)
      summary: Update configured store onchain automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Update configured store onchain automated payout processors
      operationId: GreenfieldStoreAutomatedOnChainPayoutProcessorsController_UpdateStoreOnChainAutomatedTransferSenderFactory
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOnChainAutomatedTransferSettings'
        required: true
        x-position: 1
      responses:
        '200':
          description: configured processor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/payout-processors/LightningAutomatedPayoutSenderFactory:
    get:
      tags:
      - Stores (Payout Processors)
      summary: Get configured store Lightning automated payout processors
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Get configured store Lightning automated payout processors
      operationId: GreenfieldStoreAutomatedLightningPayoutProcessorsController_GetStoreLightningAutomatedPayoutSenderFactory
      responses:
        '200':
          description: configured processors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LightningAutomatedTransferSettings'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
components:
  schemas:
    LightningAutomatedTransferSettings:
      type: object
      additionalProperties: false
      properties:
        payoutMethodId:
          $ref: '#/components/schemas/PayoutMethodId'
        intervalSeconds:
          description: How often should the processor run
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        cancelPayoutAfterFailures:
          description: How many failures should the processor tolerate before cancelling the payout
          type: number
          nullable: true
        processNewPayoutsInstantly:
          description: Skip the interval when ane eligible payout has been approved (or created with pre-approval)
          type: boolean
          default: false
    TimeSpanSeconds:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: seconds
      description: A span of times in seconds
    UpdateLightningAutomatedTransferSettings:
      type: object
      additionalProperties: false
      properties:
        intervalSeconds:
          description: How often should the processor run
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        cancelPayoutAfterFailures:
          description: How many failures should the processor tolerate before cancelling the payout
          type: number
          nullable: true
        processNewPayoutsInstantly:
          description: Skip the interval when ane eligible payout has been approved (or created with pre-approval)
          type: boolean
          default: false
    OnChainAutomatedTransferSettings:
      type: object
      additionalProperties: false
      properties:
        payoutMethodId:
          $ref: '#/components/schemas/PayoutMethodId'
        feeTargetBlock:
          type: number
          description: How many blocks should the fee rate calculation target to confirm in.
        intervalSeconds:
          description: How often should the processor run
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        threshold:
          type: string
          format: decimal
          minimum: 0
          description: Only process payouts when this payout sum is reached.
          example: '0.1'
        processNewPayoutsInstantly:
          description: Skip the interval when ane eligible payout has been approved (or created with pre-approval)
          type: boolean
          default: false
    TimeSpan:
      type: number
      format: int32
      example: 90
    PayoutMethodId:
      type: string
      description: "Payout method IDs. Available payment method IDs for Bitcoin are:  \n- `\"BTC-CHAIN\"`: Onchain   \n-`\"BTC-LN\"`: Lightning"
      example: BTC-LN
    UpdateOnChainAutomatedTransferSettings:
      type: object
      additionalProperties: false
      properties:
        feeTargetBlock:
          type: number
          description: How many blocks should the fee rate calculation target to confirm in. Set to 1 if not provided
          nullable: true
        intervalSeconds:
          description: How often should the processor run
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        threshold:
          type: string
          format: decimal
          minimum: 0
          description: Only process payouts when this payout sum is reached.
          example: '0.1'
        processNewPayoutsInstantly:
          description: Skip the interval when ane eligible payout has been approved (or created with pre-approval)
          type: boolean
          default: false
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    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
    PayoutProcessorData:
      type: object
      additionalProperties: false
      properties:
        name:
          description: unique identifier of the payout processor
          type: string
        friendlyName:
          description: Human name of the payout processor
          type: string
        payoutMethods:
          nullable: true
          description: Supported, payment methods by this processor
          type: array
          items:
            type: string
  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
    PayoutMethodId:
      name: payoutMethodId
      in: path
      required: true
      description: The payout method id
      schema:
        $ref: '#/components/schemas/PayoutMethodId'
      example: BTC-CHAIN
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  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/