Stripe Payment Intents API

openapi: 3.2.0
info:
  title: Stripe Accounts Account Payment Intents API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  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
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Payment Intents
paths:
  /v1/payment_intents:
    get:
      description: <p>Returns a list of PaymentIntents.</p>
      operationId: GetPaymentIntents
      parameters:
      - description: A filter on the list, based on the object `created` field. The value can be a string with an integer Unix timestamp or a dictionary with a number of different query options.
        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: Only return PaymentIntents for the customer that this customer ID specifies.
        in: query
        name: customer
        required: false
        schema:
          maxLength: 5000
          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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentIntentsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/PaymentFlowsPaymentIntentList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
    post:
      description: '<p>Creates a PaymentIntent object.</p>


        <p>After the PaymentIntent is created, attach a payment method and <a href="/docs/api/payment_intents/confirm">confirm</a>

        to continue the payment. Learn more about <a href="/docs/payments/payment-intents">the available payment flows

        with the Payment Intents API</a>.</p>


        <p>When you use <code>confirm=true</code> during creation, it’s equivalent to creating

        and confirming the PaymentIntent in the same call. You can use any parameters

        available in the <a href="/docs/api/payment_intents/confirm">confirm API</a> when you supply

        <code>confirm=true</code>.</p>'
      operationId: PostPaymentIntents
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              automatic_payment_methods:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              mandate_data:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              off_session:
                explode: true
                style: deepObject
              payment_method_data:
                explode: true
                style: deepObject
              payment_method_options:
                explode: true
                style: deepObject
              payment_method_types:
                explode: true
                style: deepObject
              radar_options:
                explode: true
                style: deepObject
              shipping:
                explode: true
                style: deepObject
              transfer_data:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/search:
    get:
      description: '<p>Search for PaymentIntents you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.

        Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating

        conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up

        to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
      operationId: GetPaymentIntentsSearch
      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
      - 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 pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
        in: query
        name: page
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for payment intents](https://stripe.com/docs/search#query-fields-for-payment-intents).
        in: query
        name: query
        required: true
        schema:
          maxLength: 5000
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentIntentsSearchRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/SearchResult'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}:
    get:
      description: '<p>Retrieves the details of a PaymentIntent that has previously been created. </p>


        <p>You can retrieve a PaymentIntent client-side using a publishable key when the <code>client_secret</code> is in the query string. </p>


        <p>If you retrieve a PaymentIntent with a publishable key, it only returns a subset of properties. Refer to the <a href="#payment_intent_object">payment intent</a> object reference for more details.</p>'
      operationId: GetPaymentIntentsIntent
      parameters:
      - description: The client secret of the PaymentIntent. We require it if you use a publishable key to retrieve the source.
        in: query
        name: client_secret
        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
      - in: path
        name: intent
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentIntentsIntentRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
    post:
      description: '<p>Updates properties on a PaymentIntent object without confirming.</p>


        <p>Depending on which properties you update, you might need to confirm the

        PaymentIntent again. For example, updating the <code>payment_method</code>

        always requires you to confirm the PaymentIntent again. If you prefer to

        update and confirm at the same time, we recommend updating properties through

        the <a href="/docs/api/payment_intents/confirm">confirm API</a> instead.</p>'
      operationId: PostPaymentIntentsIntent
      parameters:
      - in: path
        name: intent
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              application_fee_amount:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              payment_method_data:
                explode: true
                style: deepObject
              payment_method_options:
                explode: true
                style: deepObject
              payment_method_types:
                explode: true
                style: deepObject
              receipt_email:
                explode: true
                style: deepObject
              shipping:
                explode: true
                style: deepObject
              transfer_data:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsIntentRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/apply_customer_balance:
    post:
      description: <p>Manually reconcile the remaining amount for a <code>customer_balance</code> PaymentIntent.</p>
      operationId: PostPaymentIntentsIntentApplyCustomerBalance
      parameters:
      - in: path
        name: intent
        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/PostPaymentIntentsIntentApplyCustomerBalanceRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/cancel:
    post:
      description: '<p>You can cancel a PaymentIntent object when it’s in one of these statuses: <code>requires_payment_method</code>, <code>requires_capture</code>, <code>requires_confirmation</code>, <code>requires_action</code> or, <a href="/docs/payments/intents">in rare cases</a>, <code>processing</code>. </p>


        <p>After it’s canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a <code>status</code> of <code>requires_capture</code>, the remaining <code>amount_capturable</code> is automatically refunded. </p>


        <p>You can’t cancel the PaymentIntent for a Checkout Session. <a href="/docs/api/checkout/sessions/expire">Expire the Checkout Session</a> instead.</p>'
      operationId: PostPaymentIntentsIntentCancel
      parameters:
      - in: path
        name: intent
        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/PostPaymentIntentsIntentCancelRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/capture:
    post:
      description: '<p>Capture the funds of an existing uncaptured PaymentIntent when its status is <code>requires_capture</code>.</p>


        <p>Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.</p>


        <p>Learn more about <a href="/docs/payments/capture-later">separate authorization and capture</a>.</p>'
      operationId: PostPaymentIntentsIntentCapture
      parameters:
      - in: path
        name: intent
        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
              transfer_data:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsIntentCaptureRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/confirm:
    post:
      description: '<p>Confirm that your customer intends to pay with current or provided

        payment method. Upon confirmation, the PaymentIntent will attempt to initiate

        a payment.

        If the selected payment method requires additional authentication steps, the

        PaymentIntent will transition to the <code>requires_action</code> status and

        suggest additional actions via <code>next_action</code>. If payment fails,

        the PaymentIntent transitions to the <code>requires_payment_method</code> status or the

        <code>canceled</code> status if the confirmation limit is reached. If

        payment succeeds, the PaymentIntent will transition to the <code>succeeded</code>

        status (or <code>requires_capture</code>, if <code>capture_method</code> is set to <code>manual</code>).

        If the <code>confirmation_method</code> is <code>automatic</code>, payment may be attempted

        using our <a href="/docs/stripe-js/reference#stripe-handle-card-payment">client SDKs</a>

        and the PaymentIntent’s <a href="#payment_intent_object-client_secret">client_secret</a>.

        After <code>next_action</code>s are handled by the client, no additional

        confirmation is required to complete the payment.

        If the <code>confirmation_method</code> is <code>manual</code>, all payment attempts must be

        initiated using a secret key.

        If any actions are required for the payment, the PaymentIntent will

        return to the <code>requires_confirmation</code> state

        after those actions are completed. Your server needs to then

        explicitly re-confirm the PaymentIntent to initiate the next payment

        attempt. Read the <a href="/docs/payments/payment-intents/web-manual">expanded documentation</a>

        to learn more about manual confirmation.</p>'
      operationId: PostPaymentIntentsIntentConfirm
      parameters:
      - in: path
        name: intent
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              mandate_data:
                explode: true
                style: deepObject
              off_session:
                explode: true
                style: deepObject
              payment_method_data:
                explode: true
                style: deepObject
              payment_method_options:
                explode: true
                style: deepObject
              payment_method_types:
                explode: true
                style: deepObject
              radar_options:
                explode: true
                style: deepObject
              receipt_email:
                explode: true
                style: deepObject
              shipping:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsIntentConfirmRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/increment_authorization:
    post:
      description: '<p>Perform an incremental authorization on an eligible

        <a href="/docs/api/payment_intents/object">PaymentIntent</a>. To be eligible, the

        PaymentIntent’s status must be <code>requires_capture</code> and

        <a href="/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported">incremental_authorization_supported</a>

        must be <code>true</code>.</p>


        <p>Incremental authorizations attempt to increase the authorized amount on

        your customer’s card to the new, higher <code>amount</code> provided. Similar to the

        initial authorization, incremental authorizations can be declined. A

        single PaymentIntent can call this endpoint multiple times to further

        increase the authorized amount.</p>


        <p>If the incremental authorization succeeds, the PaymentIntent object

        returns with the updated

        <a href="/docs/api/payment_intents/object#payment_intent_object-amount">amount</a>.

        If the incremental authorization fails, a

        <a href="/docs/error-codes#card-declined">card_declined</a> error returns, and no other

        fields on the PaymentIntent or Charge update. The PaymentIntent

        object remains capturable for the previously authorized amount.</p>


        <p>Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.

        After it’s captured, a PaymentIntent can no longer be incremented.</p>


        <p>Learn more about <a href="/docs/terminal/features/incremental-authorizations">incremental authorizations</a>.</p>'
      operationId: PostPaymentIntentsIntentIncrementAuthorization
      parameters:
      - in: path
        name: intent
        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
              transfer_data:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsIntentIncrementAuthorizationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
  /v1/payment_intents/{intent}/verify_microdeposits:
    post:
      description: <p>Verifies microdeposits on a PaymentIntent object.</p>
      operationId: PostPaymentIntentsIntentVerifyMicrodeposits
      parameters:
      - in: path
        name: intent
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              amounts:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentIntentsIntentVerifyMicrodepositsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Payment Intents
components:
  schemas:
    PostPaymentIntentsIntentRequest:
      type: object
      properties:
        amount:
          description: Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or [equivalent in charge currency](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
          type: integer
        application_fee_amount:
          anyOf:
          - type: integer
          - enum:
            - ''
            type: string
          description: The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner's Stripe account. The amount of the application fee collected will be capped at the total payment amount. For more information, see the PaymentIntents [use case for connected accounts](https://stripe.com/docs/payments/connected-accounts).
        capture_method:
          description: Controls when the funds will be captured from the customer's account.
          enum:
          - automatic
          - automatic_async
          - manual
          type: string
        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
        customer:
          description: 'ID of the Customer this PaymentIntent belongs to, if one exists.


            Payment methods attached to other Customers cannot be used with this PaymentIntent.


            If present in combination with [setup_future_usage](https://stripe.com/docs/api#payment_intent_object-setup_future_usage), this PaymentIntent''s payment method will be attached to the Customer after the PaymentIntent has been confirmed and any required actions from the user are complete.'
          maxLength: 5000
          type: string
        description:
          description: An arbitrary string attached to the object. Often useful for displaying to users.
          maxLength: 1000
          type: string
        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`.
        payment_method:
          description: ID of the payment method (a PaymentMethod, Card, or [compatible Source](https://stripe.com/docs/payments/payment-methods/transitioning#compatibility) object) to attach to this PaymentIntent.
          maxLength: 5000
          type: string
        payment_method_configuration:
          description: The ID of the payment method configuration to use with this PaymentIntent.
          maxLength: 100
          type: string
        payment_method_data:
          description: 'If provided, this hash will be used to create a PaymentMethod. The new PaymentMethod will appear

            in the [payment_method](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-payment_method)

            property on the PaymentIntent.'
          properties:
            acss_debit:
              properties:
                account_number:
                  maxLength: 5000
                  type: string
                institution_number:
                  maxLength: 5000
                  type: string
                transit_number:
                  maxLength: 5000
                  type: string
              required:
              - account_number
              - institution_number
              - transit_number
              title: payment_method_param
              type: object
            affirm:
              properties: {}
              title: param
              type: object
            afterpay_clearpay:
              properties: {}
              title: param
              type: object
            alipay:
              properties: {}
              title: param
              type: object
            au_becs_debit:
              properties:
                account_number:
                  maxLength: 5000
                  type: string
                bsb_number:
                  maxLength: 5000
                  type: string
              required:
              - account_number
              - bsb_number
              title: param
              type: object
            bacs_debit:
              properties:
                account_number:
                  maxLength: 5000
                  type: string
                sort_code:
                  maxLength: 5000
                  type: string
              title: param
              type: object
            bancontact:
              properties: {}
              title: param
              type: object
            billing_details:
              properties:
                address:
                  anyOf:
                  - properties:
                      city:
                        maxLength: 5000
                        type: string
                      country:
                        maxLength: 5000
                        type: string
                      line1:
                        maxLength: 5000
                        type: string
                      line2:
                        maxLength: 5000
                        type: string
                      postal_code:
                        maxLength: 5000
                        type: string
                      state:
                        maxLength: 5000
                        type: string
                    title: billing_details_address
                    type: object
                  - enum:
                    - ''
                    type: string
                email:
                  anyOf:
                  - type: string
                  - enum:
                    - ''
                    type: string
                name:
                  anyOf:
                  - maxLength: 5000
                    type: string
                  - enum:
                    - ''
                    type: string
                phone:
                  anyOf:
                  - maxLength

# --- truncated at 32 KB (207 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-payment-intents-api-openapi.yml