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 it’s 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.

{
  "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, navigate 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. To do this, create a PaymentIntent using the customer_balance payment method type.

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.

Type	Description
`funded`	The customer has funded their balance by making a bank transfer. Funds represented by these transactions might be automatically applied to payment intents and invoices depending on the reconciliation procedure. If these funds are applied automatically, you’ll see additional transactions of type `applied_to_payment` representing that.
`applied_to_payment`	Funds from the cash balance were applied to a payment intent, either by reconciliation after funding arrives, or by manual reconciliation.
`unapplied_from_payment`	A partially funded payment intent was modified or canceled, and the funds were returned to the customer’s cash balance. You can use these funds for future payments.
`refunded_from_payment`	A successful payment intent has been refunded to the customer cash balance. You can use these funds for future payments.
`return_initiated`	Unspent funds are being returned to the customer’s bank account from their cash balance.
`return_canceled`	An attempt to return funds to the customer’s bank account has been canceled, either because you canceled the refund before the customer submitted their bank details, or we weren’t able to collect bank account details from the customer. For more information about refund state transitions, see Refund bank transfer payments.
`transferred_to_balance`	Funds have been moved from the cash balance to your Stripe balance due to failed refunds or insufficient refund details.