openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Capture API
  description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  version: '1.6'
  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: Capture
paths:
  /v1/billing/subscriptions/{id}/capture:
    post:
      summary: Capture authorized payment on subscription
      description: Captures an authorized payment from the subscriber on the subscription.
      operationId: subscriptions.capture
      responses:
        '200':
          description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
        '202':
          description: Request Accepted.
        '400':
          description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_400'
                - $ref: '#/components/schemas/subscriptions.capture-400'
        '401':
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_401'
                - $ref: '#/components/schemas/401'
        '403':
          description: Authorization failed due to insufficient permissions.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_403'
                - $ref: '#/components/schemas/403'
        '404':
          description: The specified resource does not exist.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_404'
                - $ref: '#/components/schemas/404'
        '422':
          description: The requested action could not be performed, semantically incorrect, or failed business validation.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/error_422'
                - $ref: '#/components/schemas/subscriptions.capture-422'
        '500':
          description: An internal server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_500'
        default:
          $ref: '#/components/responses/default'
      parameters:
      - $ref: '#/components/parameters/paypal_request_id'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription_capture_request'
            examples:
              subscription_capture_request:
                value:
                  note: Charging as the balance reached the limit
                  capture_type: OUTSTANDING_BALANCE
                  amount:
                    currency_code: USD
                    value: '100'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/subscriptions
      tags:
      - Capture
