Skip to content
Nappai Documentation

Stripe Balance

Retrieve the current financial status of your Stripe account with the Stripe Balance component. This tool acts as a financial snapshot, helping you understand exactly how much money is immediately usable versus how much is still processing. It provides a clear view of your account’s liquidity, which is essential for managing cash flow and ensuring you have sufficient funds for payouts or marketplace operations.

How it Works

This component connects directly to the Stripe API to fetch real-time balance information. It does not modify your account; it only reads data.

  1. Authentication: The component uses the secure credentials you have previously configured in your Nappai dashboard to verify your identity with Stripe.
  2. Data Retrieval: It queries the Stripe servers to get the current state of your funds.
  3. Categorization: The data is organized into specific categories:
    • Available Funds: Money that is ready to be withdrawn or used.
    • Pending Funds: Money from recent transactions that are being processed but are not yet ready for withdrawal.
    • Connect Reserve: Funds held by Stripe as a security measure for platform transactions (if applicable).

The component processes this information and presents it in a structured format that you can use in subsequent steps of your automation.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type Stripe API and fill in the required fields (specifically your API Key).
  3. In your workflow, select the saved credential in the Credential input field of this node.

Inputs

The Stripe Balance component is designed to be simple and straightforward. It does not require any manual input fields for configuration during workflow execution, other than the connection credentials mentioned above. It automatically retrieves the balance for the entire account associated with the selected API key.

Outputs

The component provides structured data about your Stripe financial status. You can map these outputs to other components to make decisions based on your balance.

Output Data Example (JSON)

json { “available”: { “usd”: 150000, “eur”: 50000 }, “pending”: { “usd”: 25000, “eur”: 10000 }, “connect_reserve”: { “usd”: 0, “eur”: 0 } }

Key Output Fields:

  • available: A dictionary containing the amounts of funds that are immediately accessible. It typically includes currencies like usd (USD) and eur (EUR). Use this to check if you have enough liquidity for immediate payouts or expenses.
  • pending: A dictionary containing funds that have been processed but are not yet ready for withdrawal. This helps you forecast future cash flow.
  • connect_reserve: Indicates any funds held in reserve by Stripe Connect, which is important for marketplace platforms to ensure coverage for potential refunds or chargebacks.

Connectivity

This component is typically used at the beginning of a financial monitoring workflow.

  • Forwarding to: It often connects to Decision or Logic components to trigger actions based on balance thresholds (e.g., “If Available Balance < $100, send alert”).
  • Forwarding to: It can also connect to Reporting components to generate daily or weekly financial summaries.

Usage Example

Scenario: Daily Financial Check

  1. Step 1: Add the Stripe Balance component to your workflow.
  2. Step 2: Select your Stripe API credential.
  3. Step 3: Connect the available output to a Logic component.
  4. Step 4: Configure the logic to check if the USD balance is less than a specific amount (e.g., $500).
  5. Step 5: If the condition is true, trigger an email notification to the finance team.

This setup ensures you are automatically notified if your liquid funds drop below a safe level.

Tips and Best Practices

  • Check Both Available and Pending: While available shows what you can spend now, pending gives you a better idea of your total incoming cash flow. Consider checking both for accurate financial planning.
  • Use for Alerts: This component is ideal for setting up alerts. For example, you can create a workflow that checks your balance every morning and emails you if it is lower than expected.
  • API Key Security: Ensure your Stripe API Key is stored securely in the Credentials section and is not shared in plain text within your workflow diagrams.

Security Considerations

  • Read-Only Operation: This component is “read-only.” It only retrieves data and does not make changes to your Stripe account, reducing the risk of accidental financial errors.
  • Credential Management: Always use restricted API keys if possible. Do not use master secret keys if you only need to read balance information, following the principle of least privilege.