PayPal Billing Agreements Gateway

Let a client approve a PayPal billing agreement once, then charge their invoices to it on demand, with the PayPal Billing Agreements Manager plugin doing the work behind it.

What it does

Asking a client to log in to PayPal and approve every single invoice gets old fast, and it is a dead end for recurring billing. This gateway gives a client a Pay button that charges a PayPal billing agreement they approved once, and a Setup button when they have not connected one yet, so nobody hits a wall on the payment page. It installs alongside the PayPal Billing Agreements Manager plugin, which holds your PayPal API credentials and does the actual charging, storage and recurring billing - this gateway itself has nothing to configure beyond which currencies you accept.

Key features

• Approve Once, Charge On Demand: A client connects their PayPal account a single time, and from then on their invoices can be settled against it without logging in to PayPal and approving a payment all over again.
• A Pay or Setup Button on Every Invoice: A client who already has an agreement sees a Pay button that charges it immediately; a client who does not is offered a Setup button that walks them through connecting one.
• Half of a Ready-Made Pair: Installs alongside the PayPal Billing Agreements Manager plugin, which stores each client's payment details, holds your PayPal credentials and does the charging, so the two together give you on-demand and recurring billing with nothing to build yourself.
• Nothing Extra to Configure: The gateway has no settings of its own to fill in. Enable it, tick the currencies you want to accept, and it uses the PayPal API credentials already entered on the companion plugin.
• Automatic Recurring Charges: With the companion plugin in place, invoices set to auto-debit are charged against each client's stored agreement on a daily schedule.
• Refunds From Inside Blesta: Issue a full or partial refund straight from the transaction in your admin area and it is sent to PayPal for you, with no need to open the PayPal dashboard.
• 24 Supported Currencies: Bill and take payment in any of 24 PayPal currencies, including USD, EUR, GBP, AUD, CAD, JPY, CNY and SGD.
• Fully Translatable: Every client-facing label ships in an editable language file, ready to translate or reword to match your brand.

Installing PayPal Billing Agreements Gateway

Before you start

• Install and configure the PayPal Billing Agreements Manager plugin first. This gateway refuses to install, upgrade or process a refund until a matching version of the manager plugin is already installed, since the manager is where your PayPal credentials and all of the actual billing logic live.
• 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:

components/gateways/nonmerchant/paypal_billing_agreements_gateway/

For example, on a typical install: /var/www/html/blesta/components/gateways/nonmerchant/paypal_billing_agreements_gateway/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has access to Settings > Company > Payment Gateways.
2. Go to Settings > Company > Payment Gateways and click the Available tab.
3. Find PayPal Billing Agreements in the list and click Install.

3. Configure it

This gateway has no credential fields of its own - everything PayPal-related is entered on the companion plugin.

1. Click Manage next to PayPal Billing Agreements on the Payment Gateways page. The page only explains that credentials live on the manager plugin; tick the currencies you want to accept and save.
2. Enter your PayPal API Username, Password and Signature on the PayPal Billing Agreements Manager plugin's Manage page (Settings > Company > Plugins > Installed > PayPal Billing Agreements Manager > Manage) if you have not already done so during that plugin's own install.

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

Updating PayPal Billing Agreements Gateway

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.

Update both halves together, manager plugin first. This gateway and the PayPal Billing Agreements Manager plugin are released in lockstep, and running mismatched versions is not supported. As of v2.0.0 the gateway refuses to install, upgrade or process a refund while the manager plugin is on an older version, so upload and upgrade the manager plugin before the gateway.

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 > Payment Gateways.
4. Find PayPal Billing Agreements and click Upgrade to run the update.

Version-specific notes

• v2.0.0: Requires PayPal Billing Agreements Manager v2.0.0 or later - update the manager plugin first. The Pay button now submits as a form instead of a link, so a payment can no longer be triggered by visiting a page or refreshing the browser, and the amount, currency and invoices are sealed by the gateway so an edited payment form is rejected instead of charging a different amount. No settings change on your part is needed.
• v1.1.0: Added refund support. No configuration change is needed.

Using PayPal Billing Agreements Gateway

For your staff

Payment Gateways

Under Settings > Company > Payment Gateways, PayPal Billing Agreements appears in your Installed list once enabled. Its Manage page has no credential fields - it only tells you that credentials belong on the companion plugin - and a set of currency checkboxes. Tick every currency you want clients to be able to pay in; a client only sees this gateway as an option for invoices in a currency you have ticked here.

Refunding a payment

Open the transaction under Billing > Transactions, choose to issue a refund, and enter the amount. The refund is sent to PayPal immediately and logged under Tools > Logs > Gateway alongside PayPal's response, so a failed refund can be traced.

For your clients

Paying an invoice for the first time

