Stripe Sources API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Sources 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: Sources
paths:
  /v1/customers/{customer}/sources:
    get:
      description: <p>List sources for a specified customer.</p>
      operationId: getCustomersCustomerSources
      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: Filter sources according to a particular object type.
        in: query
        name: object
        required: false
        schema:
          maxLength: 5000
          type: string
        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/GetCustomersCustomerSourcesRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/ApmsSourcesSourceList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Customer Sources
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
    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: postCustomersCustomerSources
      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/PostCustomersCustomerSourcesRequest'
        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 Sources
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
  /v1/customers/{customer}/sources/{id}:
    delete:
      description: <p>Delete a specified source for a given customer.</p>
      operationId: deleteCustomersCustomerSourcesId
      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/DeleteCustomersCustomerSourcesIdRequest'
        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 Sources Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
    get:
      description: <p>Retrieve a specified source for a given customer.</p>
      operationId: getCustomersCustomerSourcesId
      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: 500
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersCustomerSourcesIdRequest'
        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 Get   Customers Customer Sources Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
    post:
      description: <p>Update a specified source for a given customer.</p>
      operationId: postCustomersCustomerSourcesId
      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/PostCustomersCustomerSourcesIdRequest'
        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 Sources Id
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
  /v1/customers/{customer}/sources/{id}/verify:
    post:
      description: <p>Verify a specified bank account for a given customer.</p>
      operationId: postCustomersCustomerSourcesIdVerify
      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:
              amounts:
                explode: true
                style: deepObject
              expand:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostCustomersCustomerSourcesIdVerifyRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bank_account'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Post   Customers Customer Sources Id Verify
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Sources
  /v1/sources:
    post:
      description: <p>Creates a new source object.</p>
      operationId: PostSources
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              mandate:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              owner:
                explode: true
                style: deepObject
              receiver:
                explode: true
                style: deepObject
              redirect:
                explode: true
                style: deepObject
              source_order:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSourcesRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
  /v1/sources/{source}:
    get:
      description: <p>Retrieves an existing source object. Supply the unique source ID from a source creation request and Stripe will return the corresponding up-to-date source object information.</p>
      operationId: GetSourcesSource
      parameters:
      - description: The client secret of the source. Required if a publishable key is used to retrieve the source.
        in: query
        name: client_secret
        required: false
        schema:
          maxLength: 5000
          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
      - in: path
        name: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetSourcesSourceRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
    post:
      description: '<p>Updates the specified source by setting the values of the parameters passed. Any parameters not provided will be left unchanged.</p>


        <p>This request accepts the <code>metadata</code> and <code>owner</code> as arguments. It is also possible to update type specific information for selected payment methods. Please refer to our <a href="/docs/sources">payment method guides</a> for more detail.</p>'
      operationId: PostSourcesSource
      parameters:
      - in: path
        name: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              mandate:
                explode: true
                style: deepObject
              metadata:
                explode: true
                style: deepObject
              owner:
                explode: true
                style: deepObject
              source_order:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSourcesSourceRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
  /v1/sources/{source}/mandate_notifications/{mandate_notification}:
    get:
      description: <p>Retrieves a new Source MandateNotification.</p>
      operationId: GetSourcesSourceMandateNotificationsMandateNotification
      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: mandate_notification
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - in: path
        name: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetSourcesSourceMandateNotificationsMandateNotificationRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source_mandate_notification'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
  /v1/sources/{source}/source_transactions:
    get:
      description: <p>List source transactions for a given source.</p>
      operationId: GetSourcesSourceSourceTransactions
      parameters:
      - 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: 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
      - in: path
        name: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - 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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetSourcesSourceSourceTransactionsRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/ApmsSourcesSourceTransactionList'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
  /v1/sources/{source}/source_transactions/{source_transaction}:
    get:
      description: <p>Retrieve an existing source transaction object. Supply the unique source ID from a source creation request and the source transaction ID and Stripe will return the corresponding up-to-date source object information.</p>
      operationId: GetSourcesSourceSourceTransactionsSourceTransaction
      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: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      - in: path
        name: source_transaction
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetSourcesSourceSourceTransactionsSourceTransactionRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source_transaction'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
  /v1/sources/{source}/verify:
    post:
      description: <p>Verify a given source.</p>
      operationId: PostSourcesSourceVerify
      parameters:
      - in: path
        name: source
        required: true
        schema:
          maxLength: 5000
          type: string
        style: simple
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding:
              expand:
                explode: true
                style: deepObject
              values:
                explode: true
                style: deepObject
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/PostSourcesSourceVerifyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      tags:
      - Sources
