Stripe Charges API — Charges

naftiko: 1.0.0-alpha2
info:
  label: Stripe Charges API — Charges
  description: 'Stripe Charges API — Charges. 14 operations. Lead operation: Charges. Self-contained Naftiko capability covering
    one Stripe business surface.'
  tags:
  - Stripe
  - Charges
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    STRIPE_API_KEY: STRIPE_API_KEY
capability:
  consumes:
  - type: http
    namespace: charges-charges
    baseUri: https://api.stripe.com
    description: Stripe Charges API — Charges business capability. Self-contained, no shared references.
    resources:
    - name: v1-charges
      path: /v1/charges
      operations:
      - name: getcharges
        method: GET
        description: <p>Returns a list of charges you’ve previously created. The charges are returned in sorted order, with
          the most recent charges appearing first.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: created
          in: query
          type: string
        - name: customer
          in: query
          type: string
          description: Only return charges for the customer specified by this customer ID.
        - name: ending_before
          in: query
          type: string
          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 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: payment_intent
          in: query
          type: string
          description: Only return charges that were created by the PaymentIntent specified by this PaymentIntent ID.
        - name: starting_after
          in: query
          type: string
          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 o
        - name: transfer_group
          in: query
          type: string
          description: Only return charges for this transfer group.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postcharges
        method: POST
        description: <p>Use the <a href="/docs/api/payment_intents">Payment Intents API</a> to initiate a new payment instead
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-search
      path: /v1/charges/search
      operations:
      - name: getchargessearch
        method: GET
        description: <p>Search for charges you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search
          Query Language</a>.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: page
          in: query
          type: string
          description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first
            call. Use the next_page value returned in a previous respons
        - name: query
          in: query
          type: string
          description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language)
            and the list of supported [query fields for charges](
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge
      path: /v1/charges/{charge}
      operations:
      - name: getchargescharge
        method: GET
        description: <p>Retrieves the details of a charge that has previously been created. Supply the unique charge ID that
          was returned from your previous request, and Stripe will return the corresponding charge information. The same information
          is returned w
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postchargescharge
        method: POST
        description: <p>Updates the specified charge by setting the values of the parameters passed. Any parameters not provided
          will be left unchanged.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-capture
      path: /v1/charges/{charge}/capture
      operations:
      - name: postchargeschargecapture
        method: POST
        description: <p>Capture the payment of an existing, uncaptured charge that was created with the <code>capture</code>
          option set to false.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-dispute
      path: /v1/charges/{charge}/dispute
      operations:
      - name: getchargeschargedispute
        method: GET
        description: <p>Retrieve a dispute for a specified charge.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postchargeschargedispute
        method: POST
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-dispute-close
      path: /v1/charges/{charge}/dispute/close
      operations:
      - name: postchargeschargedisputeclose
        method: POST
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-refund
      path: /v1/charges/{charge}/refund
      operations:
      - name: postchargeschargerefund
        method: POST
        description: <p>When you create a new refund, you must specify either a Charge or a PaymentIntent object.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          description: The identifier of the charge to refund.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-refunds
      path: /v1/charges/{charge}/refunds
      operations:
      - name: getchargeschargerefunds
        method: GET
        description: <p>You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds
          are always available by default on the charge object. If you need more than those 10, you can use this API method
          and the <code>limit<
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: ending_before
          in: query
          type: string
          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 ob
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: limit
          in: query
          type: integer
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default
            is 10.
        - name: starting_after
          in: query
          type: string
          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 o
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postchargeschargerefunds
        method: POST
        description: <p>When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create
          it.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          description: The identifier of the charge to refund.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: v1-charges-charge-refunds-refund
      path: /v1/charges/{charge}/refunds/{refund}
      operations:
      - name: getchargeschargerefundsrefund
        method: GET
        description: <p>Retrieves the details of an existing refund.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: expand
          in: query
          type: array
          description: Specifies which fields in the response should be expanded.
        - name: refund
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: postchargeschargerefundsrefund
        method: POST
        description: <p>Update a specified refund.</p>
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        - name: refund
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.STRIPE_API_KEY}}'
  exposes:
  - type: rest
    namespace: charges-charges-rest
    port: 8080
    description: REST adapter for Stripe Charges API — Charges. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/v1/charges
      name: v1-charges
      description: REST surface for v1-charges.
      operations:
      - method: GET
        name: getcharges
        description: <p>Returns a list of charges you’ve previously created. The charges are returned in sorted order, with
          the most recent charges appearing first.</p>
        call: charges-charges.getcharges
        with:
          created: rest.created
          customer: rest.customer
          ending_before: rest.ending_before
          expand: rest.expand
          limit: rest.limit
          payment_intent: rest.payment_intent
          starting_after: rest.starting_after
          transfer_group: rest.transfer_group
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postcharges
        description: <p>Use the <a href="/docs/api/payment_intents">Payment Intents API</a> to initiate a new payment instead
        call: charges-charges.postcharges
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/search
      name: v1-charges-search
      description: REST surface for v1-charges-search.
      operations:
      - method: GET
        name: getchargessearch
        description: <p>Search for charges you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search
          Query Language</a>.
        call: charges-charges.getchargessearch
        with:
          expand: rest.expand
          limit: rest.limit
          page: rest.page
          query: rest.query
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}
      name: v1-charges-charge
      description: REST surface for v1-charges-charge.
      operations:
      - method: GET
        name: getchargescharge
        description: <p>Retrieves the details of a charge that has previously been created. Supply the unique charge ID that
          was returned from your previous request, and Stripe will return the corresponding charge information. The same information
          is returned w
        call: charges-charges.getchargescharge
        with:
          charge: rest.charge
          expand: rest.expand
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postchargescharge
        description: <p>Updates the specified charge by setting the values of the parameters passed. Any parameters not provided
          will be left unchanged.</p>
        call: charges-charges.postchargescharge
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/capture
      name: v1-charges-charge-capture
      description: REST surface for v1-charges-charge-capture.
      operations:
      - method: POST
        name: postchargeschargecapture
        description: <p>Capture the payment of an existing, uncaptured charge that was created with the <code>capture</code>
          option set to false.</p>
        call: charges-charges.postchargeschargecapture
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/dispute
      name: v1-charges-charge-dispute
      description: REST surface for v1-charges-charge-dispute.
      operations:
      - method: GET
        name: getchargeschargedispute
        description: <p>Retrieve a dispute for a specified charge.</p>
        call: charges-charges.getchargeschargedispute
        with:
          charge: rest.charge
          expand: rest.expand
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postchargeschargedispute
        description: postchargeschargedispute
        call: charges-charges.postchargeschargedispute
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/dispute/close
      name: v1-charges-charge-dispute-close
      description: REST surface for v1-charges-charge-dispute-close.
      operations:
      - method: POST
        name: postchargeschargedisputeclose
        description: postchargeschargedisputeclose
        call: charges-charges.postchargeschargedisputeclose
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/refund
      name: v1-charges-charge-refund
      description: REST surface for v1-charges-charge-refund.
      operations:
      - method: POST
        name: postchargeschargerefund
        description: <p>When you create a new refund, you must specify either a Charge or a PaymentIntent object.</p>
        call: charges-charges.postchargeschargerefund
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/refunds
      name: v1-charges-charge-refunds
      description: REST surface for v1-charges-charge-refunds.
      operations:
      - method: GET
        name: getchargeschargerefunds
        description: <p>You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds
          are always available by default on the charge object. If you need more than those 10, you can use this API method
          and the <code>limit<
        call: charges-charges.getchargeschargerefunds
        with:
          charge: rest.charge
          ending_before: rest.ending_before
          expand: rest.expand
          limit: rest.limit
          starting_after: rest.starting_after
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postchargeschargerefunds
        description: <p>When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create
          it.</p>
        call: charges-charges.postchargeschargerefunds
        with:
          charge: rest.charge
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/charges/{charge}/refunds/{refund}
      name: v1-charges-charge-refunds-refund
      description: REST surface for v1-charges-charge-refunds-refund.
      operations:
      - method: GET
        name: getchargeschargerefundsrefund
        description: <p>Retrieves the details of an existing refund.</p>
        call: charges-charges.getchargeschargerefundsrefund
        with:
          charge: rest.charge
          expand: rest.expand
          refund: rest.refund
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postchargeschargerefundsrefund
        description: <p>Update a specified refund.</p>
        call: charges-charges.postchargeschargerefundsrefund
        with:
          charge: rest.charge
          refund: rest.refund
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: charges-charges-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stripe Charges API — Charges. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: p-returns-list-charges-you-ve-previously
      description: <p>Returns a list of charges you’ve previously created. The charges are returned in sorted order, with
        the most recent charges appearing first.</p>
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getcharges
      with:
        created: tools.created
        customer: tools.customer
        ending_before: tools.ending_before
        expand: tools.expand
        limit: tools.limit
        payment_intent: tools.payment_intent
        starting_after: tools.starting_after
        transfer_group: tools.transfer_group
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-use-href-docs-api-payment
      description: <p>Use the <a href="/docs/api/payment_intents">Payment Intents API</a> to initiate a new payment instead
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postcharges
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-search-charges-you-ve-previously-created
      description: <p>Search for charges you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search
        Query Language</a>.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getchargessearch
      with:
        expand: tools.expand
        limit: tools.limit
        page: tools.page
        query: tools.query
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-retrieves-details-charge-that-has
      description: <p>Retrieves the details of a charge that has previously been created. Supply the unique charge ID that
        was returned from your previous request, and Stripe will return the corresponding charge information. The same information
        is returned w
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getchargescharge
      with:
        charge: tools.charge
        expand: tools.expand
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-updates-specified-charge-setting-values
      description: <p>Updates the specified charge by setting the values of the parameters passed. Any parameters not provided
        will be left unchanged.</p>
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargescharge
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-capture-payment-existing-uncaptured-charge
      description: <p>Capture the payment of an existing, uncaptured charge that was created with the <code>capture</code>
        option set to false.</p>
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargecapture
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-retrieve-dispute-specified-charge-p
      description: <p>Retrieve a dispute for a specified charge.</p>
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getchargeschargedispute
      with:
        charge: tools.charge
        expand: tools.expand
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: postchargeschargedispute
      description: postchargeschargedispute
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargedispute
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: postchargeschargedisputeclose
      description: postchargeschargedisputeclose
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargedisputeclose
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-when-you-create-new-refund
      description: <p>When you create a new refund, you must specify either a Charge or a PaymentIntent object.</p>
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargerefund
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-you-can-see-list-refunds
      description: <p>You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds
        are always available by default on the charge object. If you need more than those 10, you can use this API method
        and the <code>limit<
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getchargeschargerefunds
      with:
        charge: tools.charge
        ending_before: tools.ending_before
        expand: tools.expand
        limit: tools.limit
        starting_after: tools.starting_after
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-when-you-create-new-refund-2
      description: <p>When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create
        it.</p>
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargerefunds
      with:
        charge: tools.charge
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-retrieves-details-existing-refund-p
      description: <p>Retrieves the details of an existing refund.</p>
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: charges-charges.getchargeschargerefundsrefund
      with:
        charge: tools.charge
        expand: tools.expand
        refund: tools.refund
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: p-update-specified-refund-p
      description: <p>Update a specified refund.</p>
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: charges-charges.postchargeschargerefundsrefund
      with:
        charge: tools.charge
        refund: tools.refund
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.