openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Invoices 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: Invoices
  description: Invoice operations
paths:
  /api/v1/stores/{storeId}/invoices:
    get:
      tags:
      - Invoices
      summary: Get invoices
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: orderId
        in: query
        required: false
        description: Array of OrderIds to fetch the invoices for
        schema:
          type: array
          items:
            type: string
        example: 1000&orderId=1001&orderId=1002
      - name: status
        in: query
        required: false
        description: Array of statuses of invoices to be fetched
        schema:
          $ref: '#/components/schemas/InvoiceStatus'
      - name: textSearch
        in: query
        required: false
        description: A term that can help locating specific invoices.
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        description: Start date of the period to retrieve invoices
        schema:
          $ref: '#/components/schemas/UnixTimestamp'
      - name: endDate
        in: query
        required: false
        description: End date of the period to retrieve invoices
        schema:
          $ref: '#/components/schemas/UnixTimestamp'
      - name: skip
        in: query
        required: false
        description: Number of records to skip
        schema:
          nullable: true
          type: number
      - name: take
        in: query
        required: false
        description: Number of records returned in response
        schema:
          nullable: true
          type: number
      - name: includePaymentMethods
        in: query
        required: false
        description: Includes payment methods available to the response
        schema:
          type: boolean
          default: false
      description: View information about the existing invoices
      operationId: Invoices_GetInvoices
      responses:
        '200':
          description: List of invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDataList'
        '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.canviewinvoices
        Basic: []
    post:
      tags:
      - Invoices
      summary: Create a new invoice
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Create a new invoice
      operationId: Invoices_CreateInvoice
      responses:
        '200':
          description: Information about the new invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceData'
        '400':
          description: A list of errors that occurred when creating the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to add new invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequest'
      security:
      - API_Key:
        - btcpay.store.cancreateinvoice
        Basic: []
  /api/v1/invoices/{invoiceId}:
    get:
      tags:
      - Invoices
      summary: Get invoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      description: View information about the specified invoice. The store is resolved automatically from the invoice.
      operationId: Invoices_GetInvoice
      responses:
        '200':
          description: specified invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceData'
        '403':
          description: If you are authenticated but forbidden to view the specified invoice
        '404':
          description: The key is not found for this invoice
      security:
      - API_Key:
        - btcpay.store.canviewinvoices
        Basic: []
    delete:
      tags:
      - Invoices
      summary: Archive invoice
      description: Archives the specified invoice. The store is resolved automatically from the invoice.
      operationId: Invoices_ArchiveInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: The invoice has been archived
        '400':
          description: A list of errors that occurred when archiving the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to archive the specified invoice
        '404':
          description: The key is not found for this invoice
      security:
      - API_Key:
        - btcpay.store.canmodifyinvoices
        Basic: []
    put:
      tags:
      - Invoices
      summary: Update invoice
      description: Updates the specified invoice. The store is resolved automatically from the invoice.
      operationId: Invoices_UpdateInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: The invoice that has been updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceData'
        '400':
          description: A list of errors that occurred when updating the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update the specified invoice
        '404':
          description: The key is not found for this invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvoiceRequest'
      security:
      - API_Key:
        - btcpay.store.canmodifyinvoices
        Basic: []
  /api/v1/invoices/{invoiceId}/payment-methods:
    get:
      tags:
      - Invoices
      summary: Get invoice payment methods
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      - name: onlyAccountedPayments
        in: query
        required: false
        description: If default or true, only returns payments which are accounted (in Bitcoin, this mean not returning RBF'd or double spent payments)
        schema:
          type: boolean
          default: true
      - name: includeSensitive
        in: query
        required: false
        description: If `true`, `additionalData` might include sensitive data (such as xpub). Requires the permission `btcpay.store.canmodifystoresettings`.
        schema:
          type: boolean
          default: false
      description: View information about the specified invoice's payment methods. The store is resolved automatically from the invoice.
      operationId: Invoices_GetInvoicePaymentMethods
      responses:
        '200':
          description: specified invoice payment methods data
          content:
            application/json:
              schema:
                type: array
                nullable: false
                items:
                  $ref: '#/components/schemas/InvoicePaymentMethodDataModel'
        '403':
          description: If you are authenticated but forbidden to view the specified invoice
        '404':
          description: The key is not found for this invoice
      security:
      - API_Key:
        - btcpay.store.canviewinvoices
        Basic: []
  /api/v1/invoices/{invoiceId}/status:
    post:
      tags:
      - Invoices
      summary: Mark invoice status
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      description: Mark an invoice as invalid or settled. The store is resolved automatically from the invoice.
      operationId: Invoices_MarkInvoiceStatus
      responses:
        '200':
          description: The updated invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceData'
        '400':
          description: A list of errors that occurred when updating the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update the invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkInvoiceStatusRequest'
      security:
      - API_Key:
        - btcpay.store.canmodifyinvoices
        Basic: []
  /api/v1/invoices/{invoiceId}/unarchive:
    post:
      tags:
      - Invoices
      summary: Unarchive invoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      description: Unarchive an invoice. The store is resolved automatically from the invoice.
      operationId: Invoices_UnarchiveInvoice
      responses:
        '200':
          description: The unarchived invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceData'
        '400':
          description: A list of errors that occurred when updating the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update the invoice
      security:
      - API_Key:
        - btcpay.store.canmodifyinvoices
        Basic: []
  /api/v1/invoices/{invoiceId}/payment-methods/{paymentMethodId}/activate:
    post:
      tags:
      - Invoices
      summary: Activate Payment Method
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Activate an invoice payment method (if lazy payments mode is enabled). The store is resolved automatically from the invoice.
      operationId: Invoices_ActivatePaymentMethod
      responses:
        '200':
          description: ''
        '400':
          description: A list of errors that occurred when updating the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to activate the invoice payment method
      security:
      - API_Key:
        - btcpay.store.canviewinvoices
        Basic: []
  /api/v1/invoices/{invoiceId}/refund:
    post:
      tags:
      - Invoices
      summary: Refund invoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      description: Refund invoice. The store is resolved automatically from the invoice.
      operationId: Invoices_Refund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundInvoiceRequest'
      responses:
        '200':
          description: Pull payment for refunding the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullPaymentData'
        '400':
          description: A list of errors that occurred when refunding the invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to refund the invoice
      security:
      - API_Key:
        - btcpay.store.cancreatepullpayments
        Basic: []
  /api/v1/invoices/{invoiceId}/refund/{paymentMethodId}:
    get:
      tags:
      - Invoices
      summary: Get invoice refund trigger data
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: View calculated refund amounts for the specified invoice/payment-method. The store is resolved automatically from the invoice.
      operationId: Invoices_GetInvoiceRefundTriggerData
      responses:
        '200':
          description: specified invoice refund trigger data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceRefundTriggerData'
        '403':
          description: If you are authenticated but forbidden to view the specified invoice
        '404':
          description: The key is not found for this invoice
      security:
      - API_Key:
        - btcpay.store.cancreatepullpayments
        Basic: []
components:
  schemas:
    CheckoutOptions:
      type: object
      additionalProperties: false
      properties:
        speedPolicy:
          type: string
          nullable: true
          allOf:
          - $ref: '#/components/schemas/SpeedPolicy'
        paymentMethods:
          type: array
          nullable: true
          items:
            type: string
          description: A specific set of payment methods to use for this invoice (ie. BTC, BTC-LightningNetwork). By default, select all payment methods enabled in the store.
        defaultPaymentMethod:
          allOf:
          - $ref: '#/components/schemas/PaymentMethodId'
          type: string
          nullable: true
          description: Default payment type for the invoice (e.g., BTC, BTC-LightningNetwork). Default payment method set for the store is used if this parameter is not specified.
        lazyPaymentMethods:
          type: boolean
          nullable: true
          description: If true, payment methods are enabled individually upon user interaction in the invoice. Default to store's settings'
        expirationMinutes:
          type: number
          nullable: true
          description: The number of minutes after which an invoice becomes expired. Defaults to the store's settings. (The default store settings is 15)
          allOf:
          - $ref: '#/components/schemas/TimeSpanMinutes'
        monitoringMinutes:
          type: number
          nullable: true
          description: The number of minutes after an invoice expired after which we are still monitoring for incoming payments. Defaults to the store's settings. (The default store settings is 1440, 1 day)
          allOf:
          - $ref: '#/components/schemas/TimeSpanMinutes'
        paymentTolerance:
          type: number
          format: double
          nullable: true
          minimum: 0.0
          maximum: 100.0
          default: 0.0
          description: A percentage determining whether to count the invoice as paid when the invoice is paid within the specified margin of error. Defaults to the store's settings. (The default store settings is 0)
        redirectURL:
          type: string
          nullable: true
          description: When the customer has paid the invoice, the URL where the customer will be redirected when clicking on the `return to store` button. You can use placeholders `{InvoiceId}` or `{OrderId}` in the URL, BTCPay Server will replace those with this invoice `id` or `metadata.orderId` respectively.
        redirectAutomatically:
          type: boolean
          nullable: true
          description: When the customer has paid the invoice, and a `redirectURL` is set, the checkout is redirected to `redirectURL` automatically if `redirectAutomatically` is true. Defaults to the store's settings. (The default store settings is false)
        defaultLanguage:
          type: string
          nullable: true
          description: The language code (eg. en-US, en, fr-FR...) of the language presented to your customer in the checkout page. BTCPay Server tries to match the best language available. If null or not set, will fallback on the store's default language. You can see the list of language codes with [this operation](#operation/langCodes).
    PaymentStatus:
      type: string
      description: The status of the payment
      x-enumNames:
      - Invalid
      - Processing
      - Settled
      enum:
      - Invalid
      - Processing
      - Settled
    InvoiceStatusMark:
      type: string
      description: ''
      x-enumNames:
      - Invalid
      - Settled
      enum:
      - Invalid
      - Settled
    Payment:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: A unique identifier for this payment
        receivedDate:
          description: The date the payment was recorded
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        value:
          type: string
          format: decimal
          description: The value of the payment
        fee:
          type: string
          format: decimal
          description: The fee paid for the payment
        status:
          $ref: '#/components/schemas/PaymentStatus'
        destination:
          type: string
          description: The destination the payment was made to
    InvoiceStatus:
      type: string
      description: The status of the invoice
      x-enumNames:
      - New
      - Processing
      - Expired
      - Invalid
      - Settled
      enum:
      - New
      - Processing
      - Expired
      - Invalid
      - Settled
    InvoiceMetadata:
      type: object
      additionalProperties: true
      description: Additional information around the invoice that can be supplied. The mentioned properties are all optional and you can introduce any json format you wish. See [our documentation](https://docs.btcpayserver.org/Development/InvoiceMetadata/) for more information.
      example:
        orderId: pos-app_346KRC5BjXXXo8cRFKwTBmdR6ZJ4
        orderUrl: https://localhost:14142/apps/346KRC5BjXXXo8cRFKwTBmdR6ZJ4/pos
        itemDesc: Tea shop
        posData:
          tip: 0.48
          cart:
          - id: pu erh
            count: 1
            image: ~/img/pos-sample/pu-erh.jpg
            price:
              type: 2
              value: 2
              formatted: $2.00
            title: Pu Erh
            inventory: null
          - id: rooibos
            count: 1
            image: ~/img/pos-sample/rooibos.jpg
            price:
              type: 2
              value: 1.2
              formatted: $1.20
            title: Rooibos
            inventory: null
          total: 3.68
          subTotal: 3.2
          customAmount: 0
          discountAmount: 0
          discountPercentage: 0
        receiptData:
          Tip: $0.48
          Cart:
            Pu Erh: $2.00 x 1 = $2.00
            Rooibos: $1.20 x 1 = $1.20
      anyOf:
      - title: Order information
        properties:
          orderId:
            type: string
            nullable: true
            description: Refers to the order ID from an external system, such as an e-commerce platform like WooCommerce. This property is indexed, allowing for efficient invoice searches using the `orderId`.
          orderUrl:
            type: string
            nullable: true
            description: Refers to a URL linking back to the order page of the external system. This link is displayed in the invoice details view.
          taxIncluded:
            type: number
            nullable: true
            description: Represents the tax amount in the invoice currency. This information will appear in the invoice details view. During invoice creation, the value is automatically rounded to significant digits and ensured not to be greater than the invoice's price.
          physical:
            type: string
            nullable: true
            description: Indicates if this is a physical good; displayed in the invoice details view and in the BitPay API-compatible endpoints.
      - title: Point of Sale (Cart view)
        properties:
          posData:
            type: object
            description: A custom JSON object that represents information displayed in the invoice details view.
      - title: Product information
        properties:
          itemDesc:
            type: string
            nullable: true
            description: When using the Point of Sale (except in keypad or cart view), this field is set to the item description of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view.
          itemCode:
            type: string
            nullable: true
            description: When using the Point of Sale (except in keypad or cart view), this field is set to the item code of the purchased item. This information is included in the CSV invoice export feature and appears in the invoice details view.
      - title: Payment request information
        properties:
          paymentRequestId:
            type: string
            nullable: true
            description: In the invoice details view, a link is provided for navigating to the payment request page associated with the invoice.
      - title: Buyer informations
        properties:
          buyerName:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerEmail:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerCountry:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerZip:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerState:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerCity:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerAddress1:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerAddress2:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
          buyerPhone:
            type: string
            description: Visible in the invoice details view and in the BitPay API-compatible endpoints.
            nullable: true
      - title: Receipt information
        properties:
          receiptData:
            type: object
            description: A custom JSON object that represents information displayed on the receipt page of an invoice.
            nullable: true
    InvoiceId:
      type: string
      description: The invoice ID
      example: HMprBnL9BTXWuPvpoKBS6e
    MarkInvoiceStatusRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          nullable: false
          description: Mark an invoice as completed or invalid.
          allOf:
          - $ref: '#/components/schemas/InvoiceStatusMark'
    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
    TimeSpanMinutes:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: minutes
      description: A span of times in minutes
    UpdateInvoiceRequest:
      type: object
      additionalProperties: false
      properties:
        metadata:
          $ref: '#/components/schemas/InvoiceMetadata'
    SpeedPolicy:
      type: string
      description: "This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency.\n`\"HighSpeed\"`: 0 confirmations (1 confirmation if RBF enabled in transaction)   \n`\"MediumSpeed\"`: 1 confirmation   \n`\"LowMediumSpeed\"`: 2 confirmations   \n`\"LowSpeed\"`: 6 confirmations\n"
      x-enumNames:
      - HighSpeed
      - MediumSpeed
      - LowSpeed
      - LowMediumSpeed
      enum:
      - HighSpeed
      - MediumSpeed
      - LowSpeed
      - LowMediumSpeed
    PullPaymentData:
      type: object
      properties:
        id:
          type: string
          description: Id of the pull payment
        name:
          type: string
          description: Name given to pull payment when it was created
        description:
          type: string
          description: Description given to pull payment when it was created
        currency:
          type: string
          example: BTC
          description: The currency of the pull payment's amount
        amount:
          type: string
          format: decimal
          example: '1.12000000'
          description: The amount in the currency of this pull payment as a decimal string
        BOLT11Expiration:
          type: string
          example: 30
          description: If lightning is activated, do not accept BOLT11 invoices with expiration less than … days
        autoApproveClaims:
          type: boolean
          example: false
          default: false
          nullable: true
          description: Any payouts created for this pull payment will skip the approval phase upon creation
        archived:
          type: boolean
          description: Whether this pull payment is archived
        viewLink:
          type: string
          description: The link to a page to claim payouts to this pull payment
    ReceiptOptions:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          nullable: true
          description: A public page will be accessible once the invoice is settled. If null or unspecified, it will fallback to the store's settings. (The default store settings is true)
        showQR:
          type: boolean
          nullable: true
          default: null
          description: Show the QR code of the receipt in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)
        showPayments:
          type: boolean
          nullable: true
          default: null
          description: Show the payment list in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    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
    TimeSpan:
      type: number
      format: int32
      example: 90
    InvoiceType:
      type: string
      description: The type of the invoice
      x-enumNames:
      - Standard
      - TopUp
      enum:
      - Standard
      - TopUp
    CreateInvoiceRequest:
      allOf:
      - $ref: '#/components/schemas/InvoiceDataBase'
      - type: object
        additionalProperties: false
        properties:
          amount:
            type: string
            format: decimal
            nullable: true
            description: The amount of the invoice. If null or unspecified, the invoice will be a top-up invoice. (ie. The invoice will consider any payment as a full payment)
            example: '5.00'
          currency:
            type: string
            description: The currency of the invoice (if null, empty or unspecified, the currency will be the store's settings default)'
            nullable: true
            example: USD
          additionalSearchTerms:
            type: array
            items:
              type: string
            description: Additional search term to help you find this invoice via text search
            nullable: true
    InvoiceDataBase:
      properties:
        metadata:
          $ref: '#/components/schemas/InvoiceMetadata'
        checkout:
          type: object
          nullable: true
          description: Additional settings to customize the checkout flow
          allOf:
          - $ref: '#/components/schemas/CheckoutOptions'
        receipt:
          type: object
          nullable: true
          description: Additional settings to customize the public receipt
          allOf:
          - $ref: '#/components/schemas/ReceiptOptions'
    InvoiceDataList:
      type: array
      items:
        allOf:
        - type: object
          properties:
            paymentMethods:
              type: array
              items:
                $ref: '#/components/schemas/InvoicePaymentMethodDataModel'
        - $ref: '#/components/schemas/InvoiceData'
    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
    InvoiceData:
      allOf:
      - $ref: '#/components/schemas/InvoiceDataBase'
      - type: object
        additionalProperties: false
        properties:
          id:
            $ref: '#/components/schemas/InvoiceId'
          storeId:
            description: The store identifier that the invoice belongs to
            allOf:
            - $ref: '#/components/schemas/StoreId'
          amount:
            type: string
            format: decimal
            description: The amount of the invoice. Note that the amount will be zero for a top-up invoice that is paid after invoice expiry.
            example: '5.00'
          paidAmount:
            type: string
            format: decimal
            description: The actual amount paid by the customer/buyer.
            example: '5.00'
          currency:
            type: string
            description: The currency of the invoice
            example: USD
          type:
            $ref: '#/components/schemas/InvoiceType'
          checkoutLink:
            type: string
            description: The link to the checkout page, where you can redirect the customer
          createdTime:
            description: The creation time of the invoice
            allOf:
            - $ref: '#/components/schemas/UnixTimestamp'
          expirationTime:
            description: The expiration time of the invoice
            allOf:
            - $ref: '#/components/schemas/UnixTimestamp'
          monitoringExpiration:
            description: Expiration time for monitoring of the invoice for any changes
            allOf:
            - $ref: '#/components/schemas/UnixTimestamp'
          status:
            $ref: '#/components/schemas/InvoiceStatus'
          additionalStatus:
            $ref: '#/components/schemas/InvoiceAdditionalStatus'
          availableStatusesForManualMarking:
            type: array
            description: The statuses the invoice can be manually marked as
            items:
              $ref: '#/components/schemas/InvoiceStatus'
          archived:
            type: boolean
            description: true if the invoice is archived
    InvoiceAdditionalStatus:
      type: string
      description: An additional status that describes why an invoice is in its current status.
      x-enumNames:
      - None
      - PaidLate
      - PaidPartial
      - Marked
      - Invalid
      - PaidOver
      enum:
      - None
      - PaidLate
      - PaidPartial
      - Marked
      - Invalid
      - PaidOver
    RefundInvoiceRequest:
      type: object
      additionalProperties: false
      required:
      - refundVariant
      properties:
        name:
          type: string
          description: 'Name of the pull payment (Default: ''Refund'' followed by the invoice id)'
          nullable: true
        description:
          type: string
          description: Description of the pull payment
        payoutMethodId:
          $ref: '#/components/schemas/PayoutMethodId'
        refundVariant:
          type: string
          description: "* `RateThen`: Refund the crypto currency price, at the rate the invoice got paid.\r\n* `CurrentRate`: Refund the crypto currency price, at the current rate.\r\n*`Fiat`: Refund the invoice currency, at the rate when the refund will be sent.\r\n*`OverpaidAmount`: Refund the crypto currency amount that was overpaid.\r\n*`Custom`: Specify the amount, currency, and rate of the refund. (see `customAmount` and `customCurrency`)"
          x-enumNames:
          - RateThen
          - CurrentRate
          - OverpaidAmount
          - Fiat
          - Custom
          enum:
          - RateThen
          - CurrentRate
          - OverpaidAmount
          - Fiat
          - Custom
        subtractPercentage:
          type: string
          format: decimal
          description: Optional percentage by which to reduce the refund, e.g. as processing charge or to compensate for the mining fee.
          example: '2.1'
        customAmount:
          type: string
          format: decimal
          description: The amount to refund if the `refundVariant` is `Custom`.
          example: '5.00'
        customCurrency:
          type: string
          description: The currency to refund if the `refundVariant` is `Custom`
          example: USD
    InvoiceRefundTriggerData:
      type: object
      additionalProperties: false
      properties:
        paymentAmountThen:
          type: string
          format: decimal
          description: The amount in crypto at the time the invoice was paid.
          example: '5.00'
        paymentAmountNow:
          type: string
          format: decimal
          description: The current amount in crypto.
          example: '5.00'
        invoiceAmount:
          type: string
          format: decimal
          description: The fiat amount at the rate when the refund will be sent.
          example: '5.00'
        paymentCurrency:
          type: string
          description: The crypto currency of the invoice
          example: BTC
        paymentCurrencyDivisibility:
          type: number
          description: The maximum divisibility supported by the crypto currency of the invoice
        invoiceCurrencyDivisibility:
          type: number
          description: The maximum divisibility supported by the fiat currency of the invoice
        invoiceCurrency:
          type: string
          description: The fiat currency of the invoice
          example: USD
        overpaidPaymentAmount:
          type: string
          format: decimal
          nullable: true
          description: The amount by which the invoice is overpaid
          example: '2.00'
    InvoicePaymentMethodDataModel:
      type: object
      additionalProperties: false
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/PaymentMethodId'
        currency:
          type: string
          description: The currency of the payment method (e.g., "BTC" or "LTC")
          example: BTC
        destination:
          type: string
          description: The destination the payment must be made to
        paymentLink:
          type: string
          nullable: true
          description: A payment link that helps pay to the payment destination
        rate:
          type: string
          format: decimal
          example: '64392.23'
          description: The rate between this payment method's currency and the invoice currency
        paymentMethodPaid:
          type: string
          format: decimal
          description: The amount paid by this payment method
        totalPaid:
          type: string
          format: decimal
          description: The total amount paid by all payment methods to the invoice, converted to this payment method's currency
        due:
          type: string
          format: decimal
          description: The total amount left to be paid, converted to this payment method's currency (will be negative if overpaid)
        amount:
          type: string
          format: decimal
          description: The invoice amount, converted to this payment method's currency
        paymentMethodFee:
          type: string
          format: decimal
          description: The added merchant fee to pay for additional costs incurred by this payment method.
        payments:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/Payment'
          description: Payments made with this payment method.
        activated:
          type: boolean
          description: If the payment method is activated (when lazy payments option is enabled
        additionalData:
          description: Additional data provided by the payment method.
          anyOf:
          - type: object
            title: '*-LNURL'
            description: LNURL Pay information
            properties:
              providedComment:
                type: string
                nullable: true
                description: The provided comment to a LNUrl payment with comments enabled
                example: Thank you!
              consumedLightningAddress:
                type: string
                nullable: true
                description: The consumed lightning address of a LN Address payment
                example: customer@example.com
          - type: object
            title: '*-CHAIN'
            description: Bitcoin On-Chain payment information
            properties:
              keyPath:
                type: string
                description: The key path relative to the account derviation key.
                example: 0/1
              payjoinEnabled:
                type: boolean
                description: If the payjoin feature is enabled for this payment method.
              accountDerivation:
                type: string
                description: The derivation scheme used to derive addresses (null if `includeSensitive` is `false`)
                example: xpub6DVMcQAQCtGbNDTEjQGtR1GRoTKw7AzP6bVivX4gFnewcnRk1r1tbczpfsaYjKKVrmtyiwYqAEnALYzZ8yoTArVsKfZekmwLFqQp4MRgPhy
              recommendedFeeRate:
                type: string
                format: decimal
                description: The recommended fee rate for this payment method.
                example: '4.107'
              paymentMethodFeeRate:
                type: string
                format: decimal
                description: The fee rate charged to the user as `PaymentMethodFee`.
                example: '3.975'
          - type: object
            description: No additional information
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            nullable: false
            description: The json path of the property which failed validation
          message:
            type: string
            nullable: false
            description: User friendly error message about the validation
  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'
    InvoiceId:
      name: invoiceId
      in: path
      required: true
      description: The invoice ID
      schema:
        $ref: '#/components/schemas/InvoiceId'
  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/