Stripe Setup Intents API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Setup 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: Setup Intents
paths:
  /v1/setup_intents:
    get:
      description: <p>Returns a list of SetupIntents.</p>
      operationId: GetSetupIntents
      parameters:
      - description: 'If present, the SetupIntent''s payment method will be attached to the in-context Stripe Account.


          It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.'
        in: query
        name: attach_to_self
        required: false
        schema:
          type: boolean
        style: form
      - description: A filter on the list, based on the object `created` field. The value can be a string with an integer Unix timestamp, or it can be 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 SetupIntents for the customer specified by this customer ID.
        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: Only return SetupIntents that associate with the specified payment method.
        in: query
        name: payment_method
        required: false
        schema:
          maxLength: 5000
          type: string
        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/GetSetupIntentsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/PaymentFlowsSetupIntentList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
    post:
      description: '<p>Creates a SetupIntent object.</p>


        <p>After you create the SetupIntent, attach a payment method and <a href="/docs/api/setup_intents/confirm">confirm</a>

        it to collect any required permissions to charge the payment method later.</p>'
      operationId: PostSetupIntents
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              automatic_payment_methods:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              flow_directions:
                explode: true
                style: deepObject
              mandate_data:
                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
              single_use:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSetupIntentsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
  /v1/setup_intents/{intent}:
    get:
      description: '<p>Retrieves the details of a SetupIntent that has previously been created. </p>


        <p>Client-side retrieval using a publishable key is allowed when the <code>client_secret</code> is provided in the query string. </p>


        <p>When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the <a href="#setup_intent_object">SetupIntent</a> object reference for more details.</p>'
      operationId: GetSetupIntentsIntent
      parameters:
      - description: The client secret of the SetupIntent. We require this string if you use a publishable key to retrieve the SetupIntent.
        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/GetSetupIntentsIntentRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
    post:
      description: <p>Updates a SetupIntent object.</p>
      operationId: PostSetupIntentsIntent
      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
              flow_directions:
                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
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSetupIntentsIntentRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
  /v1/setup_intents/{intent}/cancel:
    post:
      description: '<p>You can cancel a SetupIntent object when it’s in one of these statuses: <code>requires_payment_method</code>, <code>requires_confirmation</code>, or <code>requires_action</code>. </p>


        <p>After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error.</p>'
      operationId: PostSetupIntentsIntentCancel
      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/PostSetupIntentsIntentCancelRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
  /v1/setup_intents/{intent}/confirm:
    post:
      description: '<p>Confirm that your customer intends to set up the current or

        provided payment method. For example, you would confirm a SetupIntent

        when a customer hits the “Save” button on a payment method management

        page on your website.</p>


        <p>If the selected payment method does not require any additional

        steps from the customer, the SetupIntent will transition to the

        <code>succeeded</code> status.</p>


        <p>Otherwise, it will transition to the <code>requires_action</code> status and

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

        the SetupIntent will transition to the

        <code>requires_payment_method</code> status or the <code>canceled</code> status if the

        confirmation limit is reached.</p>'
      operationId: PostSetupIntentsIntentConfirm
      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
              payment_method_data:
                explode: true
                style: deepObject
              payment_method_options:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSetupIntentsIntentConfirmRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
  /v1/setup_intents/{intent}/verify_microdeposits:
    post:
      description: <p>Verifies microdeposits on a SetupIntent object.</p>
      operationId: PostSetupIntentsIntentVerifyMicrodeposits
      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/PostSetupIntentsIntentVerifyMicrodepositsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setup_intent'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Setup Intents
  /v1/setup_attempts:
    get:
      summary: List Setup Attempts
      description: <p>Returns a list of SetupAttempts that associate with a provided SetupIntent.</p>
      operationId: GetSetupAttempts
      parameters:
      - name: setup_intent
        in: query
        required: true
        schema:
          type: string
          maxLength: 5000
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
          maxLength: 5000
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/setup_attempt'
                  has_more:
                    type: boolean
                  url:
                    type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_2'
      tags:
      - Setup Intents
