openapi: 3.0.0
info:
  title: Stripe Payouts API
  description: >-
    A Payout object is created when you receive funds from Stripe, or when you
    initiate a payout to either a bank account or debit card of a connected
    Stripe account. You can retrieve individual payouts, and list all payouts.
    Payouts are made on varying schedules, depending on your country and
    industry.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
security:
  - basicAuth: []
  - bearerAuth: []
servers:
  - url: https://api.stripe.com/
paths:
  /v1/payouts:
    get:
      description: >-
        <p>Returns a list of existing payouts sent to third-party bank accounts
        or payouts that Stripe sent to you. The payouts return in sorted order,
        with the most recently created payouts appearing first.</p>
      operationId: getPayouts
      parameters:
        - explode: true
          in: query
          name: arrival_date
          required: false
          schema:
            anyOf:
              - properties:
                  gt:
                    type: integer
                  gte:
                    type: integer
                  lt:
                    type: integer
                  lte:
                    type: integer
                title: range_query_specs
                type: object
              - type: integer
          style: deepObject
        - explode: true
          in: query
          name: created
          required: false
          schema:
            anyOf:
              - properties:
                  gt:
                    type: integer
                  gte:
                    type: integer
                  lt:
                    type: integer
                  lte:
                    type: integer
                title: range_query_specs
                type: object
              - type: integer
          style: deepObject
        - description: >-
            The ID of an external account - only return payouts sent to this
            external account.
          in: query
          name: destination
          required: false
          schema:
            type: string
          style: form
        - description: >-
            A cursor for use in pagination. `ending_before` is an object ID that
            defines your place in the list. For instance, if you make a list
            request and receive 100 objects, starting with `obj_bar`, your
            subsequent call can include `ending_before=obj_bar` in order to
            fetch the previous page of the list.
          in: query
          name: ending_before
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - description: >-
            A limit on the number of objects to be returned. Limit can range
            between 1 and 100, and the default is 10.
          in: query
          name: limit
          required: false
          schema:
            type: integer
          style: form
        - description: >-
            A cursor for use in pagination. `starting_after` is an object ID
            that defines your place in the list. For instance, if you make a
            list request and receive 100 objects, ending with `obj_foo`, your
            subsequent call can include `starting_after=obj_foo` in order to
            fetch the next page of the list.
          in: query
          name: starting_after
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
        - description: >-
            Only return payouts that have the given status: `pending`, `paid`,
            `failed`, or `canceled`.
          in: query
          name: status
          required: false
          schema:
            maxLength: 5000
            type: string
          style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPayoutsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                  - data
                $ref: '#/components/schemas/PayoutList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Payouts
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Get
        - Payouts
    post:
      description: >-
        <p>To send funds to your own bank account, create a new payout object.
        Your <a href="#balance">Stripe balance</a> must cover the payout amount.
        If it doesn’t, you receive an “Insufficient Funds” error.</p>


        <p>If your API key is in test mode, money won’t actually be sent, though
        every other action occurs as if you’re in live mode.</p>


        <p>If you create a manual payout on a Stripe account that uses multiple
        payment source types, you need to specify the source type balance that
        the payout draws from. The <a href="#balance_object">balance object</a>
        details available and pending amounts by source type.</p>
      operationId: postPayouts
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPayoutsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payouts
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Payouts
        - Post
  /v1/payouts/{payout}:
    get:
      description: >-
        <p>Retrieves the details of an existing payout. Supply the unique payout
        ID from either a payout creation request or the payout list. Stripe
        returns the corresponding payout information.</p>
      operationId: getPayoutsPayout
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
        - in: path
          name: payout
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPayoutsPayoutRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Payouts
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Get
        - Payouts
    post:
      description: >-
        <p>Updates the specified payout by setting the values of the parameters
        you pass. We don’t change parameters that you don’t provide. This
        request only accepts the metadata as arguments.</p>
      operationId: postPayoutsPayout
      parameters:
        - in: path
          name: payout
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPayoutsPayoutRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payouts
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Payouts
        - Post
  /v1/payouts/{payout}/cancel:
    post:
      description: >-
        <p>You can cancel a previously created payout if it hasn’t been paid out
        yet. Stripe refunds the funds to your available balance. You can’t
        cancel automatic Stripe payouts.</p>
      operationId: postPayoutsPayoutCancel
      parameters:
        - in: path
          name: payout
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPayoutsPayoutCancelRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payouts Cancel
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Cancel
        - Payouts
        - Post
  /v1/payouts/{payout}/reverse:
    post:
      description: >-
        <p>Reverses a payout by debiting the destination bank account. At this
        time, you can only reverse payouts for connected accounts to US bank
        accounts. If the payout is in the <code>pending</code> status, use
        <code>/v1/payouts/:id/cancel</code> instead.</p>


        <p>By requesting a reversal through
        <code>/v1/payouts/:id/reverse</code>, you confirm that the authorized
        signatory of the selected bank account authorizes the debit on the bank
        account and that no other authorization is required.</p>
      operationId: postPayoutsPayoutReverse
      parameters:
        - in: path
          name: payout
          required: true
          schema:
            maxLength: 5000
            type: string
          style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPayoutsPayoutReverseRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payout'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payouts Reverse
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
        - Payouts
        - Post
        - Reverse
