The Charge object
Attributes
- id string Unique identifier for the object.
- amount integer Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (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. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
- balance _ transaction nullable string Expandable ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
- billing _ details object Billing information associated with the payment method at the time of the transaction.
- currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customer nullable string Expandable ID of the customer this charge is for if one exists.
- description nullable string An arbitrary string attached to the object. Often useful for displaying to users.
- disputed boolean Whether the charge has been disputed.
- metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- payment _ intent nullable string Expandable ID of the PaymentIntent associated with this charge, if one exists.
- payment _ method _ details nullable object Details about the payment method at the time of the transaction.
- receipt _ email nullable string This is the email address that the receipt for this charge was sent to.
- refunded boolean Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
- shipping nullable object Shipping information for the charge.
- statement _ descriptor nullable 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. 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 nullable string Provides information about a card charge. Concatenated to the account’s statement descriptor prefix 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 enum The status of the payment is either
succeeded,pending, orfailed.
More attributes
- object string, value is "charge"
- amount _ captured integer
- amount _ refunded integer
- application nullable string Expandable Connect only
- application _ fee nullable string Expandable Connect only
- application _ fee _ amount nullable integer Connect only
- calculated _ statement _ descriptor nullable string
- captured boolean
- created timestamp
- failure _ balance _ transaction nullable string Expandable
- failure _ code nullable string
- failure _ message nullable string
- fraud _ details nullable object
- livemode boolean
- on _ behalf _ of nullable string Expandable Connect only
- outcome nullable object
- paid boolean
- payment _ method nullable string
- presentment _ details nullable object
- radar _ options nullable object
- receipt _ number nullable string
- receipt _ url nullable string
- refunds nullable object Includable
- review nullable string Expandable
- source _ transfer nullable string Expandable Connect only
- transfer nullable string Expandable Connect only
- transfer _ data nullable object Connect only
- transfer _ group nullable string Connect only
The Charge object
Create a charge Deprecated
POST / v1 / charges
This method is deprecated and will be removed soon. If your integration uses it, you need to update it to use a different payment flow, such as the Payment Intents API.
Parameters
- amount integer Required Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (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. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
- currency enum Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
- customer string The ID of an existing customer that will be charged in this request. The maximum length is 500 characters.
- description string An arbitrary string which you can attach to a
Chargeobject. 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 thedescriptionof the charge(s) that they are describing. - metadata map Set of key-value pairs 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 The email address to which this charge’s receipt 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, the email address specified here will override the customer’s email address. If
receipt_emailis specified for a charge in live mode, a receipt will be sent regardless of your email settings. The maximum length is 800 characters. - 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 (i.e., credit or debit card), a bank account, a source, a token, or a connected account. For certain sources—namely, cards, bank accounts, and attached 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. 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 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.
More parameters
- application _ fee _ amount integer Connect only
- capture boolean
- on _ behalf _ of string Connect only
- radar _ options object
- transfer _ data object Connect only
- transfer _ group string Connect only
Returns
Returns the charge object if the charge succeeded. This call raises an error if something goes wrong. A common source of error is an invalid or expired card, or a valid card with insufficient available balance.
Response
Update a charge
POST / v1 / charges /:id
Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
- 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
descriptionof the charge(s) that they are describing. - metadata map Set of key-value pairs 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.
More parameters
- fraud _ details object
- transfer _ group string Connect only
Returns
Returns the charge object if the update succeeded. This call will raise an error if update parameters are invalid.
Response