The Charge object represents a single attempt to move money into your Stripe account. PaymentIntent confirmation is the most common way to create Charges, but transferring money to a different Stripe account through Connect also creates Charges. Some legacy payment flows create Charges directly, which is not recommended for new integrations.
openapi: 3.0.0
info:
title: Stripe Charges API
description: Needs description.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/charges:
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>
operationId: getCharges
parameters:
- 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: Only return charges for the customer specified by this customer ID.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
Only return charges that were created by the PaymentIntent specified
by this PaymentIntent ID.
in: query
name: payment_intent
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
- description: Only return charges for this transfer group.
in: query
name: transfer_group
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetChargesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/ChargeList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
post:
description: >-
<p>Use the <a href="/docs/api/payment_intents">Payment Intents API</a>
to initiate a new payment instead
of using this method. Confirmation of the PaymentIntent creates the
<code>Charge</code>
object used to request payment, so this method is limited to legacy
integrations.</p>
operationId: postCharges
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
card:
explode: true
style: deepObject
destination:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
radar_options:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/charge'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/search:
get:
description: >-
<p>Search for charges you’ve previously created using Stripe’s <a
href="/docs/search#search-query-language">Search Query Language</a>.
Don’t use search in read-after-write flows where strict consistency is
necessary. Under normal operating
conditions, data is searchable in less than a minute. Occasionally,
propagation of new or updated data can be up
to an hour behind during outages. Search functionality is not available
to merchants in India.</p>
operationId: getChargesSearch
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
- 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 pagination across multiple pages of results. Don't
include this parameter on the first call. Use the next_page value
returned in a previous response to request subsequent results.
in: query
name: page
required: false
schema:
maxLength: 5000
type: string
style: form
- 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](https://stripe.com/docs/search#query-fields-for-charges).
in: query
name: query
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetChargesSearchRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SearchResult'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges Search
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}:
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 when creating or refunding the
charge.</p>
operationId: getChargesCharge
parameters:
- in: path
name: charge
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/GetChargesChargeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/charge'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges Charge
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
post:
description: >-
<p>Updates the specified charge by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.</p>
operationId: postChargesCharge
parameters:
- in: path
name: charge
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
fraud_details:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/charge'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/capture:
post:
description: >-
<p>Capture the payment of an existing, uncaptured charge that was
created with the <code>capture</code> option set to false.</p>
<p>Uncaptured payments expire a set number of days after they are
created (<a href="/docs/charges/placing-a-hold">7 by default</a>), after
which they are marked as refunded and capture attempts will fail.</p>
<p>Don’t use this method to capture a PaymentIntent-initiated charge.
Use <a href="/docs/api/payment_intents/capture">Capture a
PaymentIntent</a>.</p>
operationId: postChargesChargeCapture
parameters:
- in: path
name: charge
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeCaptureRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/charge'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Capture
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/dispute:
get:
description: <p>Retrieve a dispute for a specified charge.</p>
operationId: getChargesChargeDispute
parameters:
- in: path
name: charge
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/GetChargesChargeDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges Charge Dispute
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
post:
description: ''
operationId: postChargesChargeDispute
parameters:
- in: path
name: charge
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
evidence:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeDisputeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Dispute
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/dispute/close:
post:
description: ''
operationId: postChargesChargeDisputeClose
parameters:
- in: path
name: charge
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeDisputeCloseRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/dispute'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Dispute Close
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/refund:
post:
description: >-
<p>When you create a new refund, you must specify either a Charge or a
PaymentIntent object.</p>
<p>This action refunds a previously created charge that’s not refunded
yet.
Funds are refunded to the credit or debit card that’s originally
charged.</p>
<p>You can optionally refund only part of a charge.
You can repeat this until the entire charge is refunded.</p>
<p>After you entirely refund a charge, you can’t refund it again.
This method raises an error when it’s called on an already-refunded
charge,
or when you attempt to refund more money than is left on a charge.</p>
operationId: postChargesChargeRefund
parameters:
- description: The identifier of the charge to refund.
in: path
name: charge
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
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeRefundRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/charge'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Refund
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/refunds:
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</code> and <code>starting_after</code>
parameters to page through additional refunds.</p>
operationId: getChargesChargeRefunds
parameters:
- in: path
name: charge
required: true
schema:
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/GetChargesChargeRefundsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/RefundList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges Charge Refunds
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
post:
description: >-
<p>When you create a new refund, you must specify a Charge or a
PaymentIntent object on which to create it.</p>
<p>Creating a new refund will refund a charge that has previously been
created but not yet refunded.
Funds will be refunded to the credit or debit card that was originally
charged.</p>
<p>You can optionally refund only part of a charge.
You can do so multiple times, until the entire charge has been
refunded.</p>
<p>Once entirely refunded, a charge can’t be refunded again.
This method will raise an error when called on an already-refunded
charge,
or when trying to refund more money than is left on a charge.</p>
operationId: postChargesChargeRefunds
parameters:
- description: The identifier of the charge to refund.
in: path
name: charge
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
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeRefundsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Refunds
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
/v1/charges/{charge}/refunds/{refund}:
get:
description: <p>Retrieves the details of an existing refund.</p>
operationId: getChargesChargeRefundsRefund
parameters:
- in: path
name: charge
required: true
schema:
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: refund
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetChargesChargeRefundsRefundRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Charges Charge Refunds Refund
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
post:
description: <p>Update a specified refund.</p>
operationId: postChargesChargeRefundsRefund
parameters:
- in: path
name: charge
required: true
schema:
type: string
style: simple
- in: path
name: refund
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostChargesChargeRefundsRefundRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Charges Charge Refunds Refund
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
tags:
- Charges
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
charge:
description: >-
The `Charge` object represents a single attempt to move money into your
Stripe account.
PaymentIntent confirmation is the most common way to create Charges, but
transferring
money to a different Stripe account through Connect also creates
Charges.
Some legacy payment flows create Charges directly, which is not
recommended for new integrations.
properties:
amount:
description: >-
Amount intended to be collected by this payment. A positive integer
representing how much to charge in the [smallest currency
unit](https://stripe.com/docs/currencies#zero-decimal) (e.g., 100
cents to charge $1.00 or 100 to charge ¥100, a zero-decimal
currency). The minimum amount is $0.50 US or [equivalent in charge
currency](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts).
The amount value supports up to eight digits (e.g., a value of
99999999 for a USD charge of $999,999.99).
type: integer
amount_captured:
description: >-
Amount in cents (or local equivalent) captured (can be less than the
amount attribute on the charge if a partial capture was made).
type: integer
amount_refunded:
description: >-
Amount in cents (or local equivalent) refunded (can be less than the
amount attribute on the charge if a partial refund was issued).
type: integer
application:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application'
description: ID of the Connect application that created the charge.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application'
application_fee:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application_fee'
description: >-
The application fee (if any) for the charge. [See the Connect
documentation](https://stripe.com/docs/connect/direct-charges#collecting-fees)
for details.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application_fee'
application_fee_amount:
description: >-
The amount of the application fee (if any) requested for the charge.
[See the Connect
documentation](https://stripe.com/docs/connect/direct-charges#collecting-fees)
for details.
nullable: true
type: inte
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-charges-api-openapi.yml