Stripe Cards API

openapi: 3.0.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:
    PostIssuingCardsCardRequest:
      type: object
      properties:
        cancellation_reason:
          description: Reason why the `status` of this card is `canceled`.
          enum:
          - lost
          - stolen
          type: string
          x-stripeBypassValidation: true
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
        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`.
        pin:
          description: The desired new PIN for this card.
          properties:
            encrypted_number:
              maxLength: 5000
              type: string
          title: encrypted_pin_param
          type: object
        spending_controls:
          description: Rules that control spending for this card. Refer to our [documentation](https://stripe.com/docs/issuing/controls/spending-controls) for more details.
          properties:
            allowed_categories:
              items:
                enum:
                - ac_refrigeration_repair
                - accounting_bookkeeping_services
                - advertising_services
                - agricultural_cooperative
                - airlines_air_carriers
                - airports_flying_fields
                - ambulance_services
                - amusement_parks_carnivals
                - antique_reproductions
                - antique_shops
                - aquariums
                - architectural_surveying_services
                - art_dealers_and_galleries
                - artists_supply_and_craft_shops
                - auto_and_home_supply_stores
                - auto_body_repair_shops
                - auto_paint_shops
                - auto_service_shops
                - automated_cash_disburse
                - automated_fuel_dispensers
                - automobile_associations
                - automotive_parts_and_accessories_stores
                - automotive_tire_stores
                - bail_and_bond_payments
                - bakeries
                - bands_orchestras
                - barber_and_beauty_shops
                - betting_casino_gambling
                - bicycle_shops
                - billiard_pool_establishments
                - boat_dealers
                - boat_rentals_and_leases
                - book_stores
                - books_periodicals_and_newspapers
                - bowling_alleys
                - bus_lines
                - business_secretarial_schools
                - buying_shopping_services
                - cable_satellite_and_other_pay_television_and_radio
                - camera_and_photographic_supply_stores
                - candy_nut_and_confectionery_stores
                - car_and_truck_dealers_new_used
                - car_and_truck_dealers_used_only
                - car_rental_agencies
                - car_washes
                - carpentry_services
                - carpet_upholstery_cleaning
                - caterers
                - charitable_and_social_service_organizations_fundraising
                - chemicals_and_allied_products
                - child_care_services
                - childrens_and_infants_wear_stores
                - chiropodists_podiatrists
                - chiropractors
                - cigar_stores_and_stands
                - civic_social_fraternal_associations
                - cleaning_and_maintenance
                - clothing_rental
                - colleges_universities
                - commercial_equipment
                - commercial_footwear
                - commercial_photography_art_and_graphics
                - commuter_transport_and_ferries
                - computer_network_services
                - computer_programming
                - computer_repair
                - computer_software_stores
                - computers_peripherals_and_software
                - concrete_work_services
                - construction_materials
                - consulting_public_relations
                - correspondence_schools
                - cosmetic_stores
                - counseling_services
                - country_clubs
                - courier_services
                - court_costs
                - credit_reporting_agencies
                - cruise_lines
                - dairy_products_stores
                - dance_hall_studios_schools
                - dating_escort_services
                - dentists_orthodontists
                - department_stores
                - detective_agencies
                - digital_goods_applications
                - digital_goods_games
                - digital_goods_large_volume
                - digital_goods_media
                - direct_marketing_catalog_merchant
                - direct_marketing_combination_catalog_and_retail_merchant
                - direct_marketing_inbound_telemarketing
                - direct_marketing_insurance_services
                - direct_marketing_other
                - direct_marketing_outbound_telemarketing
                - direct_marketing_subscription
                - direct_marketing_travel
                - discount_stores
                - doctors
                - door_to_door_sales
                - drapery_window_covering_and_upholstery_stores
                - drinking_places
                - drug_stores_and_pharmacies
                - drugs_drug_proprietaries_and_druggist_sundries
                - dry_cleaners
                - durable_goods
                - duty_free_stores
                - eating_places_restaurants
                - educational_services
                - electric_razor_stores
                - electric_vehicle_charging
                - electrical_parts_and_equipment
                - electrical_services
                - electronics_repair_shops
                - electronics_stores
                - elementary_secondary_schools
                - emergency_services_gcas_visa_use_only
                - employment_temp_agencies
                - equipment_rental
                - exterminating_services
                - family_clothing_stores
                - fast_food_restaurants
                - financial_institutions
                - fines_government_administrative_entities
                - fireplace_fireplace_screens_and_accessories_stores
                - floor_covering_stores
                - florists
                - florists_supplies_nursery_stock_and_flowers
                - freezer_and_locker_meat_provisioners
                - fuel_dealers_non_automotive
                - funeral_services_crematories
                - furniture_home_furnishings_and_equipment_stores_except_appliances
                - furniture_repair_refinishing
                - furriers_and_fur_shops
                - general_services
                - gift_card_novelty_and_souvenir_shops
                - glass_paint_and_wallpaper_stores
                - glassware_crystal_stores
                - golf_courses_public
                - government_licensed_horse_dog_racing_us_region_only
                - government_licensed_online_casions_online_gambling_us_region_only
                - government_owned_lotteries_non_us_region
                - government_owned_lotteries_us_region_only
                - government_services
                - grocery_stores_supermarkets
                - hardware_equipment_and_supplies
                - hardware_stores
                - health_and_beauty_spas
                - hearing_aids_sales_and_supplies
                - heating_plumbing_a_c
                - hobby_toy_and_game_shops
                - home_supply_warehouse_stores
                - hospitals
                - hotels_motels_and_resorts
                - household_appliance_stores
                - industrial_supplies
                - information_retrieval_services
                - insurance_default
                - insurance_underwriting_premiums
                - intra_company_purchases
                - jewelry_stores_watches_clocks_and_silverware_stores
                - landscaping_services
                - laundries
                - laundry_cleaning_services
                - legal_services_attorneys
                - luggage_and_leather_goods_stores
                - lumber_building_materials_stores
                - manual_cash_disburse
                - marinas_service_and_supplies
                - marketplaces
                - masonry_stonework_and_plaster
                - massage_parlors
                - medical_and_dental_labs
                - medical_dental_ophthalmic_and_hospital_equipment_and_supplies
                - medical_services
                - membership_organizations
                - mens_and_boys_clothing_and_accessories_stores
                - mens_womens_clothing_stores
                - metal_service_centers
                - miscellaneous
                - miscellaneous_apparel_and_accessory_shops
                - miscellaneous_auto_dealers
                - miscellaneous_business_services
                - miscellaneous_food_stores
                - miscellaneous_general_merchandise
                - miscellaneous_general_services
                - miscellaneous_home_furnishing_specialty_stores
                - miscellaneous_publishing_and_printing
                - miscellaneous_recreation_services
                - miscellaneous_repair_shops
                - miscellaneous_specialty_retail
                - mobile_home_dealers
                - motion_picture_theaters
                - motor_freight_carriers_and_trucking
                - motor_homes_dealers
                - motor_vehicle_supplies_and_new_parts
                - motorcycle_shops_and_dealers
                - motorcycle_shops_dealers
                - music_stores_musical_instruments_pianos_and_sheet_music
                - news_dealers_and_newsstands
                - non_fi_money_orders
                - non_fi_stored_value_card_purchase_load
                - nondurable_goods
                - nurseries_lawn_and_garden_supply_stores
                - nursing_personal_care
                - office_and_commercial_furniture
                - opticians_eyeglasses
                - optometrists_ophthalmologist
                - orthopedic_goods_prosthetic_devices
                - osteopaths
                - package_stores_beer_wine_and_liquor
                - paints_varnishes_and_supplies
                - parking_lots_garages
                - passenger_railways
                - pawn_shops
                - pet_shops_pet_food_and_supplies
                - petroleum_and_petroleum_products
                - photo_developing
                - photographic_photocopy_microfilm_equipment_and_supplies
                - photographic_studios
                - picture_video_production
                - piece_goods_notions_and_other_dry_goods
                - plumbing_heating_equipment_and_supplies
                - political_organizations
                - postal_services_government_only
                - precious_stones_and_metals_watches_and_jewelry
                - professional_services
                - public_warehousing_and_storage
                - quick_copy_repro_and_blueprint
                - railroads
                - real_estate_agents_and_managers_rentals
                - record_stores
                - recreational_vehicle_rentals
                - religious_goods_stores
                - religious_organizations
                - roofing_siding_sheet_metal
                - secretarial_support_services
                - security_brokers_dealers
                - service_stations
                - sewing_needlework_fabric_and_piece_goods_stores
                - shoe_repair_hat_cleaning
                - shoe_stores
                - small_appliance_repair
                - snowmobile_dealers
                - special_trade_services
                - specialty_cleaning
                - sporting_goods_stores
                - sporting_recreation_camps
                - sports_and_riding_apparel_store

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