When a client opens an unpaid invoice and goes to make a payment, PayPal Billing Agreements appears as one of the options under Other Payment Options. Choosing it and continuing shows a Setup Billing Agreements button, since no agreement is connected yet. Clicking it sends the client to PayPal to log in and approve the agreement; PayPal then returns them to Blesta with the connection confirmed.

Paying with a connected agreement

Once an agreement is connected, choosing PayPal Billing Agreements on an invoice shows a Pay With Billing Agreements button instead. Clicking it charges the invoice to the stored agreement immediately - no trip to PayPal - and the client lands on a confirmation page showing the amount, currency and invoices paid.

Good to know

• The gateway itself never talks to PayPal - connecting, storing and charging the agreement is handled by the PayPal Billing Agreements Manager plugin, whose own usage guide covers the client's connect/cancel screen and the staff billing agreements list in more detail.
• A client with an existing PayPal billing agreement is charged automatically on your invoices' due dates through the companion plugin's nightly billing task, so most clients never need to return to the Setup step after the first time.

PayPal Billing Agreements Manager

Let clients connect their PayPal account once, then bill their invoices automatically every night without asking them to log in again.

What it does

Chasing PayPal payments by hand, or asking a client to approve every single invoice at PayPal, does not scale. This plugin is the working half of the PayPal Billing Agreements pair: it stores each client's connected PayPal billing agreement, holds your PayPal API credentials, charges agreements on demand or automatically overnight, and records every payment, refund and reversal back into Blesta. Install it alongside the PayPal Billing Agreements Gateway, which gives clients the Pay/Setup button on their invoices and lists the currencies you accept - this plugin does everything behind that button.

Key features

• Clients Connect PayPal Once: From their own area of your client portal a client clicks Connect PayPal Account, approves the agreement at PayPal, and comes straight back. The page then shows the agreement with their PayPal name and email, and a button to cancel it whenever they want.
• Nightly Automatic Billing: A scheduled task collects every invoice due for auto-debit, groups them by client and currency, charges the stored agreement and applies the payment to those invoices the same night.
• Charge a Client on Demand: A billing action on the client profile walks your staff through choosing a currency, ticking open invoices or entering another amount, reviewing the total, and taking the payment there and then.
• Five Editable Client Emails: Ready-made templates warn the client about an upcoming charge, confirm a successful one, report a failed attempt, tell them billing has been paused, and ask them to reconnect PayPal - all editable in Blesta's own email template editor.
• Retry Cap With Automatic Pause: Once a client's own auto-debit attempt limit is used up, automatic billing pauses and a single action-required email is sent instead of another failure notice every night. Any successful payment clears the pause automatically.
• Cancelled Agreements Detected Automatically: If a client revokes the agreement from inside PayPal, the next charge attempt recognises it, clears the dead agreement out of Blesta and emails the client a reconnect invitation.
• Refunds and Chargebacks Reflected Back: Refunds you issue and reversals raised against a payment are received from PayPal and recorded against the original transaction, so what Blesta shows matches your PayPal balance without anyone reconciling by hand.
• Searchable Agreement List for Staff: A staff page lists every connected agreement with the client, agreement ID, payer name, email, status and country, filterable on each field, flagging any agreement whose automatic billing is paused.
• Credentials Verified When You Save Them: Your PayPal API username, password and signature are checked against PayPal the moment you save them, and PayPal's own message is shown if they are wrong.
• Granular Staff Permissions: Viewing agreements, cancelling them and charging a client are separate permissions, so you can let support staff look without letting them take money.
• Built-In Demo Mode: A Mock API mode runs the whole plugin from bundled sample data, so you can trial every screen and action before you have a PayPal account or API credentials.

Installing PayPal Billing Agreements Manager

Before you start

• Install this plugin before the PayPal Billing Agreements Gateway. The gateway depends on it and refuses to install until a matching version of this plugin is already present.
• 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_billing_agreements_manager/

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

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has access to Settings > Company > Plugins.
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find PayPal Billing Agreements Manager in the list and click Install.

3. Configure it

1. Click Manage next to PayPal Billing Agreements Manager on the Installed Plugins page.
2. Enter your API Username, API Password and API Signature. These are classic NVP/SOAP credentials, not a REST Client ID and Secret Key - get them from Account Settings > Account access > API access > NVP/SOAP API integration (Classic) in your PayPal account, or from a sandbox business account in the PayPal Developer Dashboard.
3. Tick Sandbox while testing against PayPal's sandbox, and leave it unticked to go live. Your credentials are verified against PayPal the moment you save.
4. Optionally tick Mock API to run the plugin entirely from bundled sample data with no PayPal contact and no credentials required - useful for a first look before you have an account. Leave it unticked in production.
5. Install the PayPal Billing Agreements Gateway (Settings > Company > Payment Gateways), enable it and tick the currencies you want to accept. This plugin reads its supported currencies from the gateway, so billing does nothing until that is done.
6. Grant staff permissions: go to System > Staff > Groups, edit each staff group that should have access, and tick the permissions you want under PayPal Billing Agreements (View Billing Agreements, Cancel Billing Agreements, Bill With Billing Agreements). Blesta does not grant new permissions automatically, so until this is done staff will see "You are not authorized to access that resource" when opening the plugin's admin page.

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

