BTCPay Server Point of Sale API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Point of Sale API
  version: v1
  description: '# Introduction


    The 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.


    # Authentication


    You 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`.


    If you want to simplify the process of creating API keys for your users, you can use the Authorization endpoint 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 page.


    # Usage examples


    Use **Basic Auth** to read store information with cURL:

    ```bash

    BTCPAY_INSTANCE="https://mainnet.demo.btcpayserver.org"

    USER="MyTestUser@gmail.com"

    PASSWORD="notverysecurepassword"

    PERMISSION="btcpay.store.canmodifystoresettings"

    BODY="$(echo "{}" | jq --arg "a" "$PERMISSION" ''. + {permissions:[$a]}'')"


    API_KEY="$(curl -s \

    -H "Content-Type: application/json" \

    --user "$USER:$PASSWORD" \

    -X POST \

    -d "$BODY" \

    "$BTCPAY_INSTANCE/api/v1/api-keys" | jq -r .apiKey)"

    ```


    Use an **API key** to read store information with cURL:

    ```bash

    STORE_ID="yourStoreId"


    curl -s \

    -H "Content-Type: application/json" \

    -H "Authorization: token $API_KEY" \

    -X GET \

    "$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID"

    ```


    You can find more examples on our docs for different programming languages:

    - cURL

    - Javascript/Node.Js

    - PHP'
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: /
  description: BTCPay Server Greenfield API
security:
- API_Key: []
  Basic: []
tags:
- name: Point Of Sale
  description: Point of Sale operations
paths:
  /api/v1/apps/pos/{appId}:
    parameters:
    - $ref: '#/components/parameters/AppId'
    get:
      tags:
      - Point Of Sale
      operationId: Apps_GetPointOfSaleApp
      summary: Get Point of Sale app data
      description: Returns POS app data
      responses:
        '200':
          description: POS app data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PointOfSaleAppData'
        '404':
          description: POS app with specified ID was not found
components:
  schemas:
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    PointOfSaleAppData:
      allOf:
      - $ref: '#/components/schemas/PointOfSaleBaseData'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/AppItem'
            description: JSON object of app items
            example:
            - id: green tea
              title: Green Tea
              description: Lovely, fresh and tender, Meng Ding Gan Lu ('sweet dew') is grown in the lush Meng Ding Mountains of the southwestern province of Sichuan where it has been cultivated for over a thousand years.
              image: ~/img/pos-sample/green-tea.jpg
              price: '1.0'
              priceType: Fixed
              buyButtonText: null
              inventory: 5
              paymentMethods: null
              disabled: false
            - id: black tea
              title: Black Tea
              description: Tian Jian Tian Jian means 'heavenly tippy tea' in Chinese, and it describes the finest grade of dark tea. Our Tian Jian dark tea is from Hunan province which is famous for making some of the best dark teas available.
              image: ~/img/pos-sample/black-tea.jpg
              price: '2.0'
              priceType: Fixed
              buyButtonText: Test Buy Button Text
              inventory: null
              paymentMethods: null
              disabled: false
    AppItem:
      type: object
      properties:
        id:
          type: string
          example: green-tea
          description: Unique ID of the item
        title:
          type: string
          example: Green Tea
          description: The display name of the item
        description:
          type: string
          example: Lovely, fresh and tender.
          description: A description text for the item
        image:
          type: string
          example: http://teashop.com/img/green-tea.jpg
          description: An image URL for the item
        price:
          type:
          - string
          - 'null'
          format: decimal
          example: '21.0'
        priceType:
          type: string
          x-enumNames:
          - Fixed
          - Minimum
          - Topup
          enum:
          - Fixed
          - Minimum
          - Topup
        buyButtonText:
          type: string
          example: Buy me!
          description: A custom text for the buy button for the item
        inventory:
          type:
          - integer
          - 'null'
          example: 21
          description: The remaining stock the item
        disabled:
          type: boolean
          description: If true, the item does not appear in the list by default.
          default: false
    PointOfSaleBaseData:
      allOf:
      - $ref: '#/components/schemas/AppBaseData'
      - type: object
        properties:
          title:
            type:
            - string
            - 'null'
            description: Display title of the app
            example: My PoS app
          description:
            type:
            - string
            - 'null'
            description: App description
            example: This is my amazing PoS app
          defaultView:
            type:
            - string
            - 'null'
            description: App view type (e.g., static, cart, etc...)
            example: Cart
            x-enumNames:
            - Static
            - Cart
            - Light
            - Print
            enum:
            - Static
            - Cart
            - Light
            - Print
          showItems:
            type:
            - boolean
            - 'null'
            default: false
            description: Display item selection for keypad
            example: true
          showCustomAmount:
            type:
            - boolean
            - 'null'
            description: Whether the option to enter a custom amount is shown
            example: true
          showDiscount:
            default: false
            type:
            - boolean
            - 'null'
            description: Whether the option to enter a discount is shown
            example: false
          showSearch:
            type:
            - boolean
            - 'null'
            description: Display the search bar
            example: false
            default: true
          showCategories:
            type:
            - boolean
            - 'null'
            description: Display the list of categories
            example: false
            default: true
          enableTips:
            default: false
            type:
            - boolean
            - 'null'
            description: Whether the option to enter a tip is shown
            example: true
          currency:
            type:
            - string
            - 'null'
            description: Currency used for the app
            example: BTC
          fixedAmountPayButtonText:
            type:
            - string
            - 'null'
            description: Payment button text template for items with a set price
            example: Buy for {0}
          customAmountPayButtonText:
            type:
            - string
            - 'null'
            description: Payment button text which appears for items which allow user to input a custom amount
            example: Pay
          tipText:
            type:
            - string
            - 'null'
            description: Prompt which appears next to the tip amount field if tipping is enabled
            example: Do you want to leave a tip?
          customTipPercentages:
            type:
            - array
            - 'null'
            description: Array of predefined tip percentage amounts
            items:
              type: number
            default:
            - 15
            - 18
            - 20
          notificationUrl:
            type:
            - string
            - 'null'
            description: Deprecated. Use webhooks instead. Callback notification URL to POST to once when an invoice is paid and once when there are enough blockchain confirmations.
            deprecated: true
          redirectUrl:
            type:
            - string
            - 'null'
            description: URL user is redirected to once invoice is paid
          redirectAutomatically:
            type:
            - boolean
            - 'null'
            description: Whether user is redirected to specified redirect URL automatically after the invoice is paid
            example: true
          htmlLang:
            type:
            - string
            - 'null'
            description: Used for SEO, the [HTML Lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) of the page
            example: en
          htmlMetaTags:
            type:
            - string
            - 'null'
            description: Used for SEO, the [Meta tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) of the page
            example: <meta name="description" content="Your description">
          formId:
            type:
            - string
            - 'null'
            description: Form ID to request customer data
    AppBaseData:
      type: object
      properties:
        id:
          type: string
          description: Id of the app
          example: 3ki4jsAkN4u9rv1PUzj1odX4Nx7s
        appName:
          type: string
          description: Name given to the app when it was created
          example: my test app
        storeId:
          description: Id of the store to which the app belongs
          allOf:
          - $ref: '#/components/schemas/StoreId'
        created:
          type: integer
          example: 1651554744
          description: UNIX timestamp for when the app was created
        appType:
          type: string
          example: PointOfSale
          description: Type of the app which was created
        archived:
          type:
          - boolean
          - 'null'
          description: If true, the app does not appear in the apps list by default.
          default: false
  parameters:
    AppId:
      name: appId
      in: path
      required: true
      description: App ID
      schema:
        type: string
  securitySchemes:
    API_Key:
      type: apiKey
      description: "BTCPay Server supports authenticating and authorizing users through an API Key that is generated by them. Send the API Key as a header value to Authorization with the format: `token {token}`. For a smoother experience, you can generate a url that redirects users to an API key creation screen.\n\n The following permissions are available to the context of the user creating the API Key:\n\n* `btcpay.impersonation.canimpersonate`: Can impersonate users\n* `btcpay.user.candeleteuser`: Delete user\n* `btcpay.user.canmanagenotificationsforuser`: Manage your notifications\n* `btcpay.user.canmodifyprofile`: Manage your profile\n* `btcpay.user.canviewnotificationsforuser`: View your notifications\n* `btcpay.user.canviewprofile`: View your profile\n* `unrestricted`: Unrestricted access\n\nThe following permissions are available if the user is an administrator:\n\n* `btcpay.server.cancreatelightninginvoiceinternalnode`: Create invoices with internal lightning node\n* `btcpay.server.cancreateuser`: Create new users\n* `btcpay.server.canmanageusers`: Manage users\n* `btcpay.server.canmodifyserversettings`: Manage your server\n* `btcpay.server.canuseinternallightningnode`: Use the internal lightning node\n* `btcpay.server.canviewlightninginvoiceinternalnode`: View invoices from internal lightning node\n* `btcpay.server.canviewusers`: View users\n\nThe following permissions applies to all stores of the user, you can limit to a specific store with the following format: `btcpay.store.cancreateinvoice:6HSHAEU4iYWtjxtyRs9KyPjM9GAQp8kw2T9VWbGG1FnZ`:\n\n* `btcpay.store.canarchivepullpayments`: Archive your pull payments\n* `btcpay.store.canbroadcasttransactions`: Broadcast wallet transactions\n* `btcpay.store.cancanceltransactions`: Cancel wallet transactions\n* `btcpay.store.cancreateinvoice`: Create an invoice\n* `btcpay.store.cancreatelightninginvoice`: Create invoices from the lightning nodes associated with your stores\n* `btcpay.store.cancreatenonapprovedpullpayments`: Create non-approved pull payments\n* `btcpay.store.cancreatepullpayments`: Create pull payments\n* `btcpay.store.cancreatetransactions`: Create wallet transactions\n* `btcpay.store.cancreditsubscribers`: Credit your subscribers\n* `btcpay.store.canmanageinvoicestatus`: Manage invoice status\n* `btcpay.store.canmanagelegacyaccesstokens`: Manage legacy access tokens\n* `btcpay.store.canmanagepayouts`: Manage payouts\n* `btcpay.store.canmanagepullpayments`: Manage your pull payments\n* `btcpay.store.canmanagesubscribers`: Manage your subscribers\n* `btcpay.store.canmanagewallets`: Manage wallets\n* `btcpay.store.canmanagewalletsettings`: Manage wallet settings\n* `btcpay.store.canmanagewallettransactions`: Manage wallet transactions\n* `btcpay.store.canmodifyinvoices`: Modify invoices\n* `btcpay.store.canmodifyofferings`: Modify your offerings\n* `btcpay.store.canmodifypaymentrequests`: Modify your payment requests\n* `btcpay.store.canmodifystoresettings`: Modify your stores\n* `btcpay.store.cansendstoreemails`: Send store emails\n* `btcpay.store.cansigntransactions`: Sign wallet transactions\n* `btcpay.store.canuselightningnode`: Use the lightning nodes associated with your stores\n* `btcpay.store.canviewinvoices`: View invoices\n* `btcpay.store.canviewlightninginvoice`: View the lightning invoices associated with your stores\n* `btcpay.store.canviewofferings`: View your offerings\n* `btcpay.store.canviewpaymentrequests`: View your payment requests\n* `btcpay.store.canviewpayouts`: View payouts\n* `btcpay.store.canviewpullpayments`: View your pull payments\n* `btcpay.store.canviewreports`: View your reports\n* `btcpay.store.canviewstoresettings`: View your stores\n* `btcpay.store.canviewwallet`: View wallets\n* `btcpay.store.webhooks.canmodifywebhooks`: Modify stores webhooks\n\nNote that API Keys only limits permission of a user and can never expand it. If an API Key has the permission `btcpay.server.canmodifyserversettings` but that the user account creating this API Key is not administrator, the API Key will not be able to modify the server settings.\nSome permissions may include other permissions, see [this operation](#operation/permissionsMetadata).\n"
      name: Authorization
      in: header
    Basic:
      type: http
      description: BTCPay Server supports authenticating and authorizing users through the Basic HTTP authentication scheme during the first five minutes after account creation or when the user explicitly enables it. Send the user and password encoded in base64 with the format `Basic {base64(username:password)}`. Using this authentication method implicitly provides you with the `unrestricted` permission
      scheme: Basic
externalDocs:
  description: BTCPay Greenfield Plugins API
  url: https://docs.btcpayserver.org/API/Greenfield/Plugins/
x-provenance:
  method: harvested
  publisher: BTCPay Server
  source: https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)