API reference

Balance

This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account. The top-level available and pending comprise your "payments balance." Related guide: Balances and settlement time, Understanding Connect account balances

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Base URL
https://api.knoxapi.com

Retrieve balance

GET/v1/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.

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The balance object.

GET /v1/balance
curl https://api.knoxapi.com/v1/balance \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "available": [
    {
      "amount": 0,
      "currency": "usd",
      "source_types": {
        "card": 0
      }
    }
  ],
  "connect_reserved": [
    {
      "amount": 0,
      "currency": "usd"
    }
  ],
  "livemode": false,
  "object": "balance",
  "pending": [
    {
      "amount": 0,
      "currency": "usd",
      "source_types": {
        "card": 0
      }
    }
  ]
}

List all balance transactions

GET/v1/balance/history

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.

Query parameters

  • createdobject | integer

    Only return transactions that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • currencystring

    Only return transactions in a certain currency. Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • ending_beforestring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • payoutstring

    For automatic Stripe payouts only, only returns transactions that were paid out on the specified payout ID.

  • sourcestring

    Only returns transactions associated with the given object.

  • starting_afterstring

    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.

  • typestring

    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.

Returns

A list of balance_transaction objects.

GET /v1/balance/history
curl -G https://api.knoxapi.com/v1/balance/history \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    {
      "amount": 100,
      "available_on": 1234567890,
      "created": 1234567890,
      "currency": "usd",
      "description": "My First Test Charge (created for API docs)",
      "exchange_rate": null,
      "fee": 0,
      "fee_details": [],
      "id": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
      "net": 100,
      "object": "balance_transaction",
      "reporting_category": "charge",
      "source": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
      "status": "available",
      "type": "charge",
      "balance_type": "payments"
    }
  ]
}

Retrieve a balance transaction

GET/v1/balance/history/{id}

Retrieves the balance transaction with the given ID. Note that this endpoint previously used the path /v1/balance/history/:id.

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The balance_transaction object.

GET /v1/balance/history/{id}
curl https://api.knoxapi.com/v1/balance/history/txn_1PgaxNB7WZ01zgkWEV3TLf40 \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 100,
  "available_on": 1234567890,
  "created": 1234567890,
  "currency": "usd",
  "description": "My First Test Charge (created for API docs)",
  "exchange_rate": null,
  "fee": 0,
  "fee_details": [],
  "id": "txn_1PgaxNB7WZ01zgkWEV3TLf40",
  "net": 100,
  "object": "balance_transaction",
  "reporting_category": "charge",
  "source": "ch_1PgafuB7WZ01zgkWXYmPNZs8",
  "status": "available",
  "type": "charge",
  "balance_type": "payments"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.