API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

GET /v1/charges

List all charges

Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.

Request parameters

Parameter	Location	Type	Description
`created`	query	one of multiple schemas	Only return charges that were created during the given date interval.
`customer`	query	string	Only return charges for the customer specified by this customer ID.
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`payment_intent`	query	string	Only return charges that were created by the PaymentIntent specified by this PaymentIntent ID.
`starting_after`	query	string	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.
`transfer_group`	query	string	Only return charges for this transfer group, limited to 100.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of charge
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges

Create a charge

This method is no longer recommended—use the Payment Intents API to initiate a new payment instead. Confirmation of the PaymentIntent creates the Charge object used to request payment.

Request parameters

Field	Type	Description
`amount`	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`application_fee`	integer
`application_fee_amount`	integer	A fee in cents (or local equivalent) that will be applied to the charge and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the `Stripe-Account` header in order to take an application fee. For more information, see the application fees [documentation](https://docs.stripe.com/connect/direct-charges#collect-fees).
`capture`	boolean	Whether to immediately capture the charge. Defaults to `true`. When `false`, the charge issues an authorization (or pre-authorization), and will need to be [captured](https://api.stripe.com#capture_charge) later. Uncaptured charges expire after a set number of days (7 by default). For more information, see the [authorizing charges and settling later](https://docs.stripe.com/charges/placing-a-hold) documentation.
`card`	one of multiple schemas	A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).
`currency`	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	string	The ID of an existing customer that will be charged in this request.
`description`	string	An arbitrary string which you can attach to a `Charge` object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the `description` of the charge(s) that they are describing.
`destination`	one of multiple schemas
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`on_behalf_of`	string	The Stripe account ID for which these funds are intended. You can specify the business of record as the connected account using the `on_behalf_of` attribute on the charge. For details, see [Creating Separate Charges and Transfers](https://docs.stripe.com/connect/separate-charges-and-transfers#settlement-merchant).
`radar_options`	object	Options to configure Radar. See [Radar Session](https://docs.stripe.com/radar/radar-session) for more information.
`receipt_email`	string	The email address to which this charge's [receipt](https://docs.stripe.com/dashboard/receipts) will be sent. The receipt will not be sent until the charge is paid, and no receipts will be sent for test mode charges. If this charge is for a [Customer](https://docs.stripe.com/api/customers/object), the email address specified here will override the customer's email address. If `receipt_email` is specified for a charge in live mode, a receipt will be sent regardless of your [email settings](https://dashboard.stripe.com/account/emails).
`shipping`	object	Shipping information for the charge. Helps prevent fraud on charges for physical goods.
`source`	string	A payment source to be charged. This can be the ID of a [card](https://docs.stripe.com/api#cards) (i.e., credit or debit card), a [bank account](https://docs.stripe.com/api#bank_accounts), a [source](https://docs.stripe.com/api#sources), a [token](https://docs.stripe.com/api#tokens), or a [connected account](https://docs.stripe.com/connect/account-debits#charging-a-connected-account). For certain sources---namely, [cards](https://docs.stripe.com/api#cards), [bank accounts](https://docs.stripe.com/api#bank_accounts), and attached [sources](https://docs.stripe.com/api#sources)---you must also pass the ID of the associated customer.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`transfer_data`	object	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. For details, see [Grouping transactions](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options).

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`amount_captured` required	integer	Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).
`amount_refunded` required	integer	Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).
`application`	one of multiple schemas	ID of the Connect application that created the charge.
`application_fee`	one of multiple schemas	The application fee (if any) for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`application_fee_amount`	integer	The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
`billing_details` required	billing_details
`calculated_statement_descriptor`	string	The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined. This value only exists for card payments.
`captured` required	boolean	If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer this charge is for if one exists.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`disputed` required	boolean	Whether the charge has been disputed.
`failure_balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the reversal of the balance on your account due to payment failure.
`failure_code`	string	Error code explaining reason for charge failure if available (see [the errors section](https://docs.stripe.com/error-codes) for a list of codes).
`failure_message`	string	Message to user further explaining reason for charge failure if available.
`fraud_details`	one of multiple schemas	Information on fraud assessments for the charge.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of without triggering an automatic transfer. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers) for details.
`outcome`	one of multiple schemas	Details about whether the payment was accepted, and why. See [understanding declines](https://docs.stripe.com/declines) for details.
`paid` required	boolean	`true` if the charge succeeded, or was successfully authorized for later capture.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent associated with this charge, if one exists.
`payment_method`	string	ID of the payment method used in this charge.
`payment_method_details`	one of multiple schemas	Details about the payment method at the time of the transaction.
`presentment_details`	payment_flows_payment_intent_presentment_details
`radar_options`	radar_radar_options
`receipt_email`	string	This is the email address that the receipt for this charge was sent to.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.
`receipt_url`	string	This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
`refunded` required	boolean	Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
`refunds`	object	A list of refunds that have been applied to the charge.
`review`	one of multiple schemas	ID of the review associated with this charge if one exists.
`shipping`	one of multiple schemas	Shipping information for the charge.
`source_transfer`	one of multiple schemas	The transfer ID which created this charge. Only present if the charge came from another Stripe account. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`status` required	string	The status of the payment is either `succeeded`, `pending`, or `failed`.
`transfer`	one of multiple schemas	ID of the transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).
`transfer_data`	one of multiple schemas	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/charges/search

Search charges

Search for charges you’ve previously created using Stripe’s Search Query Language. 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.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`page`	query	string	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.
`query`	query	string	The search query string. See [search query language](https://docs.stripe.com/search#search-query-language) and the list of supported [query fields for charges](https://docs.stripe.com/search#query-fields-for-charges).

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of charge
`has_more` required	boolean
`next_page`	string
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`total_count`	integer	The total number of objects that match the query, only accurate up to 10,000.
`url` required	string

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/charges/{charge}

Retrieve a charge

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.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`amount_captured` required	integer	Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).
`amount_refunded` required	integer	Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).
`application`	one of multiple schemas	ID of the Connect application that created the charge.
`application_fee`	one of multiple schemas	The application fee (if any) for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`application_fee_amount`	integer	The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
`billing_details` required	billing_details
`calculated_statement_descriptor`	string	The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined. This value only exists for card payments.
`captured` required	boolean	If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer this charge is for if one exists.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`disputed` required	boolean	Whether the charge has been disputed.
`failure_balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the reversal of the balance on your account due to payment failure.
`failure_code`	string	Error code explaining reason for charge failure if available (see [the errors section](https://docs.stripe.com/error-codes) for a list of codes).
`failure_message`	string	Message to user further explaining reason for charge failure if available.
`fraud_details`	one of multiple schemas	Information on fraud assessments for the charge.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of without triggering an automatic transfer. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers) for details.
`outcome`	one of multiple schemas	Details about whether the payment was accepted, and why. See [understanding declines](https://docs.stripe.com/declines) for details.
`paid` required	boolean	`true` if the charge succeeded, or was successfully authorized for later capture.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent associated with this charge, if one exists.
`payment_method`	string	ID of the payment method used in this charge.
`payment_method_details`	one of multiple schemas	Details about the payment method at the time of the transaction.
`presentment_details`	payment_flows_payment_intent_presentment_details
`radar_options`	radar_radar_options
`receipt_email`	string	This is the email address that the receipt for this charge was sent to.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.
`receipt_url`	string	This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
`refunded` required	boolean	Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
`refunds`	object	A list of refunds that have been applied to the charge.
`review`	one of multiple schemas	ID of the review associated with this charge if one exists.
`shipping`	one of multiple schemas	Shipping information for the charge.
`source_transfer`	one of multiple schemas	The transfer ID which created this charge. Only present if the charge came from another Stripe account. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`status` required	string	The status of the payment is either `succeeded`, `pending`, or `failed`.
`transfer`	one of multiple schemas	ID of the transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).
`transfer_data`	one of multiple schemas	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}

Update a charge

Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string

Field	Type	Description
`customer`	string	The ID of an existing customer that will be associated with this request. This field may only be updated if there is no existing associated customer with this charge.
`description`	string	An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the `description` of the charge(s) that they are describing.
`expand`	array of string	Specifies which fields in the response should be expanded.
`fraud_details`	object	A set of key-value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a `user_report` key with a value of `fraudulent`. If you believe a charge is safe, include a `user_report` key with a value of `safe`. Stripe will use the information you send to improve our fraud detection algorithms.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`receipt_email`	string	This is the email address that the receipt for this charge will be sent to. If this field is updated, then a new email receipt will be sent to the updated address.
`shipping`	object	Shipping information for the charge. Helps prevent fraud on charges for physical goods.
`transfer_group`	string	A string that identifies this transaction as part of a group. `transfer_group` may only be provided if it has not been set. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`amount_captured` required	integer	Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).
`amount_refunded` required	integer	Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).
`application`	one of multiple schemas	ID of the Connect application that created the charge.
`application_fee`	one of multiple schemas	The application fee (if any) for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`application_fee_amount`	integer	The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
`billing_details` required	billing_details
`calculated_statement_descriptor`	string	The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined. This value only exists for card payments.
`captured` required	boolean	If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer this charge is for if one exists.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`disputed` required	boolean	Whether the charge has been disputed.
`failure_balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the reversal of the balance on your account due to payment failure.
`failure_code`	string	Error code explaining reason for charge failure if available (see [the errors section](https://docs.stripe.com/error-codes) for a list of codes).
`failure_message`	string	Message to user further explaining reason for charge failure if available.
`fraud_details`	one of multiple schemas	Information on fraud assessments for the charge.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of without triggering an automatic transfer. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers) for details.
`outcome`	one of multiple schemas	Details about whether the payment was accepted, and why. See [understanding declines](https://docs.stripe.com/declines) for details.
`paid` required	boolean	`true` if the charge succeeded, or was successfully authorized for later capture.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent associated with this charge, if one exists.
`payment_method`	string	ID of the payment method used in this charge.
`payment_method_details`	one of multiple schemas	Details about the payment method at the time of the transaction.
`presentment_details`	payment_flows_payment_intent_presentment_details
`radar_options`	radar_radar_options
`receipt_email`	string	This is the email address that the receipt for this charge was sent to.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.
`receipt_url`	string	This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
`refunded` required	boolean	Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
`refunds`	object	A list of refunds that have been applied to the charge.
`review`	one of multiple schemas	ID of the review associated with this charge if one exists.
`shipping`	one of multiple schemas	Shipping information for the charge.
`source_transfer`	one of multiple schemas	The transfer ID which created this charge. Only present if the charge came from another Stripe account. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`status` required	string	The status of the payment is either `succeeded`, `pending`, or `failed`.
`transfer`	one of multiple schemas	ID of the transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).
`transfer_data`	one of multiple schemas	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/capture

Capture a charge

Capture the payment of an existing, uncaptured charge that was created with the capture option set to false. Uncaptured payments expire a set number of days after they are created (7 by default), after which they are marked as refunded and capture attempts will fail. Don’t use this method to capture a PaymentIntent-initiated charge. Use Capture a PaymentIntent.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string

Field	Type	Description
`amount`	integer	The amount to capture, which must be less than or equal to the original amount.
`application_fee`	integer	An application fee to add on to this charge.
`application_fee_amount`	integer	An application fee amount to add on to this charge, which must be less than or equal to the original amount.
`expand`	array of string	Specifies which fields in the response should be expanded.
`receipt_email`	string	The email address to send this charge's receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`transfer_data`	object	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. `transfer_group` may only be provided if it has not been set. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`amount_captured` required	integer	Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).
`amount_refunded` required	integer	Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).
`application`	one of multiple schemas	ID of the Connect application that created the charge.
`application_fee`	one of multiple schemas	The application fee (if any) for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`application_fee_amount`	integer	The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
`billing_details` required	billing_details
`calculated_statement_descriptor`	string	The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined. This value only exists for card payments.
`captured` required	boolean	If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer this charge is for if one exists.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`disputed` required	boolean	Whether the charge has been disputed.
`failure_balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the reversal of the balance on your account due to payment failure.
`failure_code`	string	Error code explaining reason for charge failure if available (see [the errors section](https://docs.stripe.com/error-codes) for a list of codes).
`failure_message`	string	Message to user further explaining reason for charge failure if available.
`fraud_details`	one of multiple schemas	Information on fraud assessments for the charge.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of without triggering an automatic transfer. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers) for details.
`outcome`	one of multiple schemas	Details about whether the payment was accepted, and why. See [understanding declines](https://docs.stripe.com/declines) for details.
`paid` required	boolean	`true` if the charge succeeded, or was successfully authorized for later capture.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent associated with this charge, if one exists.
`payment_method`	string	ID of the payment method used in this charge.
`payment_method_details`	one of multiple schemas	Details about the payment method at the time of the transaction.
`presentment_details`	payment_flows_payment_intent_presentment_details
`radar_options`	radar_radar_options
`receipt_email`	string	This is the email address that the receipt for this charge was sent to.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.
`receipt_url`	string	This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
`refunded` required	boolean	Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
`refunds`	object	A list of refunds that have been applied to the charge.
`review`	one of multiple schemas	ID of the review associated with this charge if one exists.
`shipping`	one of multiple schemas	Shipping information for the charge.
`source_transfer`	one of multiple schemas	The transfer ID which created this charge. Only present if the charge came from another Stripe account. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`status` required	string	The status of the payment is either `succeeded`, `pending`, or `failed`.
`transfer`	one of multiple schemas	ID of the transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).
`transfer_data`	one of multiple schemas	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/charges/{charge}/dispute

/v1/charges/{charge}/dispute

Retrieve a dispute for a specified charge.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
`balance_transactions` required	array of balance_transaction	List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
`charge` required	one of multiple schemas	ID of the charge that's disputed.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`enhanced_eligibility_types` required	array of string	List of eligibility types that are included in `enhanced_evidence`.
`evidence` required	dispute_evidence
`evidence_details` required	dispute_evidence_details
`id` required	string	Unique identifier for the object.
`is_charge_refundable` required	boolean	If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's disputed.
`payment_method_details`	dispute_payment_method_details
`reason` required	string	Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://docs.stripe.com/disputes/categories).
`status` required	string	The current status of a dispute. Possible values include:`warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, or `prevented`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/dispute

/v1/charges/{charge}/dispute

Request parameters

Parameter	Location	Type	Description
`charge`	path	string

Field	Type	Description
`evidence`	object	Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`submit`	boolean	Whether to immediately submit evidence to the bank. If `false`, evidence is staged on the dispute. Staged evidence is visible in the API and Dashboard, and can be submitted to the bank by making another request with this attribute set to `true` (the default).

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
`balance_transactions` required	array of balance_transaction	List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
`charge` required	one of multiple schemas	ID of the charge that's disputed.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`enhanced_eligibility_types` required	array of string	List of eligibility types that are included in `enhanced_evidence`.
`evidence` required	dispute_evidence
`evidence_details` required	dispute_evidence_details
`id` required	string	Unique identifier for the object.
`is_charge_refundable` required	boolean	If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's disputed.
`payment_method_details`	dispute_payment_method_details
`reason` required	string	Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://docs.stripe.com/disputes/categories).
`status` required	string	The current status of a dispute. Possible values include:`warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, or `prevented`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/dispute/close

/v1/charges/{charge}/dispute/close

Request parameters

Parameter	Location	Type	Description
`charge`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
`balance_transactions` required	array of balance_transaction	List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
`charge` required	one of multiple schemas	ID of the charge that's disputed.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`enhanced_eligibility_types` required	array of string	List of eligibility types that are included in `enhanced_evidence`.
`evidence` required	dispute_evidence
`evidence_details` required	dispute_evidence_details
`id` required	string	Unique identifier for the object.
`is_charge_refundable` required	boolean	If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's disputed.
`payment_method_details`	dispute_payment_method_details
`reason` required	string	Reason given by cardholder for dispute. Possible values are `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, or `unrecognized`. Learn more about [dispute reasons](https://docs.stripe.com/disputes/categories).
`status` required	string	The current status of a dispute. Possible values include:`warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, or `prevented`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/refund

Create a refund

When you create a new refund, you must specify either a Charge or a PaymentIntent object. 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. You can optionally refund only part of a charge. You can repeat this until the entire charge is refunded. 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.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string	The identifier of the charge to refund.

Field	Type	Description
`amount`	integer	A positive integer in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal) representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge.
`expand`	array of string	Specifies which fields in the response should be expanded.
`instructions_email`	string	For payment methods without native refund support (e.g., Konbini, PromptPay), use this email from the customer to receive refund instructions.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`payment_intent`	string	The identifier of the PaymentIntent to refund.
`reason`	string	String indicating the reason for the refund. If set, possible values are `duplicate`, `fraudulent`, and `requested_by_customer`. If you believe the charge to be fraudulent, specifying `fraudulent` as the reason will add the associated card and email to your [block lists](https://docs.stripe.com/radar/lists), and will also help us improve our fraud detection algorithms.
`refund_application_fee`	boolean	Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Otherwise, the application fee will be refunded in an amount proportional to the amount of the charge refunded. An application fee can be refunded only by the application that created the charge.
`reverse_transfer`	boolean	Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed proportionally to the amount being refunded (either the entire or partial amount).A transfer can be reversed only by the application that created the charge.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount intended to be collected by this payment. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/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://docs.stripe.com/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).
`amount_captured` required	integer	Amount in cents (or local equivalent) captured (can be less than the amount attribute on the charge if a partial capture was made).
`amount_refunded` required	integer	Amount in cents (or local equivalent) refunded (can be less than the amount attribute on the charge if a partial refund was issued).
`application`	one of multiple schemas	ID of the Connect application that created the charge.
`application_fee`	one of multiple schemas	The application fee (if any) for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`application_fee_amount`	integer	The amount of the application fee (if any) requested for the charge. [See the Connect documentation](https://docs.stripe.com/connect/direct-charges#collect-fees) for details.
`balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
`billing_details` required	billing_details
`calculated_statement_descriptor`	string	The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined. This value only exists for card payments.
`captured` required	boolean	If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer this charge is for if one exists.
`description`	string	An arbitrary string attached to the object. Often useful for displaying to users.
`disputed` required	boolean	Whether the charge has been disputed.
`failure_balance_transaction`	one of multiple schemas	ID of the balance transaction that describes the reversal of the balance on your account due to payment failure.
`failure_code`	string	Error code explaining reason for charge failure if available (see [the errors section](https://docs.stripe.com/error-codes) for a list of codes).
`failure_message`	string	Message to user further explaining reason for charge failure if available.
`fraud_details`	one of multiple schemas	Information on fraud assessments for the charge.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`on_behalf_of`	one of multiple schemas	The account (if any) the charge was made on behalf of without triggering an automatic transfer. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers) for details.
`outcome`	one of multiple schemas	Details about whether the payment was accepted, and why. See [understanding declines](https://docs.stripe.com/declines) for details.
`paid` required	boolean	`true` if the charge succeeded, or was successfully authorized for later capture.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent associated with this charge, if one exists.
`payment_method`	string	ID of the payment method used in this charge.
`payment_method_details`	one of multiple schemas	Details about the payment method at the time of the transaction.
`presentment_details`	payment_flows_payment_intent_presentment_details
`radar_options`	radar_radar_options
`receipt_email`	string	This is the email address that the receipt for this charge was sent to.
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this charge. This attribute will be `null` until a receipt has been sent.
`receipt_url`	string	This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
`refunded` required	boolean	Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
`refunds`	object	A list of refunds that have been applied to the charge.
`review`	one of multiple schemas	ID of the review associated with this charge if one exists.
`shipping`	one of multiple schemas	Shipping information for the charge.
`source_transfer`	one of multiple schemas	The transfer ID which created this charge. Only present if the charge came from another Stripe account. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`statement_descriptor`	string	For a non-card charge, text that appears on the customer's statement as the statement descriptor. This value overrides the account's default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). For a card charge, this value is ignored unless you don't specify a `statement_descriptor_suffix`, in which case this value is used as the suffix.
`statement_descriptor_suffix`	string	Provides information about a card charge. Concatenated to the account's [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer's statement. If the account has no prefix value, the suffix is concatenated to the account's statement descriptor.
`status` required	string	The status of the payment is either `succeeded`, `pending`, or `failed`.
`transfer`	one of multiple schemas	ID of the transfer to the `destination` account (only applicable if the charge was created using the `destination` parameter).
`transfer_data`	one of multiple schemas	An optional dictionary including the account to automatically transfer to as part of a destination charge. [See the Connect documentation](https://docs.stripe.com/connect/destination-charges) for details.
`transfer_group`	string	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/charges/{charge}/refunds

List all refunds

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 limit and starting_after parameters to page through additional refunds.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string
`ending_before`	query	string	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.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	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.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of refund	Details about each object.
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/refunds

Create a refund

When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it. 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. You can optionally refund only part of a charge. You can do so multiple times, until the entire charge has been refunded. 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.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string	The identifier of the charge to refund.

Field	Type	Description
`amount`	integer
`currency`	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	string	Customer whose customer balance to refund from.
`expand`	array of string	Specifies which fields in the response should be expanded.
`instructions_email`	string	For payment methods without native refund support (e.g., Konbini, PromptPay), use this email from the customer to receive refund instructions.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/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`.
`origin`	string	Origin of the refund
`payment_intent`	string	The identifier of the PaymentIntent to refund.
`reason`	string	String indicating the reason for the refund. If set, possible values are `duplicate`, `fraudulent`, and `requested_by_customer`. If you believe the charge to be fraudulent, specifying `fraudulent` as the reason will add the associated card and email to your [block lists](https://docs.stripe.com/radar/lists), and will also help us improve our fraud detection algorithms.
`refund_application_fee`	boolean	Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Otherwise, the application fee will be refunded in an amount proportional to the amount of the charge refunded. An application fee can be refunded only by the application that created the charge.
`reverse_transfer`	boolean	Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed proportionally to the amount being refunded (either the entire or partial amount).A transfer can be reversed only by the application that created the charge.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount, in cents (or local equivalent).
`balance_transaction`	one of multiple schemas	Balance transaction that describes the impact on your account balance.
`charge`	one of multiple schemas	ID of the charge that's refunded.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer of this refund.
`customer_account`	string	ID of the account of this refund.
`description`	string	An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
`destination_details`	refund_destination_details
`failure_balance_transaction`	one of multiple schemas	After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.
`failure_reason`	string	Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`.
`id` required	string	Unique identifier for the object.
`instructions_email`	string	For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_action`	refund_next_action
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's refunded.
`payment_method`	one of multiple schemas	ID of the payment method associated with this refund.
`pending_reason`	string	Provides the reason for why the refund is pending. Possible values are: `processing`, `insufficient_funds`, or `charge_pending`.
`presentment_details`	payment_flows_payment_intent_presentment_details
`reason`	string	Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`).
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this refund.
`source_transfer_reversal`	one of multiple schemas	The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.
`status`	string	Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds).
`transfer_reversal`	one of multiple schemas	This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/charges/{charge}/refunds/{refund}

/v1/charges/{charge}/refunds/{refund}

Retrieves the details of an existing refund.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`refund`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount, in cents (or local equivalent).
`balance_transaction`	one of multiple schemas	Balance transaction that describes the impact on your account balance.
`charge`	one of multiple schemas	ID of the charge that's refunded.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer of this refund.
`customer_account`	string	ID of the account of this refund.
`description`	string	An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
`destination_details`	refund_destination_details
`failure_balance_transaction`	one of multiple schemas	After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.
`failure_reason`	string	Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`.
`id` required	string	Unique identifier for the object.
`instructions_email`	string	For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_action`	refund_next_action
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's refunded.
`payment_method`	one of multiple schemas	ID of the payment method associated with this refund.
`pending_reason`	string	Provides the reason for why the refund is pending. Possible values are: `processing`, `insufficient_funds`, or `charge_pending`.
`presentment_details`	payment_flows_payment_intent_presentment_details
`reason`	string	Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`).
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this refund.
`source_transfer_reversal`	one of multiple schemas	The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.
`status`	string	Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds).
`transfer_reversal`	one of multiple schemas	This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/charges/{charge}/refunds/{refund}

/v1/charges/{charge}/refunds/{refund}

Update a specified refund.

Request parameters

Parameter	Location	Type	Description
`charge`	path	string
`refund`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	integer	Amount, in cents (or local equivalent).
`balance_transaction`	one of multiple schemas	Balance transaction that describes the impact on your account balance.
`charge`	one of multiple schemas	ID of the charge that's refunded.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`currency` required	string	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
`customer`	one of multiple schemas	ID of the customer of this refund.
`customer_account`	string	ID of the account of this refund.
`description`	string	An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
`destination_details`	refund_destination_details
`failure_balance_transaction`	one of multiple schemas	After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction.
`failure_reason`	string	Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`.
`id` required	string	Unique identifier for the object.
`instructions_email`	string	For payment methods without native refund support (for example, Konbini, PromptPay), provide an email address for the customer to receive refund instructions.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`next_action`	refund_next_action
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payment_intent`	one of multiple schemas	ID of the PaymentIntent that's refunded.
`payment_method`	one of multiple schemas	ID of the payment method associated with this refund.
`pending_reason`	string	Provides the reason for why the refund is pending. Possible values are: `processing`, `insufficient_funds`, or `charge_pending`.
`presentment_details`	payment_flows_payment_intent_presentment_details
`reason`	string	Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`).
`receipt_number`	string	This is the transaction number that appears on email receipts sent for this refund.
`source_transfer_reversal`	one of multiple schemas	The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account.
`status`	string	Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds).
`transfer_reversal`	one of multiple schemas	This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors