Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Stripe Accounts Account Cash API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Cash
paths:
/v1/customers/{customer}/cash_balance:
get:
description: <p>Retrieves a customer’s cash balance.</p>
operationId: getCustomersCustomerCashBalance
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerCashBalanceRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/cash_balance'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Cash Balance
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cash
post:
description: <p>Changes the settings on a customer’s cash balance.</p>
operationId: postCustomersCustomerCashBalance
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
settings:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCustomersCustomerCashBalanceRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/cash_balance'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Customers Customer Cash Balance
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cash
/v1/customers/{customer}/cash_balance_transactions:
get:
description: <p>Returns a list of transactions that modified the customer’s <a href="/docs/payments/customer-balance">cash balance</a>.</p>
operationId: getCustomersCustomerCashBalanceTransactions
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerCashBalanceTransactionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: 'Customers with certain payments enabled have a cash balance, representing funds that were paid
by the customer to a merchant, but have not yet been allocated to a payment. Cash Balance Transactions
represent when funds are moved into or out of this balance. This includes funding by the customer, allocation
to payments, and refunds to the customer.'
x-expandableFields:
- data
$ref: '#/components/schemas/CustomerCashBalanceTransactionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Cash Balance Transactions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cash
/v1/customers/{customer}/cash_balance_transactions/{transaction}:
get:
description: <p>Retrieves a specific cash balance transaction, which updated the customer’s <a href="/docs/payments/customer-balance">cash balance</a>.</p>
operationId: getCustomersCustomerCashBalanceTransactionsTransaction
parameters:
- in: path
name: customer
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: transaction
required: true
schema:
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCustomersCustomerCashBalanceTransactionsTransactionRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/customer_cash_balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Customers Customer Cash Balance Transactions Transaction
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cash
components:
schemas:
customer:
description: 'This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.
Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)'
properties:
address:
anyOf:
- $ref: '#/components/schemas/address'
description: The customer's address.
balance:
description: The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
type: integer
cash_balance:
anyOf:
- $ref: '#/components/schemas/cash_balance'
description: The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
currency:
description: Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
maxLength: 5000
type:
- string
- 'null'
default_source:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
description: 'ID of the default payment source for the customer.
If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.'
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
x-stripeBypassValidation: true
delinquent:
description: 'Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.
If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn''t reset to `false`.
If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.'
type:
- boolean
- 'null'
description:
description: An arbitrary string attached to the object. Often useful for displaying to users.
maxLength: 5000
type:
- string
- 'null'
discount:
anyOf:
- $ref: '#/components/schemas/discount'
description: Describes the current discount active on the customer, if there is one.
email:
description: The customer's email address.
maxLength: 5000
type:
- string
- 'null'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
invoice_credit_balance:
additionalProperties:
type: integer
description: The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
type: object
invoice_prefix:
description: The prefix for the customer used to generate unique invoice numbers.
maxLength: 5000
type:
- string
- 'null'
invoice_settings:
$ref: '#/components/schemas/invoice_setting_customer_setting'
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
type: object
name:
description: The customer's full name or business name.
maxLength: 5000
type:
- string
- 'null'
next_invoice_sequence:
description: The suffix of the customer's next invoice number (for example, 0001).
type: integer
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- customer
type: string
phone:
description: The customer's phone number.
maxLength: 5000
type:
- string
- 'null'
preferred_locales:
description: The customer's preferred locales (languages), ordered by preference.
items:
maxLength: 5000
type: string
type:
- array
- 'null'
shipping:
anyOf:
- $ref: '#/components/schemas/shipping'
description: Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
sources:
description: The customer's payment sources, if any.
properties:
data:
description: Details about each object.
items:
anyOf:
- $ref: '#/components/schemas/bank_account'
- $ref: '#/components/schemas/card'
- $ref: '#/components/schemas/source'
title: Polymorphic
x-stripeBypassValidation: true
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
required:
- data
- has_more
- object
- url
title: ApmsSourcesSourceList
type: object
x-expandableFields:
- data
subscriptions:
description: The customer's current subscriptions, if any.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/subscription'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
required:
- data
- has_more
- object
- url
title: SubscriptionList
type: object
x-expandableFields:
- data
tax:
$ref: '#/components/schemas/customer_tax'
tax_exempt:
description: 'Describes the customer''s tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.'
enum:
- exempt
- none
- reverse
type:
- string
- 'null'
tax_ids:
description: The customer's tax IDs.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/tax_id'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
required:
- data
- has_more
- object
- url
title: TaxIDsList
type: object
x-expandableFields:
- data
test_clock:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/test_helpers.test_clock'
description: ID of the test clock that this customer belongs to.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/test_helpers.test_clock'
required:
- created
- id
- livemode
- object
title: Customer
type: object
x-expandableFields:
- address
- cash_balance
- default_source
- discount
- invoice_settings
- shipping
- sources
- subscriptions
- tax
- tax_ids
- test_clock
x-resourceId: customer
GetCustomersCustomerCashBalanceTransactionsRequest:
type: object
properties: {}
card:
description: 'You can store multiple cards on a customer in order to charge the customer
later. You can also store multiple debit cards on a recipient in order to
transfer to those cards later.
Related guide: [Card payments with Sources](https://stripe.com/docs/sources/cards)'
properties:
account:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/account'
description: The account this card belongs to. This attribute will not be in the card object if the card belongs to a customer or recipient instead.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/account'
address_city:
description: City/District/Suburb/Town/Village.
maxLength: 5000
type:
- string
- 'null'
address_country:
description: Billing address country, if provided when creating card.
maxLength: 5000
type:
- string
- 'null'
address_line1:
description: Address line 1 (Street address/PO Box/Company name).
maxLength: 5000
type:
- string
- 'null'
address_line1_check:
description: 'If `address_line1` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.'
maxLength: 5000
type:
- string
- 'null'
address_line2:
description: Address line 2 (Apartment/Suite/Unit/Building).
maxLength: 5000
type:
- string
- 'null'
address_state:
description: State/County/Province/Region.
maxLength: 5000
type:
- string
- 'null'
address_zip:
description: ZIP or postal code.
maxLength: 5000
type:
- string
- 'null'
address_zip_check:
description: 'If `address_zip` was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`.'
maxLength: 5000
type:
- string
- 'null'
available_payout_methods:
description: A set of available payout methods for this card. Only values from this set should be passed as the `method` when creating a payout.
items:
enum:
- instant
- standard
type: string
type:
- array
- 'null'
brand:
description: Card brand. Can be `American Express`, `Diners Club`, `Discover`, `Eftpos Australia`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`.
maxLength: 5000
type: string
country:
description: Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you've collected.
maxLength: 5000
type:
- string
- 'null'
currency:
description: Three-letter [ISO code for currency](https://stripe.com/docs/payouts). Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency.
type:
- string
- 'null'
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The customer that this card belongs to. This attribute will not be in the card object if the card belongs to an account or recipient instead.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
cvc_check:
description: 'If a CVC was provided, results of the check: `pass`, `fail`, `unavailable`, or `unchecked`. A result of unchecked indicates that CVC was provided but hasn''t been checked yet. Checks are typically performed when attaching a card to a Customer object, or when creating a charge. For more details, see [Check if a card is valid without a charge](https://support.stripe.com/questions/check-if-a-card-is-valid-without-a-charge).'
maxLength: 5000
type:
- string
- 'null'
default_for_currency:
description: Whether this card is the default external account for its currency.
type:
- boolean
- 'null'
dynamic_last4:
description: (For tokenized numbers only.) The last four digits of the device account number.
maxLength: 5000
type:
- string
- 'null'
exp_month:
description: Two-digit number representing the card's expiration month.
type: integer
exp_year:
description: Four-digit number representing the card's expiration year.
type: integer
fingerprint:
description: 'Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example. For payment methods that tokenize card information (Apple Pay, Google Pay), the tokenized number might be provided instead of the underlying card number.
*As of May 1, 2021, card fingerprint in India for Connect changed to allow two fingerprints for the same cardone for India and one for the rest of the world.*'
maxLength: 5000
type:
- string
- 'null'
funding:
description: Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
maxLength: 5000
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last four digits of the card.
maxLength: 5000
type: string
metadata:
additionalProperties:
maxLength: 500
type: string
description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
type:
- object
- 'null'
name:
description: Cardholder name.
maxLength: 5000
type:
- string
- 'null'
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- card
type: string
status:
description: For external accounts that are cards, possible values are `new` and `errored`. If a payout fails, the status is set to `errored` and [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) are stopped until account details are updated.
maxLength: 5000
type:
- string
- 'null'
tokenization_method:
description: If the card number is tokenized, this is the method that was used. Can be `android_pay` (includes Google Pay), `apple_pay`, `masterpass`, `visa_checkout`, or null.
maxLength: 5000
type:
- string
- 'null'
required:
- brand
- exp_month
- exp_year
- funding
- id
- last4
- object
title: Card
type: object
x-expandableFields:
- account
- customer
x-resourceId: card
GetCustomersCustomerCashBalanceRequest:
type: object
properties: {}
tax_id:
description: 'You can add one or multiple tax IDs to a [customer](https://stripe.com/docs/api/customers) or account.
Customer and account tax IDs get displayed on related invoices and credit notes.
Related guides: [Customer tax identification numbers](https://stripe.com/docs/billing/taxes/tax-ids), [Account tax IDs](https://stripe.com/docs/invoicing/connect#account-tax-ids)'
properties:
country:
description: Two-letter ISO code representing the country of the tax ID.
maxLength: 5000
type:
- string
- 'null'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
description: ID of the customer.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- tax_id
type: string
type:
description: Type of the tax ID, one of `ad_nrt`, `ae_trn`, `ar_cuit`, `au_abn`, `au_arn`, `bg_uic`, `bo_tin`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_vat`, `cl_tin`, `cn_tin`, `co_nit`, `cr_tin`, `do_rcn`, `ec_ruc`, `eg_tin`, `es_cif`, `eu_oss_vat`, `eu_vat`, `gb_vat`, `ge_vat`, `hk_br`, `hu_tin`, `id_npwp`, `il_vat`, `in_gst`, `is_vat`, `jp_cn`, `jp_rn`, `jp_trn`, `ke_pin`, `kr_brn`, `li_uid`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `no_vat`, `nz_gst`, `pe_ruc`, `ph_tin`, `ro_tin`, `rs_pib`, `ru_inn`, `ru_kpp`, `sa_vat`, `sg_gst`, `sg_uen`, `si_tin`, `sv_nit`, `th_vat`, `tr_tin`, `tw_vat`, `ua_vat`, `us_ein`, `uy_ruc`, `ve_rif`, `vn_tin`, or `za_vat`. Note that some legacy tax IDs have type `unknown`
enum:
- ad_nrt
- ae_trn
- ar_cuit
- au_abn
- au_arn
- bg_uic
- bo_tin
- br_cnpj
- br_cpf
- ca_bn
- ca_gst_hst
- ca_pst_bc
- ca_pst_mb
- ca_pst_sk
- ca_qst
- ch_vat
- cl_tin
- cn_tin
- co_nit
- cr_tin
- do_rcn
- ec_ruc
- eg_tin
- es_cif
- eu_oss_vat
- eu_vat
- gb_vat
- ge_vat
- hk_br
- hu_tin
- id_npwp
- il_vat
- in_gst
- is_vat
- jp_cn
- jp_rn
- jp_trn
- ke_pin
- kr_brn
- li_uid
- mx_rfc
- my_frp
- my_itn
- my_sst
- no_vat
- nz_gst
- pe_ruc
- ph_tin
- ro_tin
- rs_pib
- ru_inn
- ru_kpp
- sa_vat
- sg_gst
- sg_uen
- si_tin
- sv_nit
- th_vat
- tr_tin
- tw_vat
- ua_vat
- unknown
- us_ein
- uy_ruc
- ve_rif
- vn_tin
- za_vat
type: string
value:
description: Value of the tax ID.
maxLength: 5000
type: string
verification:
anyOf:
- $ref: '#/components/schemas/tax_id_verification'
description: Tax ID verification information.
required:
- created
- id
- livemode
- object
- type
- value
title: tax_id
type: object
x-expandableFields:
- customer
- verification
x-resourceId: tax_id
GetCustomersCustomerCashBalanceTransactionsTransactionRequest:
type: object
properties: {}
CustomerCashBalanceTransactionList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/customer_cash_balance_transaction'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
max
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-cash-api-openapi.yml