Stripe Payment Methods API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Payment 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: Payment Methods
paths:
  /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.
      tags:
      - Payment 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.
      tags:
      - Payment 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.
      tags:
      - Payment 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.
      tags:
      - Payment 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.
      tags:
      - Payment 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.
      tags:
      - Payment Methods
components:
  schemas:
    PostPaymentMethodsPaymentMethodDetachRequest:
      type: object
      properties:
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    error:
      description: An error response from the Stripe API
      properties:
        error:
          $ref: '#/components/schemas/api_errors'
      required:
      - error
      type: object
    GetPaymentMethodsRequest:
      type: object
      properties: {}
    PostPaymentMethodsPaymentMethodRequest:
      type: object
      properties:
        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
        card:
          description: If this is a `card` PaymentMethod, this hash contains the user's card details.
          properties:
            exp_month:
              type: integer
            exp_year:
              type: integer
          title: update_api_param
          type: object
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        link:
          description: If this is an `Link` PaymentMethod, this hash contains details about the Link payment method.
          properties: {}
          title: param
          type: object
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - enum:
            - ''
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
        us_bank_account:
          description: If this is an `us_bank_account` PaymentMethod, this hash contains details about the US bank account payment method.
          properties:
            account_holder_type:
              enum:
              - company
              - individual
              type: string
          title: update_param
          type: object
    PaymentFlowsPaymentMethodList:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/payment_method'
          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
          pattern: ^/v1/payment_methods
          type: string
    GetPaymentMethodsPaymentMethodRequest:
      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
    payment_method:
      description: 'PaymentMethod objects represent your customer''s payment instruments.

        You can use them with [PaymentIntents](https://stripe.com/docs/payments/payment-intents) to collect payments or save them to

        Customer objects to store instrument details for future payments.


        Related guides: [Payment Methods](https://stripe.com/docs/payments/payment-methods) and [More Payment Scenarios](https://stripe.com/docs/payments/more-payment-scenarios).'
      properties:
        acss_debit:
          $ref: '#/components/schemas/payment_method_acss_debit'
        affirm:
          $ref: '#/components/schemas/payment_method_affirm'
        afterpay_clearpay:
          $ref: '#/components/schemas/payment_method_afterpay_clearpay'
        alipay:
          $ref: '#/components/schemas/payment_flows_private_payment_methods_alipay'
        au_becs_debit:
          $ref: '#/components/schemas/payment_method_au_becs_debit'
        bacs_debit:
          $ref: '#/components/schemas/payment_method_bacs_debit'
        bancontact:
          $ref: '#/components/schemas/payment_method_bancontact'
        billing_details:
          $ref: '#/components/schemas/billing_details'
        blik:
          $ref: '#/components/schemas/payment_method_blik'
        boleto:
          $ref: '#/components/schemas/payment_method_boleto'
        card:
          $ref: '#/components/schemas/payment_method_card'
        card_present:
          $ref: '#/components/schemas/payment_method_card_present'
        cashapp:
          $ref: '#/components/schemas/payment_method_cashapp'
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        customer:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/customer'
          description: The ID of the Customer to which this PaymentMethod is saved. This will not be set when the PaymentMethod has not been saved to a Customer.
          nullable: true
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/customer'
        customer_balance:
          $ref: '#/components/schemas/payment_method_customer_balance'
        eps:
          $ref: '#/components/schemas/payment_method_eps'
        fpx:
          $ref: '#/components/schemas/payment_method_fpx'
        giropay:
          $ref: '#/components/schemas/payment_method_giropay'
        grabpay:
          $ref: '#/components/schemas/payment_method_grabpay'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        ideal:
          $ref: '#/components/schemas/payment_method_ideal'
        interac_present:
          $ref: '#/components/schemas/payment_method_interac_present'
        klarna:
          $ref: '#/components/schemas/payment_method_klarna'
        konbini:
          $ref: '#/components/schemas/payment_method_konbini'
        link:
          $ref: '#/components/schemas/payment_method_link'
        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.
          nullable: true
          type: object
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - payment_method
          type: string
        oxxo:
          $ref: '#/components/schemas/payment_method_oxxo'
        p24:
          $ref: '#/components/schemas/payment_method_p24'
        paynow:
          $ref: '#/components/schemas/payment_method_paynow'
        paypal:
          $ref: '#/components/schemas/payment_method_paypal'
        pix:
          $ref: '#/components/schemas/payment_method_pix'
        promptpay:
          $ref: '#/components/schemas/payment_method_promptpay'
        radar_options:
          $ref: '#/components/schemas/radar_radar_options'
        revolut_pay:
          $ref: '#/components/schemas/payment_method_revolut_pay'
        sepa_debit:
          $ref: '#/components/schemas/payment_method_sepa_debit'
        sofort:
          $ref: '#/components/schemas/payment_method_sofort'
        type:
          description: The type of the PaymentMethod. An additional hash is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod type.
          enum:
          - acss_debit
          - affirm
          - afterpay_clearpay
          - alipay
          - au_becs_debit
          - bacs_debit
          - bancontact
          - blik
          - boleto
          - card
          - card_present
          - cashapp
          - customer_balance
          - eps
          - fpx
          - giropay
          - grabpay
          - ideal
          - interac_present
          - 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
        us_bank_account:
          $ref: '#/components/schemas/payment_method_us_bank_account'
        wechat_pay:
          $ref: '#/components/schemas/payment_method_wechat_pay'
        zip:
          $ref: '#/components/schemas/payment_method_zip'
      required:
      - billing_details
      - created
      - id
      - livemode
      - object
      - type
      title: PaymentMethod
      type: object
      x-expandableFields:
      - acss_debit
      - affirm
      - afterpay_clearpay
      - alipay
      - au_becs_debit
      - bacs_debit
      - bancontact
      - billing_details
      - blik
      - boleto
      - card
      - card_present
      - cashapp
      - customer
      - customer_balance
      - eps
      - fpx
      - giropay
      - grabpay
      - ideal
      - interac_present
      - klarna
      - konbini
      - link
      - oxxo
      - p24
      - paynow
      - paypal
      - pix
      - promptpay
      - radar_options
      - revolut_pay
      - sepa_debit
      - sofort
      - us_bank_account
      - wechat_pay
      - zip
      x-resourceId: payment_method
    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 

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