components:
  schemas:
    source:
      description: '`Source` objects allow you to accept a variety of payment methods. They

        represent a customer''s payment instrument, and can be used with the Stripe API

        just like a `Card` object: once chargeable, they can be charged, or can be

        attached to customers.


        Stripe doesn''t recommend using the deprecated [Sources API](https://stripe.com/docs/api/sources).

        We recommend that you adopt the [PaymentMethods API](https://stripe.com/docs/api/payment_methods).

        This newer API provides access to our latest features and payment method types.


        Related guides: [Sources API](https://stripe.com/docs/sources) and [Sources & Customers](https://stripe.com/docs/sources/customers).'
      properties:
        ach_credit_transfer:
          $ref: '#/components/schemas/source_type_ach_credit_transfer'
        ach_debit:
          $ref: '#/components/schemas/source_type_ach_debit'
        acss_debit:
          $ref: '#/components/schemas/source_type_acss_debit'
        alipay:
          $ref: '#/components/schemas/source_type_alipay'
        amount:
          description: A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a zero-decimal currency) representing the total amount associated with the source. This is the amount for which the source will be chargeable once ready. Required for `single_use` sources.
          nullable: true
          type: integer
        au_becs_debit:
          $ref: '#/components/schemas/source_type_au_becs_debit'
        bancontact:
          $ref: '#/components/schemas/source_type_bancontact'
        card:
          $ref: '#/components/schemas/source_type_card'
        card_present:
          $ref: '#/components/schemas/source_type_card_present'
        client_secret:
          description: The client secret of the source. Used for client-side retrieval using a publishable key.
          maxLength: 5000
          type: string
        code_verification:
          $ref: '#/components/schemas/source_code_verification_flow'
        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) associated with the source. This is the currency for which the source will be chargeable once ready. Required for `single_use` sources.
          nullable: true
          type: string
        customer:
          description: The ID of the customer to which this source is attached. This will not be present when the source has not been attached to a customer.
          maxLength: 5000
          type: string
        eps:
          $ref: '#/components/schemas/source_type_eps'
        flow:
          description: The authentication `flow` of the source. `flow` is one of `redirect`, `receiver`, `code_verification`, `none`.
          maxLength: 5000
          type: string
        giropay:
          $ref: '#/components/schemas/source_type_giropay'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        ideal:
          $ref: '#/components/schemas/source_type_ideal'
        klarna:
          $ref: '#/components/schemas/source_type_klarna'
        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
        multibanco:
          $ref: '#/components/schemas/source_type_multibanco'
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - source
          type: string
        owner:
          anyOf:
          - $ref: '#/components/schemas/source_owner'
          description: Information about the owner of the payment instrument that may be used or required by particular source types.
          nullable: true
        p24:
          $ref: '#/components/schemas/source_type_p24'
        receiver:
          $ref: '#/components/schemas/source_receiver_flow'
        redirect:
          $ref: '#/components/schemas/source_redirect_flow'
        sepa_debit:
          $ref: '#/components/schemas/source_type_sepa_debit'
        sofort:
          $ref: '#/components/schemas/source_type_sofort'
        source_order:
          $ref: '#/components/schemas/source_order'
        statement_descriptor:
          description: Extra information about a source. This will appear on your customer's statement every time you charge the source.
          maxLength: 5000
          nullable: true
          type: string
        status:
          description: The status of the source, one of `canceled`, `chargeable`, `consumed`, `failed`, or `pending`. Only `chargeable` sources can be used to create a charge.
          maxLength: 5000
          type: string
        three_d_secure:
          $ref: '#/components/schemas/source_type_three_d_secure'
        type:
          description: The `type` of the source. The `type` is a payment method, one of `ach_credit_transfer`, `ach_debit`, `alipay`, `bancontact`, `card`, `card_present`, `eps`, `giropay`, `ideal`, `multibanco`, `klarna`, `p24`, `sepa_debit`, `sofort`, `three_d_secure`, or `wechat`. An additional hash is included on the source with a name matching this value. It contains additional information specific to the [payment method](https://stripe.com/docs/sources) used.
          enum:
          - ach_credit_transfer
          - ach_debit
          - acss_debit
          - alipay
          - au_becs_debit
          - bancontact
          - card
          - card_present
          - eps
          - giropay
          - ideal
          - klarna
          - multibanco
          - p24
          - sepa_debit
          - sofort
          - three_d_secure
          - wechat
          type: string
          x-stripeBypassValidation: true
        usage:
          description: Either `reusable` or `single_use`. Whether this source should be reusable or not. Some source types may or may not be reusable by construction, while others may leave the option at creation. If an incompatible value is passed, an error will be returned.
          maxLength: 5000
          nullable: true
          type: string
        wechat:
          $ref: '#/components/schemas/source_type_wechat'
      required:
      - client_secret
      - created
      - flow
      - id
      - livemode
      - object
      - status
      - type
      title: Source
      type: object
      x-expandableFields:
      - code_verification
      - owner
      - receiver
      - redirect
      - source_order
      x-resourceId: source
    GetCustomersCustomerSourcesIdRequest:
      type: object
      properties: {}
    PostCustomersCustomerSourcesIdVerifyRequest:
      type: object
      properties:
        amounts:
          description: Two positive integers, in *cents*, equal to the values of the microdeposits sent to the bank account.
          items:
            type: integer
          type: array
        expand:
          description: Specifies which fields in the response should be expanded.
          items:
            maxLength: 5000
            type: string
          type: array
    PostCustomersCustomerSourcesIdRequest:
      type: object
      properties:
        account_holder_name:
          description: The name of the person or business that owns the bank account.
          maxLength: 5000
          type: string
        account_holder_type:
          description: The type of entity that holds the account. This can be either `individual` or `company`.
          enum:
          - company
          - individual
          maxLength: 5000
          type: string
        address_city:
          description: City/District/Suburb/Town/Village.
          maxLength: 5000
          type: string
        address_country:
          description: Billing address country, if provided when creating card.
          maxLength: 5000
          type: string
        address_line1:
          description: Address line 1 (Street address/PO Box/Company name).
          maxLengt

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