BTCPay Server Stores (Payouts) API

openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Stores (Payouts) 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 (Payouts)
  description: Store pull payment payout operations
paths:
  /api/v1/stores/{storeId}/payouts:
    parameters:
    - $ref: '#/components/parameters/StoreId'
    post:
      summary: Create Payout
      description: Create a new payout
      operationId: Payouts_CreatePayoutThroughStore
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutThroughStoreRequest'
        required: true
        x-position: 1
      responses:
        '200':
          description: A new payout has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutData'
        '404':
          description: store not found
        '422':
          description: Unable to validate the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '400':
          description: 'Well-known error codes are: `duplicate-destination`, `expired`, `not-started`, `archived`, `overdraft`, `amount-too-low`, `payment-method-not-supported`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.cancreatepullpayments
        - btcpay.store.cancreatenonapprovedpullpayments
        Basic: []
    get:
      summary: Get Store Payouts
      operationId: PullPayments_GetStorePayouts
      description: Get payouts
      parameters:
      - name: includeCancelled
        in: query
        required: false
        description: Whether this should list cancelled payouts
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The payouts of the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutDataList'
        '404':
          description: Pull payment not found
      tags:
      - Stores (Payouts)
      security: []
  /api/v1/stores/{storeId}/payouts/{payoutId}:
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - name: payoutId
      in: path
      required: true
      description: The ID of the payout
      schema:
        type: string
    get:
      summary: Get Payout
      operationId: GetStorePayout
      description: Get payout
      responses:
        '200':
          description: A specific payout of a store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutData'
        '404':
          description: Payout not found
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.canmanagepullpayments
        Basic: []
    post:
      summary: Approve Payout
      operationId: PullPayments_ApprovePayout
      description: Approve a payout
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                revision:
                  type: integer
                  description: The revision number of the payout being modified
                rateRule:
                  type: string
                  nullable: true
                  example: kraken(BTC_USD)
                  description: The rate rule to calculate the rate of the payout. This can also be a fixed decimal. (if null or unspecified, will use the same rate setting as the store's settings)
      responses:
        '200':
          description: The payout has been approved, transitioning to `AwaitingPayment` state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutData'
        '422':
          description: Unable to validate the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '400':
          description: 'Well-known error codes are: `rate-unavailable`, `invalid-state`, `amount-too-low`, `old-revision`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The payout is not found
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.canmanagepullpayments
        Basic: []
    delete:
      summary: Cancel Payout
      description: Cancel the payout
      operationId: PullPayments_CancelPayout
      responses:
        '200':
          description: The payout has been cancelled
        '404':
          description: The payout is not found
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.canmanagepullpayments
        Basic: []
  /api/v1/stores/{storeId}/payouts/{payoutId}/mark-paid:
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - name: payoutId
      in: path
      required: true
      description: The ID of the payout
      schema:
        type: string
    post:
      summary: Mark Payout as Paid
      operationId: PullPayments_MarkPayoutPaid
      description: Mark a payout as paid
      responses:
        '200':
          description: The payout has been marked paid, transitioning to `Completed` state.
        '422':
          description: Unable to validate the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '400':
          description: 'Well-known error codes are: `invalid-state`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The payout is not found
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.canmanagepullpayments
        Basic: []
  /api/v1/stores/{storeId}/payouts/{payoutId}/mark:
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - name: payoutId
      in: path
      required: true
      description: The ID of the payout
      schema:
        type: string
    post:
      summary: Mark Payout
      operationId: PullPayments_MarkPayout
      description: Mark a payout with a state
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  $ref: '#/components/schemas/PayoutState'
                paymentProof:
                  $ref: '#/components/schemas/PayoutPaymentProof'
      responses:
        '200':
          description: The payout has been set to the specified state
        '422':
          description: Unable to validate the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '400':
          description: 'Well-known error codes are: `invalid-state`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: The payout is not found
      tags:
      - Stores (Payouts)
      security:
      - API_Key:
        - btcpay.store.canmanagepullpayments
        Basic: []
components:
  schemas:
    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
    PayoutDataList:
      type: array
      items:
        $ref: '#/components/schemas/PayoutData'
    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
    PayoutData:
      type: object
      properties:
        id:
          type: string
          description: The id of the payout
        revision:
          type: integer
          description: The revision number of the payout. This revision number is incremented when the payout amount or destination is modified before the approval.
        pullPaymentId:
          type: string
          description: The id of the pull payment this payout belongs to
        date:
          type: string
          description: The creation date of the payout as a unix timestamp
        destination:
          type: string
          example: 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
          description: The destination of the payout (can be an address or a BIP21 url)
        originalCurrency:
          type: string
          example: USD
          description: The currency before being converted into the payout's currency
        originalAmount:
          type: string
          format: decimal
          nullable: false
          example: '10399.18'
          description: The amount in originalCurrency before being converted into the payout's currency
        payoutCurrency:
          type: string
          example: BTC
          description: The currency of the payout after conversion.
        payoutAmount:
          type: string
          format: decimal
          nullable: true
          example: '1.12300000'
          description: The amount in payoutCurrency after conversion. (This property is set after the payout has been Approved)
        payoutMethodId:
          $ref: '#/components/schemas/PayoutMethodId'
        state:
          $ref: '#/components/schemas/PayoutState'
        paymentProof:
          $ref: '#/components/schemas/PayoutPaymentProof'
        metadata:
          type: object
          additionalProperties: true
          description: Additional information around the payout that can be supplied. The mentioned properties are all optional and you can introduce any json format you wish.
          example:
            source: Payout created through the API
          anyOf:
          - title: General information
            properties:
              source:
                type: string
                nullable: true
                description: The source of the payout creation. Shown on the payout list page.
              sourceLink:
                type: string
                format: url
                nullable: true
                description: A link to the source of the payout creation. Shown on the payout list page.
    PayoutPaymentProof:
      type: object
      additionalProperties: true
      description: Additional information around how the payout is being or has been paid out. The mentioned properties are all optional (except `proofType`) and you can introduce any json format you wish.
      properties:
        proofType:
          type: string
          description: The type of payment proof it is.
      anyOf:
      - properties:
          link:
            type: string
            format: url
            nullable: true
            description: A link to the proof of payout payment.
      - properties:
          id:
            type: string
            nullable: true
            description: A unique identifier to the proof of payout payment.
    PayoutState:
      type: string
      example: AwaitingPayment
      description: The state of the payout (`AwaitingApproval`, `AwaitingPayment`, `InProgress`, `Completed`, `Cancelled`)
      x-enumNames:
      - AwaitingApproval
      - AwaitingPayment
      - InProgress
      - Completed
      - Cancelled
      enum:
      - AwaitingApproval
      - AwaitingPayment
      - InProgress
      - Completed
      - Cancelled
    CreatePayoutRequest:
      type: object
      properties:
        destination:
          type: string
          example: 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
          description: The destination of the payout (can be an address or a BIP21 url)
        amount:
          type: string
          format: decimal
          example: '10399.18'
          description: The amount of the payout in the currency of the pull payment (eg. USD).
        payoutMethodId:
          $ref: '#/components/schemas/PayoutMethodId'
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    CreatePayoutThroughStoreRequest:
      allOf:
      - $ref: '#/components/schemas/CreatePayoutRequest'
      - type: object
        properties:
          pullPaymentId:
            type: string
            description: The pull payment to create this for. Optional.
          approved:
            type: boolean
            description: Whether to approve this payout automatically upon creation
          metadata:
            type: object
            description: Additional metadata to store with the payout
    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:
    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/