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.
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 valuefalse
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 valuesadjusted_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.
{
"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"
}
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.
{
"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.
{
"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"
}
{...}
{...}
],
}
Fund a test mode cash balanceTest helper
Create an incoming testmode bank transfer
Parameters
- amountintegerRequired
Amount to be used for this test cash balance transaction. A positive integer representing how much to fund in the smallest currency unit (e.g., 100 cents to fund $1.00 or 100 to fund ¥100, a zero-decimal currency).
- currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.
More parameters
- referencestring
Returns
Returns a specific cash balance transaction, which funded the customer’s cash balance.
{
"id": "ccsbtxn_1NlhIV2eZvKYlo2CKwRcXkii",
"object": "customer_cash_balance_transaction",
"created": 1693612963,
"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"
}