Cash Balance Transaction

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.

Endpoints

POST/v1/customers/:id/funding_instructions

GET/v1/customers/:id/cash_balance_transactions/:id

GET/v1/customers/:id/cash_balance_transactions

POST/v1/test_helpers/customers/:id/fund_cash_balance

The Cash Balance Transaction object

Attributes

idstring
Unique identifier for the object.

objectstring
String representing the object’s type. Objects of the same type share the same value.

adjusted_for_overdraftnullable object
If this is a type=adjusted_for_overdraft transaction, contains information about what caused the overdraft, which triggered this transaction.

applied_to_paymentnullable object
If this is a type=applied_to_payment transaction, contains information about how funds were applied.

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

currencystring
Three-letter ISO currency code, in lowercase. Must be a supported currency.

customerstringExpandable
The customer whose available cash balance changed as a result of this transaction.

ending_balanceinteger
The total available cash balance for the specified currency after this transaction was applied. Represented in the smallest currency unit.

fundednullable object
If this is a type=funded transaction, contains information about the funding.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

net_amountinteger
The amount by which the cash balance changed, represented in the smallest currency unit. A positive value represents funds being added to the cash balance, a negative value represents funds being removed from the cash balance.

refunded_from_paymentnullable object
If this is a type=refunded_from_payment transaction, contains information about the source of the refund.

transferred_to_balancenullable object
If this is a type=transferred_to_balance transaction, contains the balance transaction linked to the transfer.

typeenum

The type of the cash balance transaction. New types may be added in future. See Customer Balance to learn more about these types.

Possible enum values

adjusted_for_overdraft

A cash balance transaction type: adjusted_for_overdraft

applied_to_payment

A cash balance transaction type: applied_to_payment

funded

A cash balance transaction type: funded

funding_reversed

A cash balance transaction type: funding_reversed

refunded_from_payment

A cash balance transaction type: refunded_from_payment

return_canceled

A cash balance transaction type: return_canceled

return_initiated

A cash balance transaction type: return_initiated

transferred_to_balance

A cash balance transaction type: transferred_to_balance

unapplied_from_payment

A cash balance transaction type: unapplied_from_payment

unapplied_from_paymentnullable object
If this is a type=unapplied_from_payment transaction, contains information about how funds were unapplied.

The Cash Balance Transaction object

{
  "id": "ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF",
  "object": "customer_cash_balance_transaction",
  "created": 1690829143,
  "currency": "eur",
  "customer": "cus_9s6XKzkNRiz8i3",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 28278FC-155",
      "type": "eu_bank_transfer"
    }
  },
  "livemode": false,
  "net_amount": 5000,
  "type": "funded"
}

Create or retrieve funding instructions for a customer cash balance

Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.

Parameters

bank_transferobjectRequired
Additional parameters for bank_transfer funding types

currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.

funding_typeenumRequired
The funding_type to get the instructions for.
Possible enum values
bank_transfer
Use a bank_transfer hash to define the bank transfer type

Returns

Returns funding instructions for a customer cash balance

POST /v1/customers/:id/funding_instructions

Server-side language

curl https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/funding_instructions \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d funding_type=bank_transfer \
  -d currency=eur \
  -d "bank_transfer[type]"=eu_bank_transfer \
  -d "bank_transfer[eu_bank_transfer][country]"=DE

Response

{
  "object": "funding_instructions",
  "bank_transfer": {
    "country": "DE",
    "financial_addresses": [
      {
        "iban": {
          "account_holder_address": {
            "city": "Dublin",
            "country": "IE",
            "line1": "Some address",
            "line2": null,
            "postal_code": "D01H104",
            "state": "Dublin 1"
          },
          "account_holder_name": "Merchant name",
          "bank_address": {
            "city": "Dublin",
            "country": "IE",
            "line1": "1 North Wall Quay",
            "line2": null,
            "postal_code": "D01 T8Y1",
            "state": "Dublin"
          },
          "bic": "SOGEDEFFXXX",
          "country": "DE",
          "iban": "DE006847740991234567890"
        },
        "supported_networks": [
          "sepa",
          "swift"
        ],
        "type": "iban"
      }
    ],
    "type": "eu_bank_transfer"
  },
  "currency": "eur",
  "funding_type": "bank_transfer",
  "livemode": false
}

Retrieve a cash balance transaction

Retrieves a specific cash balance transaction, which updated the customer’s cash balance.

Parameters

No parameters.

Returns

Returns a cash balance transaction object if a valid identifier was provided.

GET /v1/customers/:id/cash_balance_transactions/:id

Server-side language

curl https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions/ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

Response

{
  "id": "ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF",
  "object": "customer_cash_balance_transaction",
  "created": 1690829143,
  "currency": "eur",
  "customer": "cus_9s6XKzkNRiz8i3",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 28278FC-155",
      "type": "eu_bank_transfer"
    }
  },
  "livemode": false,
  "net_amount": 5000,
  "type": "funded"
}

List cash balance transactions

Returns a list of transactions that modified the customer’s cash balance.

Parameters

No parameters.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit cash balance transactions, starting after item starting_after. Each entry in the array is a separate cash balance transaction object. If no more items are available, the resulting array will be empty.

GET /v1/customers/:id/cash_balance_transactions

Server-side language

curl -G https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions",
  "has_more": false,
  "data": [
    {
      "id": "ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF",
      "object": "customer_cash_balance_transaction",
      "created": 1690829143,
      "currency": "eur",
      "customer": "cus_9s6XKzkNRiz8i3",
      "ending_balance": 10000,
      "funded": {
        "bank_transfer": {
          "eu_bank_transfer": {
            "bic": "BANKDEAAXXX",
            "iban_last4": "7089",
            "sender_name": "Sample Business GmbH"
          },
          "reference": "Payment for Invoice 28278FC-155",
          "type": "eu_bank_transfer"
        }
      },
      "livemode": false,
      "net_amount": 5000,
      "type": "funded"
    }
  ]
}

Cash Balance Transaction

The Cash Balance Transaction object

Attributes

idstring

objectstring

adjusted_for_overdraftnullable object

applied_to_paymentnullable object

createdtimestamp

currencystring

customerstringExpandable

ending_balanceinteger

fundednullable object

livemodeboolean

net_amountinteger

refunded_from_paymentnullable object

transferred_to_balancenullable object

typeenum

unapplied_from_paymentnullable object

Create or retrieve funding instructions for a customer cash balance

Parameters

bank_transferobjectRequired

currencyenumRequired

funding_typeenumRequired

Returns

Retrieve a cash balance transaction

Parameters

Returns

List cash balance transactions

Parameters

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

More parameters