components:
  schemas:
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
        - error
      type: object
    payout:
      description: >-
        A `Payout` object is created when you receive funds from Stripe, or when
        you

        initiate a payout to either a bank account or debit card of a [connected

        Stripe account](/docs/connect/bank-debit-card-payouts). You can retrieve
        individual payouts,

        and list all payouts. Payouts are made on [varying

        schedules](/docs/connect/manage-payout-schedule), depending on your
        country and

        industry.


        Related guide: [Receiving payouts](https://stripe.com/docs/payouts)
      properties:
        amount:
          description: >-
            The amount (in cents (or local equivalent)) that transfers to your
            bank account or debit card.
          type: integer
        arrival_date:
          description: >-
            Date that you can expect the payout to arrive in the bank. This
            factors in delays to account for weekends or bank holidays.
          format: unix-time
          type: integer
        automatic:
          description: >-
            Returns `true` if the payout is created by an [automated payout
            schedule](https://stripe.com/docs/payouts#payout-schedule) and
            `false` if it's [requested
            manually](https://stripe.com/docs/payouts#manual-payouts).
          type: boolean
        balance_transaction:
          anyOf:
            - maxLength: 5000
              type: string
            - $ref: '#/components/schemas/balance_transaction'
          description: >-
            ID of the balance transaction that describes the impact of this
            payout on your account balance.
          nullable: true
          x-expansionResources:
            oneOf:
              - $ref: '#/components/schemas/balance_transaction'
        created:
          description: >-
            Time at which the object was created. Measured in seconds since the
            Unix epoch.
          format: unix-time
          type: integer
        currency:
          description: >-
            Three-letter [ISO currency
            code](https://www.iso.org/iso-4217-currency-codes.html), in
            lowercase. Must be a [supported
            currency](https://stripe.com/docs/currencies).
          type: string
        description:
          description: >-
            An arbitrary string attached to the object. Often useful for
            displaying to users.
          maxLength: 5000
          nullable: true
          type: string
        destination:
          anyOf:
            - maxLength: 5000
              type: string
            - $ref: '#/components/schemas/bank_account'
            - $ref: '#/components/schemas/card'
            - $ref: '#/components/schemas/deleted_bank_account'
            - $ref: '#/components/schemas/deleted_card'
          description: ID of the bank account or card the payout is sent to.
          nullable: true
          x-expansionResources:
            oneOf:
              - $ref: '#/components/schemas/bank_account'
              - $ref: '#/components/schemas/card'
              - $ref: '#/components/schemas/deleted_bank_account'
              - $ref: '#/components/schemas/deleted_card'
          x-stripeBypassValidation: true
        failure_balance_transaction:
          anyOf:
            - maxLength: 5000
              type: string
            - $ref: '#/components/schemas/balance_transaction'
          description: >-
            If the payout fails or cancels, this is the ID of the balance
            transaction that reverses the initial balance transaction and
            returns the funds from the failed payout back in your balance.
          nullable: true
          x-expansionResources:
            oneOf:
              - $ref: '#/components/schemas/balance_transaction'
        failure_code:
          description: >-
            Error code that provides a reason for a payout failure, if
            available. View our [list of failure
            codes](https://stripe.com/docs/api#payout_failures).
          maxLength: 5000
          nullable: true
          type: string
        failure_message:
          description: Message that provides the reason for a payout failure, if available.
          maxLength: 5000
          nullable: true
          type: string
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        livemode:
          description: >-
            Has the value `true` if the object exists in live mode or the value
            `false` if the object exists in test mode.
          type: boolean
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: >-
            Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
            you can attach to an object. This can be useful for storing
            additional information about the object in a structured format.
          nullable: true
          type: object
        method:
          description: >-
            The method used to send this payout, which can be `standard` or
            `instant`. `instant` is supported for payouts to debit cards and
            bank accounts in certain countries. Learn more about [bank support
            for Instant
            Payouts](https://stripe.com/docs/payouts/instant-payouts-banks).
          maxLength: 5000
          type: string
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - payout
          type: string
        original_payout:
          anyOf:
            - maxLength: 5000
              type: string
            - $ref: '#/components/schemas/payout'
          description: >-
            If the payout reverses another, this is the ID of the original
            payout.
          nullable: true
          x-expansionResources:
            oneOf:
              - $ref: '#/components/schemas/payout'
        reconciliation_status:
          description: >-
            If `completed`, you can use the [Balance Transactions
            API](https://stripe.com/docs/api/balance_transactions/list#balance_transaction_list-payout)
            to list all balance transactions that are paid out in this payout.
          enum:
            - completed
            - in_progress
            - not_applicable
          type: string
        reversed_by:
          anyOf:
            - maxLength: 5000
              type: string
            - $ref: '#/components/schemas/payout'
          description: >-
            If the payout reverses, this is the ID of the payout that reverses
            this payout.
          nullable: true
          x-expansionResources:
            oneOf:
              - $ref: '#/components/schemas/payout'
        source_type:
          description: >-
            The source balance this payout came from, which can be one of the
            following: `card`, `fpx`, or `bank_account`.
          maxLength: 5000
          type: string
        statement_descriptor:
          description: >-
            Extra information about a payout that displays on the user's bank
            statement.
          maxLength: 5000
          nullable: true
          type: string
        status:
          description: >-
            Current status of the payout: `paid`, `pending`, `in_transit`,
            `canceled` or `failed`. A payout is `pending` until it's submitted
            to the bank, when it becomes `in_transit`. The status changes to
            `paid` if the transaction succeeds, or to `failed` or `canceled`
            (within 5 business days). Some payouts that fail might initially
            show as `paid`, then change to `failed`.
          maxLength: 5000
          type: string
        type:
          description: Can be `bank_account` or `card`.
          enum:
            - bank_account
            - card
          type: string
          x-stripeBypassValidation: true
      required:
        - amount
        - arrival_date
        - automatic
        - created
        - currency
        - id
        - livemode
        - method
        - object
        - reconciliation_status
        - source_type
        - status
        - type
      title: Payout
      type: object
      x-expandableFields:
        - balance_transaction
        - destination
        - failure_balance_transaction
        - original_payout
        - reversed_by
      x-resourceId: payout
    GetPayoutsRequest:
      type: object
      properties: {}
    PayoutList:
      type: object
      required:
        - data
        - has_more
        - object
        - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/payout'
          type: array
        has_more:
          description: >-
            True if this list has another page of items after this one that can
            be fetched.
          type: boolean
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value. Always has the value `list`.
          enum:
            - list
          type: string
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          pattern: ^/v1/payouts
          type: string
    PostPayoutsRequest:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          description: A positive integer in cents representing how much to payout.
          type: integer
        currency:
          description: >-
            Three-letter [ISO currency
            code](https://www.iso.org/iso-4217-currency-codes.html), in
            lowercase. Must be a [supported
            currency](https://stripe.com/docs/currencies).
          type: string
        description:
          description: >-
            An arbitrary string attached to the object. Often useful for
            displaying to users.
          maxLength: 5000
          type: string
        destination:
          description: >-
            The ID of a bank account or a card to send the payout to. If you
            don't provide a destination, we use the default external account for
            the specified currency.
          type: string
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        metadata:
          additionalProperties:
            type: string
          description: >-
            Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
            you can attach to an object. This can be useful for storing
            additional information about the object in a structured format.
            Individual keys can be unset by posting an empty value to them. All
            keys can be unset by posting an empty value to `metadata`.
          type: object
        method:
          description: >-
            The method used to send this payout, which is `standard` or
            `instant`. We support `instant` for payouts to debit cards and bank
            accounts in certain countries. Learn more about [bank support for
            Instant
            Payouts](https://stripe.com/docs/payouts/instant-payouts-banks).
          enum:
            - instant
            - standard
          maxLength: 5000
          type: string
          x-stripeBypassValidation: true
        source_type:
          description: >-
            The balance type of your Stripe balance to draw this payout from.
            Balances for different payment sources are kept separately. You can
            find the amounts with the Balances API. One of `bank_account`,
            `card`, or `fpx`.
          enum:
            - bank_account
            - card
            - fpx
          maxLength: 5000
          type: string
          x-stripeBypassValidation: true
        statement_descriptor:
          description: >-
            A string that displays on the recipient's bank or card statement (up
            to 22 characters). A `statement_descriptor` that's longer than 22
            characters return an error. Most banks truncate this information and
            display it inconsistently. Some banks might not display it at all.
          maxLength: 22
          type: string
          x-stripeBypassValidation: true
    GetPayoutsPayoutRequest:
      type: object
      properties: {}
    PostPayoutsPayoutRequest:
      type: object
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - enum:
                - ''
              type: string
          description: >-
            Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
            you can attach to an object. This can be useful for storing
            additional information about the object in a structured format.
            Individual keys can be unset by posting an empty value to them. All
            keys can be unset by posting an empty value to `metadata`.
    PostPayoutsPayoutCancelRequest:
      type: object
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    PostPayoutsPayoutReverseRequest:
      type: object
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        metadata:
          additionalProperties:
            type: string
          description: >-
            Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
            you can attach to an object. This can be useful for storing
            additional information about the object in a structured format.
            Individual keys can be unset by posting an empty value to them. All
            keys can be unset by posting an empty value to `metadata`.
          type: object
  securitySchemes:
    basicAuth:
      description: >-
        Basic HTTP authentication. Allowed headers-- Authorization: Basic
        <api_key> | Authorization: Basic <base64 hash of `api_key:`>
      scheme: basic
      type: http
    bearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
tags:
  - name: Cancel
  - name: Get
  - name: Payouts
  - name: Post
  - name: Reverse