openapi: 3.0.3
info:
  title: Paypal Payouts
  description: Use the Payouts API to make payments to multiple PayPal or Venmo recipients. The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. You can send up to 15,000 payments per call. If you integrated the Payouts API before September 1, 2017, you receive transaction reports through <a href="/docs/archive/mass-pay/integration-guide/MassPayReporting/">Mass Payments Reporting</a>. Otherwise, <a href="/docs/payouts/features/view-reports/">view reports from your PayPal Business account</a>. The Payouts API uses the <a href="https://tools.ietf.org/html/rfc3339#section-5.6">ISO 8601 Internet date and time format</a>.
  version: '1.9'
  contact: {}
servers:
  - url: https://api-m.sandbox.paypal.com
    description: PayPal Sandbox Environment
  - url: https://api-m.paypal.com
    description: PayPal Live Environment
tags:
  - name: Payouts
    description: Use the `/payouts` resource to create a batch payout, update the status for a batch payout, show the status of a batch payout with the transaction status and other data for individual payout items, and request approval for a batch payout.
  - name: Payouts-Item
    description: Use the `/payouts-item` resource to show payout item details and cancel an unclaimed payout item.
externalDocs:
  url: https://developer.paypal.com/docs/api/payments.payouts-batch/v1/
paths:
  "/v1/payments/payouts":
    post:
      summary: Paypal Create batch payout
      description: Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.<br/>You can make payouts to one or more recipients.<blockquote><strong>Notes:</strong> <ul><li><p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>.</p></li><li><p>The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the <code>PayPal-Partner-Attribution-Id</code> request header.</p><p>For information about the <code>PayPal-Partner-Attribution-Id</code> header, see <a href="/api/rest/requests/#http-request-headers">HTTP request headers</a>. To learn about or request a BN code, contact your partner manager or see <a href="https://www.paypal.com/us/webapps/mpp/partner-program">PayPal Partner Program</a>.</p></li></ul></blockquote>
      operationId: payouts.post
      responses:
        '201':
          description: A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the ID for the payout and payout details. To show payout status, use the <code>payout_batch_id</code> value that appears in the response. If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the <code>batch_status</code> is <code>PENDING</code>. The initial scan checks for syntax errors and missing or duplicated keywords. The API does not immediately validate some payout item values, such as the receiver phone numbers.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payout"
        '400':
          description: Request is not well-formed, syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Authorization failed due to insufficient permissions.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/paypal_request_id"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_payout_request"
            examples:
              create_payout_request:
                value:
                  sender_batch_header:
                    sender_batch_id: Payouts_2018_100007
                    email_subject: You have a payout!
                    email_message: You have received a payout! Thanks for using our service!
                  items:
                    - recipient_type: EMAIL
                      amount:
                        value: '9.87'
                        currency: USD
                      note: Thanks for your patronage!
                      sender_item_id: '201403140001'
                      receiver: receiver@example.com
                      alternate_notification_method:
                        phone:
                          country_code: '91'
                          national_number: '9999988888'
                      notification_language: fr-FR
                    - recipient_type: PHONE
                      amount:
                        value: '112.34'
                        currency: USD
                      note: Thanks for your support!
                      sender_item_id: '201403140002'
                      receiver: 91-734-234-1234
                    - recipient_type: PAYPAL_ID
                      amount:
                        value: '5.32'
                        currency: USD
                      note: Thanks for your patronage!
                      sender_item_id: '201403140003'
                      receiver: G83JXTJ5EHCQ2
      security:
        - Oauth2:
            - https://uri.paypal.com/payments/payouts
      tags:
        - Payouts
  "/v1/payments/payouts/{id}":
    get:
      summary: Paypal Show payout batch details
      description: Shows the latest status of a batch payout. Includes the transaction status and other data for individual payout items.
      operationId: payouts.get
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows batch payout details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payout_batch"
        '404':
          description: Resource Not Found.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/id"
        - "$ref": "#/components/parameters/fields"
        - "$ref": "#/components/parameters/page"
        - "$ref": "#/components/parameters/page_size"
        - "$ref": "#/components/parameters/total_required"
      security:
        - Oauth2:
            - https://uri.paypal.com/payments/payouts
      tags:
        - Payouts
  "/v1/payments/payouts-item/{payout_item_id}":
    get:
      summary: Paypal Show payout item details
      description: Shows details for a payout item, by ID. A <code>payout_item_id</code> helps you identify denied payments. If a payment is denied, you can use the <code>payout_item_id</code> to identify the payment even if it lacks a <code>transaction_id</code>.
      operationId: payouts-item.get
      responses:
        '200':
          description: A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body with a <code>payout_item_details</code> object, which contains data about a payout item including the transaction status.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payout_item-2"
        '404':
          description: Resource Not Found.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/payout_item_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/payments/payouts
      tags:
        - Payouts-Item
  "/v1/payments/payouts-item/{payout_item_id}/cancel":
    post:
      summary: Paypal Cancel unclaimed payout item
      description: Cancels an unclaimed payout item, by ID. If no one claims the unclaimed item within 30 days, the API automatically returns the funds to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund. You can cancel payout items with a <code>transaction_status</code> of <code>UNCLAIMED</code>.
      operationId: payouts-item.cancel
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code with a JSON response body that shows payout item details.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/payout_item-2"
        '400':
          description: Request is not well-formed, syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Resource Not Found.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      parameters:
        - "$ref": "#/components/parameters/payout_item_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/payments/payouts
      tags:
        - Payouts-Item
