Stripe Methods API

openapi: 3.2.0
info:
  title: Stripe Accounts Account Methods 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: Methods
paths:
  /v1/customers/{customer}/payment_methods:
    get:
      description: <p>Returns a list of PaymentMethods for a given Customer</p>
      operationId: getCustomersCustomerPaymentMethods
      parameters:
      - in: path
        name: customer
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - 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:
          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:
          type: string
        style: form
      - description: An optional filter on the list, based on the object `type` field. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.
        in: query
        name: type
        required: false
        schema:
          enum:
          - acss_debit
          - affirm
          - afterpay_clearpay
          - alipay
          - au_becs_debit
          - bacs_debit
          - bancontact
          - blik
          - boleto
          - card
          - cashapp
          - customer_balance
          - eps
          - fpx
          - giropay
          - grabpay
          - ideal
          - klarna
          - konbini
          - link
          - oxxo
          - p24
          - paynow
          - paypal
          - pix
          - promptpay
          - revolut_pay
          - sepa_debit
          - sofort
          - us_bank_account
          - wechat_pay
          - zip
          type: string
          x-stripeBypassValidation: true
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersCustomerPaymentMethodsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/CustomerPaymentMethodResourceList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Customer Payment Methods
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
  /v1/customers/{customer}/payment_methods/{payment_method}:
    get:
      description: <p>Retrieves a PaymentMethod object for a given Customer.</p>
      operationId: getCustomersCustomerPaymentMethodsPaymentMethod
      parameters:
      - in: path
        name: customer
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - 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: payment_method
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersCustomerPaymentMethodsPaymentMethodRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Customer Payment Methods Payment Method
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
  /v1/payment_methods:
    get:
      description: <p>Returns a list of PaymentMethods for Treasury flows. If you want to list the PaymentMethods attached to a Customer for payments, you should use the <a href="/docs/api/payment_methods/customer_list">List a Customer’s PaymentMethods</a> API instead.</p>
      operationId: getPaymentMethods
      parameters:
      - description: The ID of the customer whose PaymentMethods will be retrieved.
        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:
          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:
          type: string
        style: form
      - description: An optional filter on the list, based on the object `type` field. Without the filter, the list includes all current and future payment method types. If your integration expects only one type of payment method in the response, make sure to provide a type value in the request.
        in: query
        name: type
        required: false
        schema:
          enum:
          - acss_debit
          - affirm
          - afterpay_clearpay
          - alipay
          - au_becs_debit
          - bacs_debit
          - bancontact
          - blik
          - boleto
          - card
          - cashapp
          - customer_balance
          - eps
          - fpx
          - giropay
          - grabpay
          - ideal
          - klarna
          - konbini
          - link
          - oxxo
          - p24
          - paynow
          - paypal
          - pix
          - promptpay
          - revolut_pay
          - sepa_debit
          - sofort
          - us_bank_account
          - wechat_pay
          - zip
          type: string
          x-stripeBypassValidation: true
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentMethodsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/PaymentFlowsPaymentMethodList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Payment Methods
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
    post:
      description: '<p>Creates a PaymentMethod object. Read the <a href="/docs/stripe-js/reference#stripe-create-payment-method">Stripe.js reference</a> to learn how to create PaymentMethods via Stripe.js.</p>


        <p>Instead of creating a PaymentMethod directly, we recommend using the <a href="/docs/payments/accept-a-payment">PaymentIntents</a> API to accept a payment immediately or the <a href="/docs/payments/save-and-reuse">SetupIntent</a> API to collect payment method details ahead of a future payment.</p>'
      operationId: postPaymentMethods
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              acss_debit:
                explode: true
                style: deepObject
              affirm:
                explode: true
                style: deepObject
              afterpay_clearpay:
                explode: true
                style: deepObject
              alipay:
                explode: true
                style: deepObject
              au_becs_debit:
                explode: true
                style: deepObject
              bacs_debit:
                explode: true
                style: deepObject
              bancontact:
                explode: true
                style: deepObject
              billing_details:
                explode: true
                style: deepObject
              blik:
                explode: true
                style: deepObject
              boleto:
                explode: true
                style: deepObject
              card:
                explode: true
                style: deepObject
              cashapp:
                explode: true
                style: deepObject
              customer_balance:
                explode: true
                style: deepObject
              eps:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              fpx:
                explode: true
                style: deepObject
              giropay:
                explode: true
                style: deepObject
              grabpay:
                explode: true
                style: deepObject
              ideal:
                explode: true
                style: deepObject
              interac_present:
                explode: true
                style: deepObject
              klarna:
                explode: true
                style: deepObject
              konbini:
                explode: true
                style: deepObject
              link:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              oxxo:
                explode: true
                style: deepObject
              p24:
                explode: true
                style: deepObject
              paynow:
                explode: true
                style: deepObject
              paypal:
                explode: true
                style: deepObject
              pix:
                explode: true
                style: deepObject
              promptpay:
                explode: true
                style: deepObject
              radar_options:
                explode: true
                style: deepObject
              revolut_pay:
                explode: true
                style: deepObject
              sepa_debit:
                explode: true
                style: deepObject
              sofort:
                explode: true
                style: deepObject
              us_bank_account:
                explode: true
                style: deepObject
              wechat_pay:
                explode: true
                style: deepObject
              zip:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentMethodsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payment Methods
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
  /v1/payment_methods/{payment_method}:
    get:
      description: <p>Retrieves a PaymentMethod object attached to the StripeAccount. To retrieve a payment method attached to a Customer, you should use <a href="/docs/api/payment_methods/customer">Retrieve a Customer’s PaymentMethods</a></p>
      operationId: getPaymentMethodsPaymentMethod
      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
      - in: path
        name: payment_method
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentMethodsPaymentMethodRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Payment Methods
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
    post:
      description: <p>Updates a PaymentMethod object. A PaymentMethod must be attached a customer to be updated.</p>
      operationId: postPaymentMethodsPaymentMethod
      parameters:
      - in: path
        name: payment_method
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              billing_details:
                explode: true
                style: deepObject
              card:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              link:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              us_bank_account:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostPaymentMethodsPaymentMethodRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payment Methods
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
  /v1/payment_methods/{payment_method}/attach:
    post:
      description: '<p>Attaches a PaymentMethod object to a Customer.</p>


        <p>To attach a new PaymentMethod to a customer for future payments, we recommend you use a <a href="/docs/api/setup_intents">SetupIntent</a>

        or a PaymentIntent with <a href="/docs/api/payment_intents/create#create_payment_intent-setup_future_usage">setup_future_usage</a>.

        These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the <code>/v1/payment_methods/:id/attach</code>

        endpoint without first using a SetupIntent or PaymentIntent with <code>setup_future_usage</code> does not optimize the PaymentMethod for

        future use, which makes later declines and payment friction more likely.

        See <a href="/docs/payments/payment-intents#future-usage">Optimizing cards for future payments</a> for more information about setting up

        future payments.</p>


        <p>To use this PaymentMethod as the default for invoice or subscription payments,

        set <a href="/docs/api/customers/update#update_customer-invoice_settings-default_payment_method"><code>invoice_settings.default_payment_method</code></a>,

        on the Customer to the PaymentMethod’s ID.</p>'
      operationId: postPaymentMethodsPaymentMethodAttach
      parameters:
      - in: path
        name: payment_method
        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/PostPaymentMethodsPaymentMethodAttachRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payment Methods Attach
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
  /v1/payment_methods/{payment_method}/detach:
    post:
      description: <p>Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.</p>
      operationId: postPaymentMethodsPaymentMethodDetach
      parameters:
      - in: path
        name: payment_method
        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/PostPaymentMethodsPaymentMethodDetachRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_method'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Payment Methods Detach
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Methods
components:
  schemas:
    customer:
      description: 'This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.


        Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)'
      properties:
        address:
          anyOf:
          - $ref: '#/components/schemas/address'
          description: The customer's address.
        balance:
          description: The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
          type: integer
        cash_balance:
          anyOf:
          - $ref: '#/components/schemas/cash_balance'
          description: The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        currency:
          description: Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
          maxLength: 5000
          type:
          - string
          - 'null'
        default_source:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/bank_account'
          - $ref: '#/components/schemas/card'
          - $ref: '#/components/schemas/source'
          description: 'ID of the default payment source for the customer.


            If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.'
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/bank_account'
            - $ref: '#/components/schemas/card'
            - $ref: '#/components/schemas/source'
          x-stripeBypassValidation: true
        delinquent:
          description: 'Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.


            If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn''t reset to `false`.


            If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.'
          type:
          - boolean
          - 'null'
        description:
          description: An arbitrary string attached to the object. Often useful for displaying to users.
          maxLength: 5000
          type:
          - string
          - 'null'
        discount:
          anyOf:
          - $ref: '#/components/schemas/discount'
          description: Describes the current discount active on the customer, if there is one.
        email:
          description: The customer's email address.
          maxLength: 5000
          type:
          - string
          - 'null'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        invoice_credit_balance:
          additionalProperties:
            type: integer
          description: The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
          type: object
        invoice_prefix:
          description: The prefix for the customer used to generate unique invoice numbers.
          maxLength: 5000
          type:
          - string
          - 'null'
        invoice_settings:
          $ref: '#/components/schemas/invoice_setting_customer_setting'
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        metadata:
          additionalProperties:
            maxLength: 500
            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.
          type: object
        name:
          description: The customer's full name or business name.
          maxLength: 5000
          type:
          - string
          - 'null'
        next_invoice_sequence:
          description: The suffix of the customer's next invoice number (for example, 0001).
          type: integer
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - customer
          type: string
        phone:
          description: The customer's phone number.
          maxLength: 5000
          type:
          - string
          - 'null'
        preferred_locales:
          description: The customer's preferred locales (languages), ordered by preference.
          items:
            maxLength: 5000
            type: string
          type:
          - array
          - 'null'
        shipping:
          anyOf:
          - $ref: '#/components/schemas/shipping'
          description: Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
        sources:
          description: The customer's payment sources, if any.
          properties:
            data:
              description: Details about each object.
              items:
                anyOf:
                - $ref: '#/components/schemas/bank_account'
                - $ref: '#/components/schemas/card'
                - $ref: '#/components/schemas/source'
                title: Polymorphic
                x-stripeBypassValidation: true
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: ApmsSourcesSourceList
          type: object
          x-expandableFields:
          - data
        subscriptions:
          description: The customer's current subscriptions, if any.
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/subscription'
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: SubscriptionList
          type: object
          x-expandableFields:
          - data
        tax:
          $ref: '#/components/schemas/customer_tax'
        tax_exempt:
          description: 'Describes the customer''s tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.'
          enum:
          - exempt
          - none
          - reverse
          type:
          - string
          - 'null'
        tax_ids:
          description: The customer's tax IDs.
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/tax_id'
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: 

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