Stripe Methods API

openapi: 3.0.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:
    GetCustomersCustomerPaymentMethodsPaymentMethodRequest:
      type: object
      properties: {}
    GetPaymentMethodsRequest:
      type: object
      properties: {}
    PostPaymentMethodsPaymentMethodAttachRequest:
      type: object
      required:
      - customer
      properties:
        customer:
          description: The ID of the customer to which to attach the PaymentMethod.
          maxLength: 5000
          type: string
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    PostPaymentMethodsRequest:
      type: object
      properties:
        acss_debit:
          description: If this is an `acss_debit` PaymentMethod, this hash contains details about the ACSS Debit payment method.
          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:
          description: If this is an `affirm` PaymentMethod, this hash contains details about the Affirm payment method.
          properties: {}
          title: param
          type: object
        afterpay_clearpay:
          description: If this is an `AfterpayClearpay` PaymentMethod, this hash contains details about the AfterpayClearpay payment method.
          properties: {}
          title: param
          type: object
        alipay:
          description: If this is an `Alipay` PaymentMethod, this hash contains details about the Alipay payment method.
          properties: {}
          title: param
          type: object
        au_becs_debit:
          description: If this is an `au_becs_debit` PaymentMethod, this hash contains details about the bank account.
          properties:
            account_number:
              maxLength: 5000
              type: string
            bsb_number:
              maxLength: 5000
              type: string
          required:
          - account_number
          - bsb_number
          title: param
          type: object
        bacs_debit:
          description: If this is a `bacs_debit` PaymentMethod, this hash contains details about the Bacs Direct Debit bank account.
          properties:
            account_number:
              maxLength: 5000
              type: string
            sort_code:
              maxLength: 5000
              type: string
          title: param
          type: object
        bancontact:
          description: If this is a `bancontact` PaymentMethod, this hash contains details about the Bancontact payment method.
          properties: {}
          title: param
          type: object
        billing_details:
          description: Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
          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:
          description: If this is a `blik` PaymentMethod, this hash contains details about the BLIK payment method.
          properties: {}
          title: param
          type: object
        boleto:
          description: If this is a `boleto` PaymentMethod, this hash contains details about the Boleto payment method.
          properties:
            tax_id:
              maxLength: 5000
              type: string
          required:
          - tax_id
          title: param
          type: object
        card:
          anyOf:
          - properties:
              cvc:
                maxLength: 5000
                type: string
              exp_month:
                type: integer
              exp_year:
                type: integer
              number:
                maxLength: 5000
                type: string
            required:
            - exp_month
            - exp_year
            - number
            title: card_details_params
            type: object
          - properties:
              token:
                maxLength: 5000
                type: string
            required:
            - token
            title: token_params
            type: object
          description: 'If this is a `card` PaymentMethod, this hash contains the user''s card details. For backwards compatibility, you can alternatively provide a Stripe token (e.g., for Apple Pay, Amex Express Checkout, or legacy Checkout) into the card hash with format `card: {token: "tok_visa"}`. When providing a card number, you must meet the requirements for [PCI compliance](https://stripe.com/docs/security#validating-pci-compliance). We strongly recommend using Stripe.js instead of interacting with this API directly.'
          x-stripeBypassValidation: true
        cashapp:
          description: If this is a `cashapp` PaymentMethod, this hash contains details about the Cash App Pay payment method.
          properties: {}
          title: param
          type: object
        customer:
          description: The `Customer` to whom the original PaymentMethod is attached.
          maxLength: 5000
          type: string
        customer_balance:
          description: If this is a `customer_balance` PaymentMethod, this hash contains details about the CustomerBalance payment method.
          properties: {}
          title: param
          type: object
        eps:
          description: If this is an `eps` PaymentMethod, this hash contains details about the EPS payment method.
          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
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        fpx:
          description: If this is an `fpx` PaymentMethod, this hash contains details about the FPX payment method.
          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:
          description: If this is a `giropay` PaymentMethod, this hash contains details about the Giropay payment method.
          properties: {}
          title: param
          type: object
        grabpay:
          description: If this is a `grabpay` PaymentMethod, this hash contains details about the GrabPay payment method.
          properties: {}
          title: param
          type: object
        ideal:
          desc

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