Customer balance

Learn how to use the customer balance with payments.

Your customers might have associated balances that contain two types of funds—cash and credit.

Cash balances

A customer’s cash balance represents funds that they can use for payment. When they overpay or send an amount using a bank transfer that isn’t automatically reconciled with any outstanding payment, we add these funds to the customer cash balance. You can use these funds for later payments for the same customer, or initiate a refund from their cash balance to return the funds to their bank account, limited to the amount available in the customer balance.

A customer can have cash balances in all currencies that you accept bank transfer payments in, each with its own funding instruction.

You can’t add funds to the customer cash balance directly. This isn’t a balance that customers can top up and is only there as a reconciliation layer—it’s not a digital wallet or e-money. You can’t use the cash balance for any other purpose besides future payments, or returns to the customer it’s associated with.

Customer invoice balance

In contrast to a cash balance, an invoice balance is an Invoices feature that represents liability between you and the customer. You can’t use invoice balance funds for payment, but you can apply them to offset future invoices. You can update the invoice balance by creating an adjustment Customer Balance Transaction.

View the customer balance

You can find a customer’s balance with both the API and through the Stripe Dashboard. To view a customer’s balance using the API, first retrieve the Customer and then expand the cash_balance field.

Accounts v2 considerations

The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.

To view the customer balance for a customer-configured Account, use the Customers API endpoint with the Account ID as the path parameter, for example the relevant part of the product.

Command Line

Select a language

curl

Ruby

Python

PHP

Node.js

No results

{
 "id": "cus_HgrkK7bxHMy65g",
 "object": "customer",
 "address": null,
 "cash_balance": {
 "available": {
 "usd": 50,
 },
 "settings": {
 "reconciliation_mode": "automatic"
 },
 "livemode": "true",
 "object": "cash_balance",
 },
 "created": 1598918400,

To view a customer’s balance in the Dashboard, go to the Customer page. The customer’s balance appears in the Payment methods section.

Make a payment from the cash balance

When your customer has a cash balance, you can use the funds immediately to make a payment up to the available amount.

Enable bank transfers as a payment method in your Dashboard before creating the intent.

Command Line

Select a language

curl

Ruby

Python

PHP

Node.js

No results

When your customer has a cash balance, you can use the funds immediately to make a payment up to the available amount. You can do this by using either the API or the Dashboard.

To make a payment using the API, create a PaymentIntent using the customer_balance payment method type.

The payment succeeds if the cash balance has sufficient funds, and fails otherwise.

To collect more funds from the customer when the cash balance is insufficient, use the customer balance with a bank transfer funding.

List changes to the customer balance

Changes to the customer’s cash balance are modeled as a list of cash balance transactions. You can retrieve these transactions for a customer to see how their cash balance has changed over time.

Note

For a customer with multiple cash balances in different currencies, listing changes to the cash balance will return changes for all the different currencies.

Cash balance transaction types

Cash balance transactions have a type value indicating the type of action that caused the cash balance to change.