components:
  schemas:
    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'
    '403':
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: PERMISSION_DENIED
              properties:
                issue:
                  type: string
                  enum:
                  - PERMISSION_DENIED
                description:
                  type: string
                  enum:
                  - You do not have permission to access or perform operations on this resource.
    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_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_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
    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
    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
    subscriptions.capture-422:
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: USER_ACCOUNT_CLOSED
              properties:
                issue:
                  type: string
                  enum:
                  - USER_ACCOUNT_CLOSED
                description:
                  type: string
                  enum:
                  - User account locked or closed.
            - title: SUBSCRIBER_ACCOUNT_LOCKED
              properties:
                issue:
                  type: string
                  enum:
                  - SUBSCRIBER_ACCOUNT_LOCKED
                description:
                  type: string
                  enum:
                  - Subscriber Account Locked.
            - title: SUBSCRIBER_ACCOUNT_CLOSED
              properties:
                issue:
                  type: string
                  enum:
                  - SUBSCRIBER_ACCOUNT_CLOSED
                description:
                  type: string
                  enum:
                  - Subscriber Account Closed.
            - title: SUBSCRIBER_ACCOUNT_RESTRICTED
              properties:
                issue:
                  type: string
                  enum:
                  - SUBSCRIBER_ACCOUNT_RESTRICTED
                description:
                  type: string
                  enum:
                  - Subscriber Account Restricted.
            - title: SUBSCRIPTION_STATUS_INVALID
              properties:
                issue:
                  type: string
                  enum:
                  - SUBSCRIPTION_STATUS_INVALID
                description:
                  type: string
                  enum:
                  - Invalid subscription status for capture action; subscription status should be active or suspended or expired.
            - title: ZERO_OUTSTANDING_BALANCE
              properties:
                issue:
                  type: string
                  enum:
                  - ZERO_OUTSTANDING_BALANCE
                description:
                  type: string
                  enum:
                  - Current outstanding balance should be greater than zero.
            - title: CURRENCY_MISMATCH
              properties:
                issue:
                  type: string
                  enum:
                  - CURRENCY_MISMATCH
                description:
                  type: string
                  enum:
                  - The currency code is different from the subscription's currency code.
            - title: AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE
              properties:
                issue:
                  type: string
                  enum:
                  - AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE
                description:
                  type: string
                  enum:
                  - The capture amount can not be greater than the current outstanding balance.
    transaction:
      title: Transaction Details
      description: The transaction details.
      type: object
      allOf:
      - $ref: '#/components/schemas/capture_status'
      - properties:
          id:
            type: string
            description: The PayPal-generated transaction ID.
            minLength: 3
            maxLength: 50
            readOnly: true
          amount_with_breakdown:
            $ref: '#/components/schemas/amount_with_breakdown'
          payer_name:
            description: The name of the customer.
            readOnly: true
            $ref: '#/components/schemas/name'
          payer_email:
            description: The email ID of the customer.
            readOnly: true
            $ref: '#/components/schemas/email_address'
          time:
            description: The date and time when the transaction was processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
            readOnly: true
            $ref: '#/components/schemas/date_time'
      required:
      - id
      - amount_with_breakdown
      - time
    error_default:
      description: The default error response.
      oneOf:
      - $ref: '#/components/schemas/error_400'
      - $ref: '#/components/schemas/error_401'
      - $ref: '#/components/schemas/error_403'
      - $ref: '#/components/schemas/error_404'
      - $ref: '#/components/schemas/error_409'
      - $ref: '#/components/schemas/error_415'
      - $ref: '#/components/schemas/error_422'
      - $ref: '#/components/schemas/error_500'
      - $ref: '#/components/schemas/error_503'
    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
    money:
      type: object
      title: Money
      description: The currency and amount for a financial transaction, such as a balance or payment due.
      properties:
        currency_code:
          $ref: '#/components/schemas/currency_code'
        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](/docs/integration/direct/rest/currency-codes/).
          maxLength: 32
          pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
      required:
      - currency_code
      - value
    capture_status_details:
      title: Capture Status Details
      description: The details of the captured payment status.
      type: object
      properties:
        reason:
          description: The reason why the captured payment status is `PENDING` or `DENIED`.
          type: string
          enum:
          - BUYER_COMPLAINT
          - CHARGEBACK
          - ECHECK
          - INTERNATIONAL_WITHDRAWAL
          - OTHER
          - PENDING_REVIEW
          - RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
          - REFUNDED
          - TRANSACTION_APPROVED_AWAITING_FUNDING
          - UNILATERAL
          - VERIFICATION_REQUIRED
    amount_with_breakdown:
      type: object
      title: Amount with Breakdown
      description: The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
      properties:
        gross_amount:
          description: The amount for this transaction.
          readOnly: true
          $ref: '#/components/schemas/money'
        total_item_amount:
          description: The item total for the transaction.
          readOnly: true
          $ref: '#/components/schemas/money'
        fee_amount:
          description: The fee details for the transaction.
          readOnly: true
          $ref: '#/components/schemas/money'
        shipping_amount:
          description: The shipping amount for the transaction.
          readOnly: true
          $ref: '#/components/schemas/money'
        tax_amount:
          description: The tax amount for the transaction.
          readOnly: true
          $ref: '#/components/schemas/money'
        net_amount:
          description: The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as <code>gross_amount</code> minus the <code>paypal_fee</code>.
          readOnly: true
          $ref: '#/components/schemas/money'
      required:
      - gross_amount
    '401':
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: INVALID_ACCOUNT_STATUS
              properties:
                issue:
                  type: string
                  enum:
                  - INVALID_ACCOUNT_STATUS
                description:
                  type: string
                  enum:
                  - Account validations failed for the user.
    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
    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'
    currency_code:
      description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
      type: string
      format: ppaas_common_currency_code_v2
      minLength: 3
      maxLength: 3
    subscription_capture_request:
      title: Charge Amount from Subscriber
      description: The charge amount from the subscriber.
      type: object
      properties:
        note:
          type: string
          description: The reason or note for the subscription charge.
          minLength: 1
          maxLength: 128
        capture_type:
          type: string
          description: The type of capture.
          minLength: 1
          maxLength: 24
          pattern: ^[A-Z_]+$
          enum:
          - OUTSTANDING_BALANCE
        amount:
          $ref: '#/components/schemas/money'
          description: The amount of the outstanding balance. This value cannot be greater than the current outstanding balance amount.
      required:
      - note
      - capture_type
      - amount
    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'
    '404':
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: INVALID_RESOURCE_ID
              properties:
                issue:
                  type: string
                  enum:
                  - INVALID_RESOURCE_ID
                description:
                  type: string
                  enum:
                  - Specified resource ID does not exist. Please check the resource ID and try again.
    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'
    subscriptions.capture-400:
      properties:
        details:
          type: array
          items:
            anyOf:
            - title: MISSING_REQUEST_BODY
              properties:
                issue:
                  type: string
                  enum:
                  - MISSING_REQUEST_BODY
                description:
                  type: string
                  enum:
                  - Request body is missing.
            - title: INVALID_PARAMETER_VALUE
              properties:
                issue:
                  type: string
                  enum:
                  - INVALID_PARAMETER_VALUE
                description:
                  type: string
                  enum:
                  - The value of a field is invalid.
            - title: INVALID_STRING_MAX_LENGTH
              properties:
                issue:
                  type: string
                  enum:
                  - INVALID_STRING_MAX_LENGTH
                description:
                  type: string
                  enum:
                  - The value of a field is too long.
            - title: MISSING_REQUIRED_PARAMETER
              properties:
                issue:
                  type: string
                  enum:
                  - MISSING_REQUIRED_PARAMETER
                description:
                  type: string
                  enum:
                  - A required field is missing.
    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
    email_address:
      type: string
      description: The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
      format: ppaas_common_email_address_v2
      minLength: 3
      maxLength: 254
      pattern: ^.+@[^"\-].+$
    date_time:
      type: string
      description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
      format: ppaas_date_time_v3
      minLength: 20
      maxLength: 64
      pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$
    capture_status:
      type: object
      title: Capture Status
      description: The status of a captured payment.
      properties:
        status:
          description: The status of the captured payment.
          type: string
          readOnly: true
          enum:
          - COMPLETED
          - DECLINED
          - PARTIALLY_REFUNDED
          - PENDING
          - REFUNDED
        status_details:
          description: The details of the captured payment status.
          readOnly: true
          $ref: '#/components/schemas/capture_status_details'
  parameters:
    id:
      name: id
      in: path
      required: true
      description: The ID of the subscription.
      schema:
        type: string
    paypal_request_id:
      name: PayPal-Request-Id
      in: header
      description: The server stores keys for 72 hours.
      required: false
      schema:
        type: string
  responses:
    default:
      description: The default response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_default'
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth2/token
          scopes:
            https://uri.paypal.com/services/subscriptions: Manage plan & subscription
externalDocs:
  url: https://developer.paypal.com/docs/api/subscriptions/v1/