Cash Balance Transactions

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.

Was this section helpful? Yes No

Create or retrieve funding instructions for a customer cash balance

POST / v1 / customers /:id / funding_instructions

Retrieve a cash balance transaction

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

List cash balance transactions

GET / v1 / customers /:id / cash_balance_transactions

Fund a test mode cash balance

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

The Cash Balance Transaction object

Attributes

• id string Unique identifier for the object.
• object string, value is "customer_cash_balance_transaction" String representing the object’s type. Objects of the same type share the same value.
• adjusted _ for _ overdraft nullable object If this is a type=adjusted_for_overdraft transaction, contains information about what caused the overdraft, which triggered this transaction.
• applied _ to _ payment nullable object If this is a type=applied_to_payment transaction, contains information about how funds were applied.
• created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
• currency string Three-letter ISO currency code, in lowercase. Must be a supported currency.
• customer string Expandable The customer whose available cash balance changed as a result of this transaction.
• customer _ account nullable string The ID of an Account representing a customer whose available cash balance changed as a result of this transaction.
• ending _ balance integer The total available cash balance for the specified currency after this transaction was applied. Represented in the smallest currency unit.
• funded nullable object If this is a type=funded transaction, contains information about the funding.
• livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
• net _ amount integer 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 _ payment nullable object If this is a type=refunded_from_payment transaction, contains information about the source of the refund.
• transferred _ to _ balance nullable object If this is a type=transferred_to_balance transaction, contains the balance transaction linked to the transfer.
• type enum 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 _ payment nullable 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

POST / v1 / customers /:id / funding_instructions

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 _ transfer object Required Additional parameters for bank_transfer funding types
• currency enum Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
• funding _ type enum Required 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

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}