components:
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: "/v1/oauth2/token"
          scopes:
            https://uri.paypal.com/payments/payouts: Payout to a list of recipients.
            https://uri.paypal.com/services/payments/payouts-item/reverse: For reversing a completed payout item.
  schemas:
    error_details:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          "$ref": "#/components/schemas/error_location"
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
      required:
        - issue
    error_location:
      type: string
      description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
      enum:
        - body
        - path
        - query
      default: body
    error_link_description:
      title: Link Description
      description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
      type: object
      required:
        - href
        - rel
      properties:
        href:
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          type: string
          minLength: 0
          maxLength: 20000
          pattern: "^.*$"
        rel:
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          type: string
          minLength: 0
          maxLength: 100
          pattern: "^.*$"
        method:
          description: The HTTP method required to make the related call.
          type: string
          minLength: 3
          maxLength: 6
          pattern: "^[A-Z]*$"
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - PATCH
    error_400:
      type: object
      title: Bad Request Error
      description: Request is not well-formed, syntactically incorrect, or violates schema.
      properties:
        name:
          type: string
          enum:
            - INVALID_REQUEST
        message:
          type: string
          enum:
            - Request is not well-formed, syntactically incorrect, or violates schema.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_401:
      type: object
      title: Unauthorized Error
      description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
      properties:
        name:
          type: string
          enum:
            - AUTHENTICATION_FAILURE
        message:
          type: string
          enum:
            - Authentication failed due to missing authorization header, or invalid authentication credentials.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_403:
      type: object
      title: Not Authorized Error
      description: 'The client is not authorized to access this resource, although it may have valid credentials. '
      properties:
        name:
          type: string
          enum:
            - NOT_AUTHORIZED
        message:
          type: string
          enum:
            - Authorization failed due to insufficient permissions.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_404:
      type: object
      title: Not found Error
      description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
      properties:
        name:
          type: string
          enum:
            - RESOURCE_NOT_FOUND
        message:
          type: string
          enum:
            - The specified resource does not exist.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_409:
      type: object
      title: Resource Conflict Error
      description: The server has detected a conflict while processing this request.
      properties:
        name:
          type: string
          enum:
            - RESOURCE_CONFLICT
        message:
          type: string
          enum:
            - The server has detected a conflict while processing this request.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_415:
      type: object
      title: Unsupported Media Type Error
      description: The server does not support the request payload's media type.
      properties:
        name:
          type: string
          enum:
            - UNSUPPORTED_MEDIA_TYPE
        message:
          type: string
          enum:
            - The server does not support the request payload's media type.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_422:
      type: object
      title: Unprocessable Entity Error
      description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
      properties:
        name:
          type: string
          enum:
            - UNPROCESSABLE_ENTITY
        message:
          type: string
          enum:
            - The requested action could not be performed, semantically incorrect, or failed business validation.
        details:
          type: array
          items:
            "$ref": "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
    error_500:
      type: object
      title: Internal Server Error
      description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
      properties:
        name:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
        message:
          type: string
          enum:
            - An internal server error occurred.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
      example:
        name: INTERNAL_SERVER_ERROR
        message: An internal server error occurred.
        debug_id: 90957fca61718
        links:
          - href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
            rel: information_link
    error_503:
      type: object
      title: Service Unavailable Error
      description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
      properties:
        name:
          type: string
          enum:
            - SERVICE_UNAVAILABLE
        message:
          type: string
          enum:
            - Service Unavailable.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            "$ref": "#/components/schemas/error_link_description"
      example:
        name: SERVICE_UNAVAILABLE
        message: Service Unavailable.
        debug_id: 90957fca61718
        information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
    sender_batch_header:
      type: object
      title: Sender Batch Header
      description: The sender-provided payout header for a payout request.
      properties:
        sender_batch_id:
          type: string
          description: A sender-specified ID number. Tracks the payout in an accounting system.<blockquote><strong>Note:</strong> <p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>. The API completes a payment only once for a <code>sender_batch_id</code> that is used within 30 days.</p></blockquote>
          minLength: 0
          maxLength: 256
          pattern: "^.*$"
        recipient_type:
          type: string
          description: The ID type that identifies the recipient of the payment. For example, <code>EMAIL</code>.
          minLength: 0
          maxLength: 13
          pattern: "^.*$"
        email_subject:
          type: string
          description: The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.
          minLength: 0
          maxLength: 255
          pattern: "^.*$"
        email_message:
          type: string
          description: The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
          minLength: 0
          maxLength: 1000
          pattern: "^.*$"
        note:
          type: string
          description: The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.
          minLength: 0
          maxLength: 1000
          pattern: "^.*$"
    currency:
      type: object
      title: Currency
      description: The currency and amount for a financial transaction, such as a balance or payment due.
      properties:
        currency:
          type: string
          description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/).
        value:
          type: string
          description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).
      required:
        - currency
        - value
    phone:
      type: object
      title: Phone
      description: The phone number in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
      properties:
        country_code:
          type: string
          description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
          minLength: 1
          maxLength: 3
          pattern: "^[0-9]{1,3}?$"
        national_number:
          type: string
          description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
          minLength: 1
          maxLength: 14
          pattern: "^[0-9]{1,14}?$"
        extension_number:
          type: string
          description: The extension number.
          minLength: 1
          maxLength: 15
          pattern: "^[0-9]{1,15}?$"
      required:
        - country_code
        - national_number
    alternate_notification_method:
      type: object
      title: Alternate Notification Method
      description: Captures additional notification modes to reach out to the receiver regarding this payment.
      properties:
        phone:
          description: The mobile phone number of the receiver.
          "$ref": "#/components/schemas/phone"
    language:
      type: string
      description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
      format: ppaas_common_language_v3
      maxLength: 10
      minLength: 2
      pattern: "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$"
    application_context:
      type: object
      title: Application Context
      description: Metadata for Venmo transactions.
      properties:
        social_feed_privacy:
          type: string
          default: PRIVATE
          description: This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to `PRIVATE` if left blank.
          minLength: 1
          maxLength: 15
          pattern: "^.*$"
        holler_url:
          type: string
          description: Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.
          format: uri
          minLength: 1
          maxLength: 1000
          deprecated: true
        logo_url:
          type: string
          description: 'Link to a logo that displays as the sender''s profile image in the recipient''s Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.'
          format: uri
          minLength: 0
          maxLength: 1000
    purpose_enum:
      type: string
      title: Purpose
      description: The purpose of the transaction.
      minLength: 1
      maxLength: 40
      pattern: "^[A-Z0-9_]+$"
      enum:
        - AWARDS
        - PRIZES
        - DONATIONS
        - GOODS
        - SERVICES
        - REBATES
        - CASHBACK
        - DISCOUNTS
        - NON_GOODS_OR_SERVICES
    payout_item:
      type: object
      title: Payout Item
      description: The sender-created payout to a recipient.
      properties:
        recipient_type:
          type: string
          description: The recipient type. Value is:<ul><li><p><code>EMAIL</code>. The unencrypted email. Value is a string of up to 127 single-byte characters.</p></li><li><p><code>PHONE</code>. The unencrypted phone number.</p><blockquote><strong>Note:</strong> The PayPal sandbox does not support the <code>PHONE</code> recipient type.</blockquote></li><li><p><code>PAYPAL_ID</code>. The encrypted PayPal account number.</p></li><li><p><code>USER_HANDLE</code>. User handle (or) Username associated with Venmo account.</p></li></ul><br/>If the <code>sender_batch_header</code> includes the <code>recipient_type</code> attribute, payout items use the <code>recipient_type</code> of the <code>sender_batch_header</code>, unless a payout item has its own <code>recipient_type</code> attribute. If the <code>sender_batch_header</code> omits the <code>recipient_type</code> attribute, each payout item must include its own <code>recipient_type</code> value.
          minLength: 0
          maxLength: 13
          pattern: "^.*$"
        amount:
          description: The currency and amount to pay the receiver.
          "$ref": "#/components/schemas/currency"
        note:
          type: string
          description: The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
          minLength: 0
          maxLength: 4000
          pattern: "^.*$"
        receiver:
          type: string
          description: The receiver of the payment. Corresponds to the `recipient_type` value in the request. Max value of up to 127 single-byte characters.
          minLength: 0
          maxLength: 127
          pattern: "^.*$"
        sender_item_id:
          type: string
          description: The sender-specified ID number. Tracks the payout in an accounting system.
          minLength: 0
          maxLength: 63
          pattern: "^.*$"
        recipient_wallet:
          type: string
          description: The recipient wallet.
          default: PAYPAL
          minLength: 0
          maxLength: 36
          pattern: "^.*$"
        alternate_notification_method:
          description: Captures additional notification modes to reach out to the receiver regarding this payment.
          "$ref": "#/components/schemas/alternate_notification_method"
        notification_language:
          "$ref": "#/components/schemas/language"
          description: The language in which to show the payout recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.
        application_context:
          description: Metadata for accepting additional information from merchants to Venmo.
          "$ref": "#/components/schemas/application_context"
        purpose:
          description: The purpose of the transaction.
          "$ref": "#/components/schemas/purpose_enum"
      required:
        - amount
        - receiver
    create_payout_request:
      type: object
      title: Create Payout Request
      description: The create payout request.
      properties:
        sender_batch_header:
          description: The sender-provided payout header for a payout request.
          "$ref": "#/components/schemas/sender_batch_header"
        items:
          type: array
          description: An array of individual payout items.
          maxItems: 15000
          minItems: 1
          items:
            "$ref": "#/components/schemas/payout_item"
      required:
        - sender_batch_header
        - items
    error_details-2:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          type: string
          description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
          default: body
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
      required:
        - issue
    link_description:
      type: object
      title: Link Description
      description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
      required:
        - href
        - rel
      properties:
        href:
          type: string
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
        rel:
          type: string
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - HEAD
            - CONNECT
            - OPTIONS
            - PATCH
    error:
      type: object
      title: Error
      description: The error details.
      properties:
        name:
          type: string
          description: The human-readable, unique name of the error.
        message:
          type: string
          description: The message that describes the error.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        information_link:
          type: string
          description: The information link, or URI, that shows detailed information about this error for the developer.
          readOnly: true
        details:
          type: array
          description: An array of additional details about the error.
          items:
            "$ref": "#/components/schemas/error_details-2"
        links:
          type: array
          description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
          readOnly: true
          items:
            "$ref": "#/components/schemas/link_description"
            readOnly: true
      required:
        - name
        - message
        - debug_id
    batch_enum:
      title: Batch status
      description: The payouts status.
      type: string
      minLength: 1
      maxLength: 36
      pattern: "^[0-9A-Z_]+$"
      enum:
        - DENIED
        - PENDING
        - PROCESSING
        - SUCCESS
        - CANCELED
    recipient_enum:
      title: Recipient type
      description: The ID type that identifies the payment receiver.
      type: string
      minLength: 1
      maxLength: 36
      pattern: "^[0-9A-Z_]+$"
      enum:
        - EMAIL
        - PHONE
        - PAYPAL_ID
    payout_sender_batch_header:
      type: object
      title: Payout Sender Batch Header
      description: The sender-provided header for a payout request.
      properties:
        sender_batch_id:
          type: string
          description: The sender-specified ID number. Tracks the payout in an accounting system.<blockquote><strong>Note:</strong> <p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>. The API completes a payment only once for a <code>sender_batch_id</code> that is used within 30 days.</p></blockquote>
          minLength: 0
          maxLength: 256
          pattern: "^.*$"
        recipient_type:
          "$ref": "#/components/schemas/recipient_enum"
        email_subject:
          type: string
          description: The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string with a maximum length of 255 single-byte characters.
          minLength: 0
          maxLength: 255
          pattern: "^.*$"
        email_message:
          type: string
          description: The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
          minLength: 0
          maxLength: 1000
          pattern: "^.*$"
    payout_header:
      type: object
      title: Payout Header
      description: The payout header that is returned in response to a payout header request. Shows details for an entire payout request.
      properties:
        payout_batch_id:
          type: string
          description: The PayPal-generated ID for a payout.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        batch_status:
          description: The PayPal-generated payout status. If the payout passes preliminary checks, the status is `PENDING`.
          "$ref": "#/components/schemas/batch_enum"
        time_created:
          type: string
          format: date-time
          minLength: 0
          maxLength: 100
          description: The date and time when processing for the payout began, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
        sender_batch_header:
          description: The original payout header, as provided by the payment sender.
          "$ref": "#/components/schemas/payout_sender_batch_header"
      required:
        - batch_status
        - payout_batch_id
        - sender_batch_header
    payout:
      type: object
      title: Create Payout Response
      description: The create payout response.
      properties:
        batch_header:
          description: The payout header.
          "$ref": "#/components/schemas/payout_header"
        links:
          type: array
          description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
          readOnly: true
          items:
            "$ref": "#/components/schemas/link_description"
          minItems: 1
          maxItems: 15000
    funding_source:
      title: Funding source
      description: Identifies a funding source type.
      type: string
      minLength: 1
      maxLength: 36
      pattern: "^[0-9A-Z_]+$"
      enum:
        - BALANCE
    payout_batch_header:
      type: object
      title: Payout Batch Header
      description: The payout header that is returned in response to a payout header request. Shows details for an entire payout request.
      properties:
        payout_batch_id:
          type: string
          description: The PayPal-generated ID for a payout.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        batch_status:
          description: The PayPal-generated payout status. If the payout passes preliminary checks, the status is `PENDING`.
          "$ref": "#/components/schemas/batch_enum"
        time_created:
          type: string
          format: date-time
          minLength: 0
          maxLength: 100
          description: The date and time when processing for the payout began, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
        time_completed:
          type: string
          format: date-time
          description: The date and time when processing for the payout was completed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
          minLength: 0
          maxLength: 100
        time_closed:
          type: string
          format: date-time
          description: The date and time when the payout was closed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). A payout is considered closed when all items in a batch are processed and the available balance from the temporary hold is released.
          minLength: 0
          maxLength: 100
        sender_batch_header:
          description: The original payout header, as provided by the payment sender.
          "$ref": "#/components/schemas/payout_sender_batch_header"
        funding_source:
          description: The ID to differentiate a PayPal balance-funded transaction from a PayPal treasury-funded transaction.
          "$ref": "#/components/schemas/funding_source"
        amount:
          description: The currency and total amount requested for the payouts.
          "$ref": "#/components/schemas/currency"
        fees:
          description: The currency and amount of the total estimate for the applicable payouts fees. Initially, the fee is `0`. The fee is populated after the payout moves to the `PROCESSING` state.
          "$ref": "#/components/schemas/currency"
      required:
        - payout_batch_id
        - batch_status
        - sender_batch_header
    transaction_enum:
      title: Transaction status
      description: The item transaction status.<blockquote><strong>Note:</strong> For <code>POST/v1/payments/payouts-item/{payout_item_id}/cancel</code>, the only possible <code>transaction_status</code> value is <code>RETURNED</code>.</blockquote>
      type: string
      minLength: 1
      maxLength: 36
      pattern: "^[0-9A-Z_]+$"
      enum:
        - SUCCESS
        - FAILED
        - PENDING
        - UNCLAIMED
        - RETURNED
        - ONHOLD
        - BLOCKED
        - REFUNDED
        - REVERSED
    name:
      type: object
      title: Name
      description: The name of the party.
      properties:
        prefix:
          type: string
          description: The prefix, or title, to the party's name.
          maxLength: 140
        given_name:
          type: string
          description: When the party is a person, the party's given, or first, name.
          maxLength: 140
        surname:
          type: string
          description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
          maxLength: 140
        middle_name:
          type: string
          description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
          maxLength: 140
        suffix:
          type: string
          description: The suffix for the party's name.
          maxLength: 140
        alternate_full_name:
          type: string
          description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
          maxLength: 300
        full_name:
          type: string
          description: When the party is a person, the party's full name.
          maxLength: 300
    recipient_wallet_enum:
      title: Recipient wallet
      description: The wallet where the recipient receives the payout. Payouts to Venmo recipients require a 'note' string and a US mobile phone number.
      type: string
      default: PAYPAL
      minLength: 1
      maxLength: 36
      pattern: "^[0-9A-Z_]+$"
      enum:
        - PAYPAL
        - VENMO
        - RECIPIENT_SELECTED
    payout_item_detail:
      type: object
      title: Payout Item Detail
      description: The details for a sender-created payout to a single recipient.
      properties:
        recipient_type:
          "$ref": "#/components/schemas/recipient_enum"
        amount:
          description: The currency and amount of payout item. Might be an integer for currencies like `JPY` that are not typically fractional or a decimal fraction for currencies like `TND` that are subdivided into thousandths. For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).
          "$ref": "#/components/schemas/currency"
        note:
          type: string
          description: The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
          minLength: 0
          maxLength: 4000
          pattern: "^.*$"
        receiver:
          type: string
          description: The receiver of the payment. Corresponds to the `recipient_type` value in the request.
          minLength: 0
          maxLength: 127
          pattern: "^.*$"
        sender_item_id:
          type: string
          description: A sender-specified ID number. Tracks the payout in an accounting system.
          minLength: 0
          maxLength: 63
          pattern: "^.*$"
        recipient_name:
          description: The name of the recipient where money is credited. For `UNCLAIMED` payments, the recipient name is populated after the payment is claimed.
          "$ref": "#/components/schemas/name"
        recipient_wallet:
          description: The recipient wallet.
          "$ref": "#/components/schemas/recipient_wallet_enum"
        purpose:
          description: The purpose of the transaction.
          "$ref": "#/components/schemas/purpose_enum"
      required:
        - amount
        - receiver
    payout_currency_conversion:
      type: object
      title: Currency conversion resource
      description: The currency conversion resource.
      properties:
        from_amount:
          "$ref": "#/components/schemas/currency"
          description: The amount that is converted from.
        to_amount:
          "$ref": "#/components/schemas/currency"
          description: The amount that is converted to.
        exchange_rate:
          type: string
          description: The exchange rate that is applied for this payout.
          pattern: "^.*$"
          minLength: 0
          maxLength: 30
    payout_batch_items:
      type: object
      title: Payout Item
      description: The payout item status and other details.
      properties:
        payout_item_id:
          type: string
          description: The ID for the payout item. Viewable when you show details for a payout.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        transaction_id:
          type: string
          description: The PayPal-generated ID for the transaction.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        activity_id:
          type: string
          description: The unique PayPal-generated common ID created to link sender side and receiver side transaction. Used for tracking.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        transaction_status:
          "$ref": "#/components/schemas/transaction_enum"
        payout_item_fee:
          description: The fee, in U.S. dollars.
          "$ref": "#/components/schemas/currency"
        payout_batch_id:
          type: string
          description: The PayPal-generated ID for the payout.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        payout_item:
          description: The sender-provided information for the payout item.
          "$ref": "#/components/schemas/payout_item_detail"
        currency_conversion:
          description: The currency conversion applicable for this payout item.
          "$ref": "#/components/schemas/payout_currency_conversion"
        time_processed:
          type: string
          format: date-time
          minLength: 0
          maxLength: 100
          description: The date and time when this item was last processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
        errors:
          "$ref": "#/components/schemas/error"
        links:
          type: array
          description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
          readOnly: true
          items:
            "$ref": "#/components/schemas/link_description"
          minItems: 0
          maxItems: 15000
      required:
        - payout_item_id
        - payout_batch_id
        - payout_item
    payout_batch:
      type: object
      title: Payout Batch
      description: The PayPal-generated batch status.
      properties:
        total_items:
          description: The total number of items in the full result list.
          type: integer
          minimum: 0
          maximum: 15000
        total_pages:
          description: The total number of pages.
          type: integer
          minimum: 0
          maximum: 1000
        batch_header:
          description: A payout header. Includes the generated payout status.
          "$ref": "#/components/schemas/payout_batch_header"
        items:
          type: array
          description: An array of individual items.
          items:
            "$ref": "#/components/schemas/payout_batch_items"
          minItems: 0
          maxItems: 15000
        links:
          type: array
          description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
          readOnly: true
          items:
            "$ref": "#/components/schemas/link_description"
          minItems: 0
          maxItems: 15000
    payout_item-2:
      type: object
      title: Payout Item
      description: The payout item status and other details. A <code>payout_item_id</code> helps you identify denied payments. If a payment is denied, you can use the <code>payout_item_id</code> to identify the payment even if it lacks a <code>transaction_id</code>.
      properties:
        payout_item_id:
          type: string
          description: The ID for the payout item. Visible when you show details for a payout.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        transaction_id:
          type: string
          description: The PayPal-generated ID for the transaction.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        activity_id:
          type: string
          description: The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        transaction_status:
          "$ref": "#/components/schemas/transaction_enum"
        payout_item_fee:
          description: The estimate for the payout fee. Initially, the fee is `0`. The fee is populated after the item moves to the `PENDING` state
          "$ref": "#/components/schemas/currency"
        payout_batch_id:
          type: string
          description: The PayPal-generated ID for the payout batch.
          minLength: 0
          maxLength: 30
          pattern: "^.*$"
        sender_batch_id:
          type: string
          description: A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
          minLength: 0
          maxLength: 256
          pattern: "^.*$"
        payout_item:
          description: The sender-provided information for the payout item.
          "$ref": "#/components/schemas/payout_item_detail"
        currency_conversion:
          description: The currency conversion applicable for this payout item.
          "$ref": "#/components/schemas/payout_currency_conversion"
        time_processed:
          type: string
          format: date-time
          description: The date and time when this item was last processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
          minLength: 1
          maxLength: 100
        errors:
          "$ref": "#/components/schemas/error"
          description: The error details.
        links:
          type: array
          description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
          readOnly: true
          items:
            "$ref": "#/components/schemas/link_description"
          minItems: 0
          maxItems: 15000
      required:
        - payout_item_id
        - payout_batch_id
        - payout_item
  parameters:
    paypal_request_id:
      name: PayPal-Request-Id
      in: header
      description: The server stores keys for 30 days.
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 1000
        pattern: "^.*$"
    id:
      name: id
      in: path
      description: The ID of the payout for which to show details.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 1000
        pattern: "^.*$"
    fields:
      name: fields
      in: query
      description: Shows details for only the specified fields.
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 1000
        pattern: "^.*$"
    page:
      name: page
      in: query
      description: A non-zero integer representing the page of the results.
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1000
        default: 1
    page_size:
      name: page_size
      in: query
      description: The maximum number of results to return at one time. Value is a non-negative, non-zero integer. If the user chooses pagination, the maximum page is `1000`.
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 1000
    total_required:
      name: total_required
      in: query
      description: Indicates whether to show the total items and total pages count in the response.
      schema:
        type: boolean
        default: false
    payout_item_id:
      name: payout_item_id
      in: path
      description: The ID of the payout item to cancel.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 32
        pattern: "^.*$"