The Stripe API is a powerful interface that allows developers to integrate payment processing capabilities into web and mobile applications. It enables online finance management for e-commerce platforms and digital businesses.

Stripe provides a robust API that allows developers to:

• Manage online payments
• Handle credit card transactions
• Monitor balances and refunds
• Automate payment workflows

In this document, we focus specifically on the Balance API, which helps retrieve account funds data including available, pending, and reserved amounts.

All Stripe API requests use the following base URL to connect::

https://api.stripe.com

✅ Note: You must register for a developer account at https://stripe.com/ to obtain your API keys and enable access to the endpoints.

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard. Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer ,[object Object]," instead of -u ,[object Object].

Connect the CLI to your Stripe account by logging in to persist your secret key locally. See also Log in to the CLI.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl https://api.stripe.com/v1/charges \
  -u sk_test_51RnldHROvpfI1pPNe8vgG9uHYYkkg80SR0KsVKHLyCqQoQfOXcH8ITSagoVlzFWCySOlUHwAzdVYmjz6aeki0gGt00plSgrjHw:
# The colon prevents curl from asking for a password.

const Stripe = require('stripe');
const stripe = Stripe('sk_test_51RnldHROvpfI1pPNe8vgG9uHYYkkg80SR0KsVKHLyCqQoQfOXcH8ITSagoVlzFWCySOlUHwAzdVYmjz6aeki0gGt00plSgrjHw');

var charge = await stripe.charges.retrieve(
  'ch_3LiiC52eZvKYlo2C1da66ZSQ',
  {
    apiKey: 'sk_test_51RnldHROvpfI1pPNe8vgG9uHYYkkg80SR0KsVKHLyCqQoQfOXcH8ITSagoVlzFWCySOlUHwAzdVYmjz6aeki0gGt00plSgrjHw'
  }
);

Before you can make requests to the Stripe API, you need to generate a secret API key.

1. Go to https://dashboard.stripe.com/login and log in to your developer account.
2. Navigate to Developers → API keys in the left-hand sidebar.
3. Under Standard keys, you will find:
   • Publishable key (used on frontend)
   • Secret key (used on backend or server-side requests)
4. Click Reveal live key token or use the test key to start development.

> 🛡️ Keep your secret key confidential. Do not expose it in frontend code or version control.

When you call the GET /v1/balance endpoint, the Stripe API returns a balance object. This object represents the current balance of your Stripe account, including available funds, pending transactions, and reserved amounts for refunds or disputes.

Use this endpoint to check the available, pending, and reserved balances of your Stripe account.

`GET `{{baseUrl}}/v1/balance

`200` OK

 `GET` https://api.stripe.com/v1/balance 

{
  "object": "balance",
  "available": [
    {
      "amount": 666670,
      "currency": "usd",
      "source_types": {
        "card": 666670
      }
    }
  ],
  "connect_reserved": [
    {
      "amount": 0,
      "currency": "usd"
    }
  ],
  "livemode": false,
  "pending": [
    {
      "amount": 61414,
      "currency": "usd",
      "source_types": {
        "card": 61414
      }
    }
  ]
}

This object is particularly useful when: - You want to display available balance for payouts. - You need to monitor pending amounts before initiating transfers. - You want to check if you have enough funds for refunds or disputes. - You are operating in multi-currency environments (e.g., USD, CAD, EUR) and need a breakdown by currency and source type.

Use this endpoint to check the available, pending, and reserved balances of your Stripe account by passing a parameter named `parameter1=test`.

`400` Bad Request

 `GET` https://api.stripe.com/v1/balance?parameter1=test 

{
  "error": {
    "code": "parameter_unknown",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-unknown",
    "message": "Received unknown parameter: parameter1",
    "param": "parameter1",
    "request_log_url": "https://dashboard.stripe.com/test/logs/req_RJw4l6hmLWtTp7?t=1753226534",
    "type": "invalid_request_error"
  }
}

Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe’s servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

✅ Summary

• Endpoint: /v1/balance [Use this endpoint to check available and pending balances.]
• Method: GET
• Authentication: Bearer token using Stripe Secret Key
• Primary Object: Balance

Author: Snehil Kusum Tiwari