components:
  schemas:
    PostSetupIntentsRequest:
      type: object
      properties:
        attach_to_self:
          description: 'If present, the SetupIntent''s payment method will be attached to the in-context Stripe Account.


            It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.'
          type: boolean
        automatic_payment_methods:
          description: When you enable this parameter, this SetupIntent accepts payment methods that you enable in the Dashboard and that are compatible with its other parameters.
          properties:
            allow_redirects:
              enum:
              - always
              - never
              type: string
            enabled:
              type: boolean
          required:
          - enabled
          title: automatic_payment_methods_param
          type: object
        confirm:
          description: Set to `true` to attempt to confirm this SetupIntent immediately. This parameter defaults to `false`. If a card is the attached payment method, you can provide a `return_url` in case further authentication is necessary.
          type: boolean
        customer:
          description: 'ID of the Customer this SetupIntent belongs to, if one exists.


            If present, the SetupIntent''s payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent.'
          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
        flow_directions:
          description: 'Indicates the directions of money movement for which this payment method is intended to be used.


            Include `inbound` if you intend to use the payment method as the origin to pull funds from. Include `outbound` if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.'
          items:
            enum:
            - inbound
            - outbound
            type: string
          type: array
        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. This parameter can only be used with [`confirm=true`](https://stripe.com/docs/api/setup_intents/create#create_setup_intent-confirm).
        metadata:
          additionalProperties:
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
          type: object
        on_behalf_of:
          description: The Stripe account ID created for this SetupIntent.
          type: string
        payment_method:
          description: ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.
          maxLength: 5000
          type: string
        payment_method_configuration:
          description: The ID of the payment method configuration to use with this SetupIntent.
          maxLength: 100
          type: string
        payment_method_data:
          description: 'When included, this hash creates a PaymentMethod that is set as the [`payment_method`](https://stripe.com/docs/api/setup_intents/object#setup_intent_object-payment_method)

            value in the SetupIntent.'
          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: 5000
                    type: string
                  - enum:
                    - ''
                    type: string
              title: billing_details_inner_params
              type: object
            blik:
              properties: {}
              title: param
              type: object
            boleto:
              properties:
                tax_id:
                  maxLength: 5000
                  type: string
              required:
              - tax_id
              title: param
              type: object
            cashapp:
              properties: {}
              title: param
              type: object
            customer_balance:
              properties: {}
              title: param
              type: object
            eps:
              properties:
                bank:
                  enum:
                  - arzte_und_apotheker_bank
                  - austrian_anadi_bank_ag
                  - bank_austria
                  - bankhaus_carl_spangler
                  - bankhaus_schelhammer_und_schattera_ag
                  - bawag_psk_ag
                  - bks_bank_ag
                  - brull_kallmus_bank_ag
                  - btv_vier_lander_bank
                  - capital_bank_grawe_gruppe_ag
                  - deutsche_bank_ag
                  - dolomitenbank
                  - easybank_ag
                  - erste_bank_und_sparkassen
                  - hypo_alpeadriabank_international_ag
                  - hypo_bank_burgenland_aktiengesellschaft
                  - hypo_noe_lb_fur_niederosterreich_u_wien
                  - hypo_oberosterreich_salzburg_steiermark
                  - hypo_tirol_bank_ag
                  - hypo_vorarlberg_bank_ag
                  - marchfelder_bank
                  - oberbank_ag
                  - raiffeisen_bankengruppe_osterreich
                  - schoellerbank_ag
                  - sparda_bank_wien
                  - volksbank_gruppe
                  - volkskreditbank_ag
                  - vr_bank_braunau
                  maxLength: 5000
                  type: string
              title: param
              type: object
            fpx:
              properties:
                bank:
                  enum:
                  - affin_bank
                  - agrobank
                  - alliance_bank
                  - ambank
                  - bank_islam
                  - bank_muamalat
                  - bank_of_china
                  - bank_rakyat
                  - bsn
                  - cimb
                  - deutsche_bank
                  - hong_leong_bank
                  - hsbc
                  - kfh
                  - maybank2e
                  - maybank2u
                  - ocbc
                  - pb_enterprise
                  - public_bank
                  - rhb
                  - standard_chartered
                  - uob
                  maxLength: 5000
                  type: string
                  x-stripeBypassValidation: true
              required:
              - bank
              title: param
              type: object
            giropay:
              properties: {}
              title: param
              type: object
            grabpay:
              properties: {}
              title: param
              type: object
            ideal:
              properties:
                bank:
                  enum:
                  - abn_amro
                  - asn_bank
                  - bunq
                  - handelsbanken
                  - ing
                  - knab
                  - moneyou
                  - n26
                  - rabobank
                  - regiobank
                  - revolut
                  - sns_bank
                  - triodos_bank
                  - van_lanschot
                  - yoursafe
                  maxLength: 5000
                  type: string
              title: param
              type: object
            interac_present:
              properties: {}
              title: param
              type: object
            klarna:
              properties:
                dob:
                  properties:
                    day:
                      type: integer
                    month:
                      type: integer
                    year:
                      type: integer
                  required:
                  - day
                  - month
                  - year
                  title: date_of_birth
                  type: object
              title: param
              type: object
            konbini:
              properties: {}
              title: param
              type: object
            link:
              properties: {}
              title: param
              type: object
            metadata:
              additionalProperties:
                type: string
              type: object
            oxxo:
              properties: {}
              title: param
              type: object
            p24:
              properties:
                bank:
                  enum:
                  - alior_bank
                  - bank_millennium
                  - bank_nowy_bfg_sa
                  - bank_pekao_sa
                  - banki_spbdzielcze
                  - blik
                  - bnp_paribas
                  - boz
                  - citi_handlowy
                  - credit_agricole
                  - envelobank
                  - etransfer_pocztowy24
                  - getin_bank
                  - ideabank
                  - ing
                  - inteligo
                  - mbank_mtransfer
                  - nest_przelew
                  - noble_pay
                  - pbac_z_ipko
                  - plus_bank
                  - santander_przelew24
                  - tmobile_usbugi_bankowe
                  - toyota_bank
                  - volkswagen_bank
                  type: string
                  x-stripeBypassValidation: true
              title: param
              type: object
            paynow:
              properties: {}
              title: param
              type: object
            paypal:
              properties: {}
              title: param
              type: object
            pix:
              properties: {}
              title: param
              type: object
            promptpay:
              properties: {}
              title: param
              type: object
            radar_options:
              properties:
                session:
                  maxLength: 5000
                  type: string
              title: radar_options
              type: object
            revolut_pay:
              properties: {}
              title: param
              type: object
            sepa_debit:
              properties:
                iban:
                  maxLength: 5000
                  type: string
              required:
              - iban
              title: param
              type: object
            sofort:
              properties:
                country:
                  enum:
                  - AT
                  - BE
                  - DE
                  - ES
                  - IT
                  - NL
                  type: string
              required:
              - country
              title: param
              type: object
            type:
              enum:
              - acss_debit
              - affirm
              - afterpay_clearpay
              - alipay
              - au_becs_debit
              - bacs_debit
              - bancontact
              - blik
              - boleto
              - cashapp
              - customer_balance
              - eps
              - fpx
              - giropay
              - grabpay
              - ideal
              - klarna
              - konbini
              - link
              - oxxo
              - p24
              - paynow
              - paypal
              - pix
              - promptpay
              - revolut_pay
              - sepa_debit
              - sofort
           

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