Stripe Payment Intents API

openapi: 3.0.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:
    PostPaymentIntentsIntentApplyCustomerBalanceRequest:
      type: object
      properties:
        amount:
          description: 'Amount that you intend to apply to this PaymentIntent from the customer’s cash balance.


            A positive integer representing how much to charge in the [smallest currency unit](https://stripe.com/docs/currencies#zero-decimal) (for example, 100 cents to charge 1 USD or 100 to charge 100 JPY, a zero-decimal currency).


            The maximum amount is the amount of the PaymentIntent.


            When you omit the amount, it defaults to the remaining amount requested on the PaymentIntent.'
          type: integer
        currency:
          description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
          type: string
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    SearchResult:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/payment_intent'
          type: array
        has_more:
          type: boolean
        next_page:
          maxLength: 5000
          nullable: true
          type: string
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - search_result
          type: string
        total_count:
          description: The total number of objects that match the query, only accurate up to 10,000.
          type: integer
        url:
          maxLength: 5000
          type: string
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    PostPaymentIntentsIntentConfirmRequest:
      type: object
      properties:
        capture_method:
          description: Controls when the funds will be captured from the customer's account.
          enum:
          - automatic
          - automatic_async
          - manual
          type: string
        client_secret:
          description: The client secret of the PaymentIntent.
          maxLength: 5000
          type: string
        error_on_requires_action:
          description: Set to `true` to fail the payment attempt if the PaymentIntent transitions into `requires_action`. This parameter is intended for simpler integrations that do not handle customer actions, like [saving cards without authentication](https://stripe.com/docs/payments/save-card-without-authentication).
          type: boolean
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        mandate:
          description: ID of the mandate that's used for this payment.
          maxLength: 5000
          type: string
        mandate_data:
          anyOf:
          - properties:
              customer_acceptance:
                properties:
                  accepted_at:
                    format: unix-time
                    type: integer
                  offline:
                    properties: {}
                    title: offline_param
                    type: object
                  online:
                    properties:
                      ip_address:
                        type: string
                      user_agent:
                        maxLength: 5000
                        type: string
                    required:
                    - ip_address
                    - user_agent
                    title: online_param
                    type: object
                  type:
                    enum:
                    - offline
                    - online
                    maxLength: 5000
                    type: string
                required:
                - type
                title: customer_acceptance_param
                type: object
            required:
            - customer_acceptance
            title: secret_key_param
            type: object
          - enum:
            - ''
            type: string
          - description: This hash contains details about the Mandate to create
            properties:
              customer_acceptance:
                properties:
                  online:
                    properties:
                      ip_address:
                        type: string
                      user_agent:
                        maxLength: 5000
                        type: string
                    title: online_param
                    type: object
                  type:
                    enum:
                    - online
                    maxLength: 5000
                    type: string
                required:
                - online
                - type
                title: customer_acceptance_param
                type: object
            required:
            - customer_acceptance
            title: client_key_param
            type: object
        off_session:
          anyOf:
          - type: boolean
          - enum:
            - one_off
            - recurring
            maxLength: 5000
            type: string
          description: Set to `true` to indicate that the customer isn't in your checkout flow during this payment attempt and can't authenticate. Use this parameter in scenarios where you collect card details and [charge them later](https://stripe.com/docs/payments/cards/charging-saved-cards).
        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_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_nu

# --- 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