Updating PayPal Billing Agreements Manager

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.

Update both halves together, update this plugin first. This plugin and the PayPal Billing Agreements Gateway are released in lockstep, and running mismatched versions is not supported.

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 Billing Agreements Manager and click Upgrade to run the update, then upgrade the PayPal Billing Agreements Gateway the same way.

Version-specific notes

• v2.0.0: The stored PayPal password and signature are no longer shown on the Manage page - both fields are now blank by default, and leaving them blank when you save keeps the credentials you already have. Automatic billing now pauses after too many consecutive failed charges instead of retrying forever; nothing to configure, it uses your existing Auto Debit Attempts setting. Also adds an optional Setup Currency override on the Manage page (defaults to Company Default, no action needed) and requires PayPal Billing Agreements Gateway v2.0.0 or later - update the gateway at the same time.
• v1.2.0: Introduces staff permissions for this plugin's admin pages, and Blesta does not grant them automatically. After updating, go to System > Staff > Groups and tick the permissions you want under PayPal Billing Agreements (View Billing Agreements, Cancel Billing Agreements, Bill With Billing Agreements) for each staff group, or staff - including administrators - will see "You are not authorized to access that resource". Also requires PayPal Billing Agreements Gateway v1.2.0 or later.
• Contact access (introduced alongside v2.0.0): A client contact with their own login now additionally needs the Payment Accounts permission, alongside this plugin's own permission, to view, connect or cancel the account's stored PayPal agreement from their client-area login. Grant both under My Information > Contacts > edit > Authentication for any contact who should have access; granting only one of the two is refused the same way as granting neither. Paying an invoice is unaffected. Primary account holders are not affected.

Using PayPal Billing Agreements Manager

For your staff

Manage page

Settings > Company > Plugins > Installed > PayPal Billing Agreements Manager > Manage is where your PayPal credentials live: API Username, Password and Signature, the Sandbox toggle, the optional Mock API demo mode, and an optional Setup Currency override for the zero-amount authorization PayPal receives when a client connects an agreement (leave it on Company Default unless your PayPal account rejects that currency). Password and Signature are never shown back to you once saved - leave them blank to keep what is already stored, and only fill them in when you are changing them. Saving makes a real check against PayPal and shows PayPal's own error if something is wrong.

PayPal Billing Agreements list

Under Billing > PayPal Billing Agreements in the admin menu, every connected agreement is listed one row per client, showing the client, agreement ID, payer name, payer email, payer status and payer country. Any agreement with automatic billing paused is flagged in the list. Use the filters above the list to search by client, agreement ID, payer, payer email, payer status or payer country, and click Cancel on a row to cancel that client's agreement at PayPal and remove it from Blesta - you're asked to confirm first.

Billing a client on demand

Open a client's profile and choose Bill With Billing Agreements among the account actions. The wizard walks through three steps: pick the currency to bill in, then tick the open invoices to pay and/or enter another amount, then review the client and payment details before confirming. Confirming charges the client's stored agreement immediately and applies the payment to the invoices you selected.

For your clients

Connecting a PayPal account

Clients reach their own PayPal Billing Agreements page from the client area menu. Before connecting, it explains that no billing agreement is set up yet and offers a Connect PayPal Account button; clicking it sends the client to PayPal to log in and approve the agreement, then brings them back to Blesta.

Viewing and cancelling the connected agreement

Once connected, the same page shows the Billing Agreement Details: the agreement ID, the PayPal name and email on file, and a Cancel Billing Agreement button. Cancelling asks for confirmation, then removes the agreement at PayPal and from Blesta - the client would need to connect again before their invoices could be charged automatically or with the Pay button on an invoice.

Paying an invoice

Once an agreement is connected, PayPal Billing Agreements appears as a payment option on the client's invoices, letting them pay with one click instead of returning to PayPal. See the companion gateway's usage guide for that screen.

Good to know

• Automatic billing runs once a night against every invoice flagged for auto-debit, in the client's own currency, provided that currency is enabled on the companion gateway.
• If too many consecutive automatic charges fail for a client, billing pauses for that agreement and the client is emailed once rather than nightly; a successful payment (automatic, client-initiated or staff-initiated) clears the pause.
• If a client revokes the agreement from inside PayPal itself, the next charge attempt detects this, removes the stale agreement from Blesta and emails the client asking them to reconnect.
• A contact with their own client-area login needs both the PayPal Billing Agreements and Payment Accounts permissions (under My Information > Contacts > edit > Authentication) to view, connect or cancel the account's agreement - granting only one of the two is refused with the same message as granting neither.