Stripe Cards API

openapi: 3.2.0
info:
  title: Stripe Accounts Account Cards 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: Cards
paths:
  /v1/customers/{customer}/cards:
    get:
      deprecated: true
      description: '<p>You can see a list of the cards belonging to a customer.

        Note that the 10 most recent sources are always available on the <code>Customer</code> object.

        If you need more than those 10, you can use this API method and the <code>limit</code> and <code>starting_after</code> parameters to page through additional cards.</p>'
      operationId: getCustomersCustomerCards
      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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersCustomerCardsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/CardList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Customer Cards
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
    post:
      description: '<p>When you create a new credit card, you must specify a customer or recipient on which to create it.</p>


        <p>If the card’s owner has no default card, then the new card will become the default.

        However, if the owner already has a default, then it will not change.

        To change the default, you should <a href="/docs/api#update_customer">update the customer</a> to have a new <code>default_source</code>.</p>'
      operationId: postCustomersCustomerCards
      parameters:
      - in: path
        name: customer
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              bank_account:
                explode: true
                style: deepObject
              card:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostCustomersCustomerCardsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Customers Customer Cards
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
  /v1/customers/{customer}/cards/{id}:
    delete:
      description: <p>Delete a specified source for a given customer.</p>
      operationId: deleteCustomersCustomerCardsId
      parameters:
      - in: path
        name: customer
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/DeleteCustomersCustomerCardsIdRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/payment_source'
                - $ref: '#/components/schemas/deleted_payment_source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Delete   Customers Customer Cards Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
    get:
      deprecated: true
      description: <p>You can always see the 10 most recent cards directly on a customer; this method lets you retrieve details about a specific card stored on the customer.</p>
      operationId: getCustomersCustomerCardsId
      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: id
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersCustomerCardsIdRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Customer Cards Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
    post:
      description: <p>Update a specified source for a given customer.</p>
      operationId: postCustomersCustomerCardsId
      parameters:
      - in: path
        name: customer
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - in: path
        name: id
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              owner:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostCustomersCustomerCardsIdRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/card'
                - $ref: '#/components/schemas/bank_account'
                - $ref: '#/components/schemas/source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Customers Customer Cards Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
  /v1/issuing/cards:
    get:
      description: <p>Returns a list of Issuing <code>Card</code> objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.</p>
      operationId: getIssuingCards
      parameters:
      - description: Only return cards belonging to the Cardholder with the provided ID.
        in: query
        name: cardholder
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: Only return cards that were issued during the given date interval.
        explode: true
        in: query
        name: created
        required: false
        schema:
          anyOf:
          - properties:
              gt:
                type: integer
              gte:
                type: integer
              lt:
                type: integer
              lte:
                type: integer
            title: range_query_specs
            type: object
          - type: integer
        style: deepObject
      - description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: Only return cards that have the given expiration month.
        in: query
        name: exp_month
        required: false
        schema:
          type: integer
        style: form
      - description: Only return cards that have the given expiration year.
        in: query
        name: exp_year
        required: false
        schema:
          type: integer
        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: Only return cards that have the given last four digits.
        in: query
        name: last4
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
        in: query
        name: starting_after
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: Only return cards that have the given status. One of `active`, `inactive`, or `canceled`.
        in: query
        name: status
        required: false
        schema:
          enum:
          - active
          - canceled
          - inactive
          type: string
          x-stripeBypassValidation: true
        style: form
      - description: Only return cards that have the given type. One of `virtual` or `physical`.
        in: query
        name: type
        required: false
        schema:
          enum:
          - physical
          - virtual
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetIssuingCardsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/IssuingCardList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Issuing Cards
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
    post:
      description: <p>Creates an Issuing <code>Card</code> object.</p>
      operationId: postIssuingCards
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              shipping:
                explode: true
                style: deepObject
              spending_controls:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostIssuingCardsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/issuing.card'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Issuing Cards
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
  /v1/issuing/cards/{card}:
    get:
      description: <p>Retrieves an Issuing <code>Card</code> object.</p>
      operationId: getIssuingCardsCard
      parameters:
      - in: path
        name: card
        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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetIssuingCardsCardRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/issuing.card'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Issuing Cards Card
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
    post:
      description: <p>Updates the specified Issuing <code>Card</code> object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.</p>
      operationId: postIssuingCardsCard
      parameters:
      - in: path
        name: card
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              pin:
                explode: true
                style: deepObject
              spending_controls:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostIssuingCardsCardRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/issuing.card'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Issuing Cards Card
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Cards
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: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: TaxIDsList
          type: object
          x-expandableFields:
          - data
        test_clock:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/test_helpers.test_clock'
          description: ID of the test clock that this customer belongs to.
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/test_helpers.test_clock'
      required:
      - created
      - id
      - livemode
      - object
      title: Customer
      type: object
      x-expandableFields:
      - address
      - cash_balance
      - default_source
      - discount
      - invoice_settings
      - shipping
      - sources
      - subscriptions
      - tax
      - tax_ids
      - test_clock
      x-resourceId: customer
    GetCustomersCustomerCardsRequest:
      type: object
      properties: {}
    GetCustomersCustomerCardsIdRequest:
      type: object
      properties: {}
    issuing.cardholder:
      description: 'An Issuing `Cardholder` object represents an individual or business entity who is [issued](https://stripe.com/docs/issuing) cards.


        Related guide: [How to create a cardholder](https://stripe.com/docs/issuing/cards#create-cardholder)'
      properties:
        billing:
          $ref: '#/components/schemas/issuing_cardholder_address'
        company:
          anyOf:
          - $ref: '#/components/schemas/issuing_cardholder_company'
          description: Additional information about a `company` cardholder.
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        email:
          description: The cardholder's email address.
          maxLength: 5000
          type:
          - string
          - 'null'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        individual:
          anyOf:
          - $ref: '#/components/schemas/issuing_cardholder_individual'
          description: Additional information about an `individual` cardholder.
        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) t

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