API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/balance
Retrieve balance
Retrieves the current account balance, based on the authentication that was used to make the request. For a sample request, see Accounting for negative balances.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
available required | array of balance_amount | Available funds that you can transfer or pay out automatically by Stripe or explicitly through the [Transfers API](https://api.stripe.com#transfers) or [Payouts API](https://api.stripe.com#payouts). You can find the available balance for each currency and payment type in the `source_types` property. |
connect_reserved | array of balance_amount | Funds held due to negative balances on connected accounts where [account.controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. You can find the connect reserve balance for each currency and payment type in the `source_types` property. |
instant_available | array of balance_amount_net | Funds that you can pay out using Instant Payouts. |
issuing | balance_detail | |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
pending required | array of balance_amount | Funds that aren't available in the balance yet. You can find the pending balance for each currency and each payment type in the `source_types` property. |
refund_and_dispute_prefunding | balance_detail_ungated |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/balance/history
List all balance transactions
Returns a list of transactions that have contributed to the Stripe account balance (for example, charges, transfers, and so on). The transactions return in sorted order, with the most recent transactions appearing first. The previous name of this endpoint was “Balance history,” and it used the path /v1/balance/history.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
created | query | one of multiple schemas | Only return transactions that were created during the given date interval. |
currency | query | string | Only return transactions in a certain currency. Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
payout | query | string | For automatic Stripe payouts only, only returns transactions that were paid out on the specified payout ID. |
source | query | string | Only returns transactions associated with the given object. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
type | query | string | Only returns transactions of the given type. One of: `tax_fund`, `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `inbound_transfer`, `inbound_transfer_reversal`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `payout_minimum_balance_hold`, `payout_minimum_balance_release`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `reserve_hold`, `reserve_release`, `stripe_fee`, `stripe_fx_fee`, `stripe_balance_payment_debit`, `stripe_balance_payment_debit_reversal`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, `transfer_refund`, or `fee_credit_funding`. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of balance_transaction | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/balance/history/{id}
Retrieve a balance transaction
Retrieves the balance transaction with the given ID. Note that this endpoint previously used the path /v1/balance/history/:id.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
expand | query | array of string | Specifies which fields in the response should be expanded. |
id | path | string |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
amount required | integer | Gross amount of this transaction (in cents (or local equivalent)). A positive value represents funds charged to another party, and a negative value represents funds sent to another party. |
available_on required | integer | The date that the transaction's net funds become available in the Stripe balance. |
balance_type required | string | The balance that this transaction impacts. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
description | string | An arbitrary string attached to the object. Often useful for displaying to users. |
exchange_rate | number | If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multiplied by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`. |
fee required | integer | Fees (in cents (or local equivalent)) paid for this transaction. Represented as a positive integer when assessed. |
fee_details required | array of fee | Detailed breakdown of fees (in cents (or local equivalent)) paid for this transaction. |
id required | string | Unique identifier for the object. |
net required | integer | Net impact to a Stripe balance (in cents (or local equivalent)). A positive value represents incrementing a Stripe balance, and a negative value decrementing a Stripe balance. You can calculate the net impact of a transaction on a balance by `amount` - `fee` |
object required | string | String representing the object's type. Objects of the same type share the same value. |
reporting_category required | string | Learn more about how [reporting categories](https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective. |
source | one of multiple schemas | This transaction relates to the Stripe object. |
status required | string | The transaction's net funds status in the Stripe balance, which are either `available` or `pending`. |
type required | string | Transaction type: `tax_fund`, `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `inbound_transfer`, `inbound_transfer_reversal`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `payout_minimum_balance_hold`, `payout_minimum_balance_release`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `reserve_hold`, `reserve_release`, `stripe_fee`, `stripe_fx_fee`, `stripe_balance_payment_debit`, `stripe_balance_payment_debit_reversal`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, `transfer_refund`, or `fee_credit_funding`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |