BTCPay Server Stores (Payouts) API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Stores (Payouts) API
  version: v1
  description: '# Introduction


    The BTCPay Server Greenfield API is a REST API.'
  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
                  - 'null'
                  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:
    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
          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
          - 'null'
          format: decimal
          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
                - 'null'
                description: The source of the payout creation. Shown on the payout list page.
              sourceLink:
                type:
                - string
                - 'null'
                format: url
                description: A link to the source of the payout creation. Shown on the payout list page.
    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
    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'
    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
    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
            - 'null'
            format: url
            description: A link to the proof of payout payment.
      - properties:
          id:
            type:
            - string
            - 'null'
            description: A unique identifier to the proof of payout payment.
    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
            description: The json path of the property which failed validation
          message:
            type: string
            description: User friendly error message about the validation
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          description: An error code describing the error
        message:
          type: string
          description: User friendly error message about the error
    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'
  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/