PayPal Balance Widget

See how much money is sitting in every PayPal account you hold, in every currency, right on your Blesta dashboard.

What it does

Checking a PayPal balance today means logging into PayPal separately from Blesta, and doing it again for every account you run. PayPal Balance Widget puts the answer on your Blesta dashboard instead: a widget on both the staff Home dashboard and the Billing dashboard shows the current balance of every PayPal account you configure, in every currency it holds, refreshed automatically in the background. A small trend line next to each figure shows whether it is climbing or draining, and a one-click refresh control is there for whenever you cannot wait for the next scheduled update.

Key features

• Live Balance on Your Dashboard: A widget on both the staff Home and Billing dashboards shows your current PayPal balance the moment you log in, with the time it was last updated shown alongside it.
• Unlimited PayPal Accounts: Add as many PayPal accounts as you use and give each one your own label, so a merchant account, a payouts account, and a test account all report side by side in one place.
• Every Currency You Hold: Each account reports a separate figure for every currency held in it, not just the primary one, so multi-currency balances are never hidden.
• Balance Trend Sparkline: A snapshot is recorded on every refresh and drawn as an inline trend line next to each currency, so you can see at a glance whether a balance is climbing or draining.
• One-Click Manual Refresh: A refresh control on the widget pulls fresh balances on demand and updates in place without reloading the dashboard, for when you cannot wait for the next scheduled run.
• One-Click Connection Test: A Test Connection button on the account form checks your credentials immediately and reports back the resulting balance, without saving half-typed settings or waiting for the next scheduled refresh.
• Encrypted Credential Storage: Your PayPal API username, password, and signature are stored encrypted, never in plain text.
• Per-Staff-Group Visibility: The widget is governed by its own staff permissions, so you decide which staff groups are allowed to see your PayPal balances and which are not.

Installing PayPal Balance Widget

Before you start

• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

plugins/paypal_balance_widget/

For example, on a typical install: /var/www/html/blesta/plugins/paypal_balance_widget/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has the Plugins permission (which includes Install Plugin and Manage Plugin) under Settings in Manage Staff Groups.
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find PayPal Balance Widget in the list and click Install.

3. Configure it

1. From the Installed tab, click Manage next to PayPal Balance Widget. This opens the plugin's PayPal Accounts page.
2. Click the + button to add a PayPal account: give it a Label (any name you'll recognize it by), then either enter its Username, Password, and Signature (the NVP/classic API credentials from your PayPal Business account's API access settings), or tick Mock API to try the widget with sample data before connecting a real account. Tick Sandbox if this account should point at PayPal's sandbox environment instead of live PayPal. Use Test Connection to check the credentials immediately without saving. Add one account per PayPal account you want to track.
3. The plugin registers a Refresh PayPal Balances cron task that runs automatically every 15 minutes once installed - no manual step is needed for it to start working.
4. Go to Settings > System > Staff > Staff Groups and edit each staff group that should see the widget. Under the PayPal Balance Widget permission group, tick View PayPal Balance (to see the widget at all) and Refresh PayPal Balance (to use its manual refresh control). Like every Blesta permission, these are registered but granted to nobody automatically, so the widget stays hidden from a staff group until you tick them.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating PayPal Balance Widget

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Plugins.
4. Find PayPal Balance Widget and click Update to run the upgrade.

Version-specific notes

• v2.0.0: The Manage page now lists multiple PayPal accounts per company - add, edit, or remove each as its own labeled account. Any single account you had configured before this update is carried forward automatically. Balances are now refreshed in the background by a new "Refresh PayPal Balances" cron task (every 15 minutes) instead of contacting PayPal on every dashboard load; this is enabled automatically, no manual step required. The dashboard widget reads the last cached figure, shows how long ago it was fetched, draws a small trend line, and has a manual refresh control. A Test Connection button on the account form lets you verify credentials without saving. This version also adds a new staff permission, Refresh PayPal Balance, controlling the widget's manual refresh control. Like every Blesta permission it is registered unchecked and granted to no one, so grant it (alongside the existing View PayPal Balance permission) under Settings > System > Staff > Staff Groups for any staff group that should use it.
• v1.1.0: Added a Mock API option on each account, so you (or your staff) can try the widget and its Test Connection with sample data before connecting real PayPal credentials. Added the View PayPal Balance staff permission that gates the widget; if the widget disappears after updating from v1.0.0, grant it under Settings > System > Staff > Staff Groups. Also fixed your API signature always showing as blank on the settings page and being erased the moment you saved (which had silently stopped the widget from reporting a balance), and fixed your API password and signature being sent to PayPal in the web address rather than the request body (which had written both of them in plain text into your server's error log whenever a request failed).

Using PayPal Balance Widget

For your staff

Enabling the widget on your dashboard

Blesta dashboard widgets are opt-in per staff member. If you don't see "PayPal Balance Widget" on your Home or Billing dashboard after installing, click Manage Widgets in the dashboard sidebar and drag it into your enabled widgets, the same way you would enable any other dashboard widget.

Managing PayPal accounts

Go to Settings > Company > Plugins, find PayPal Balance Widget in the Installed tab, and click Manage. This opens the PayPal Accounts page: a table listing every account you've added, with its Label, its Environment (Live, Sandbox, or Mock), and Edit / Delete links. Click the + button in the top right to add a new account. Deleting an account asks you to confirm first.

Adding or editing an account

The account form has these fields:

• Label - a name for this account, shown as the heading above its balances in the widget (for example "Merchant Account" or "EU Payouts").
• Sandbox - tick this to point the account at PayPal's sandbox environment instead of live PayPal.
• Mock API - tick this to serve a fixed sample balance instead of contacting PayPal at all, useful for trying out the widget before you have real API credentials.
• Username, Password, Signature - your PayPal NVP/classic API credentials. Password and Signature are never shown again once saved; leaving either blank when editing keeps the value already stored.
• Test Connection - checks the credentials right away and shows the resulting balance inline, without saving the form.
• Save - adds the account or saves your changes.

The dashboard widget

Once an account is added and its balance has been fetched, the PayPal Balance Widget box on your Home and Billing dashboards shows each account as its own heading, followed by a table with one row per currency it holds: the Currency and amount, a small Trend line showing recent movement, and when it was last Updated. An account that hasn't been fetched yet shows a placeholder message instead of a table.

A Refresh balances button in the top right of the widget fetches fresh balances for every account on demand and updates the widget in place, without reloading the page. It's limited to once a minute per company, since each refresh makes a live PayPal request for every configured account.

Good to know

• Balances refresh automatically in the background every 15 minutes; the widget itself only ever reads the last cached figure, so loading your dashboard never waits on a PayPal request.
• The trend line is drawn from the last 30 balance snapshots, and snapshots older than 90 days are cleared out automatically.
• The widget renders in two places - the staff Home dashboard and the Billing dashboard - reading the same cached data, so refreshing from one updates what the other shows next time you load it.
• The View PayPal Balance and Refresh PayPal Balance permissions (under the PayPal Balance Widget group in Manage Staff Groups) control who can see the widget and who can use its refresh control.