Dual PayPal Payment Buttons

Add PayPal payment buttons to allow fast and easy payments without requiring the client to have a PayPal account - and split those payments across two PayPal accounts, chosen automatically by the amount being paid.

Payments greater than the Amount Limit you set are taken with your second PayPal account; everything at or below it uses the first. Leave the limit blank and every payment uses the first account, so you can run single-account until you are ready to add the second.

Install the Gateway

1. Upload the source code to a /components/gateways/nonmerchant/dual_paypal_payment_buttons/ directory within your Blesta installation path.

   For example:

   /var/www/html/blesta/components/gateways/nonmerchant/dual_paypal_payment_buttons/

2. Log in to your Blesta admin area and navigate to: /admin/settings/company/gateways/available/

3. Find the Dual PayPal Payment Buttons gateway and click the "Install" button to install it

4. Register the webhook shown on the gateway's Manage screen in both PayPal accounts - payments are not recorded without it. See the usage guide.

5. You're done!

Setting up

Quick Support

Where can I find my Client ID and Secret?

• Go to this link: https://developer.paypal.com/, and login using the "Log in to Dashboard" button in the top right
• Once you're logged in, go to https://developer.paypal.com/developer/applications
• Under "My apps & credentials" press "Live"
• Click on "Create App" or on your app if it already exists
• Copy over your Client ID and press on "Show" under Secret to reveal your Client Secret
• Repeat while logged in to your second PayPal account to get that account's Client ID and Client Secret

Can I try it without a PayPal account?

Yes. Tick Demo Mode on the gateway's Manage screen and enter any placeholder credentials. The gateway then serves canned PayPal responses, so you can walk the whole payment flow end to end without contacting PayPal or taking a real payment. Turn it off before going live.

Dual PayPal Payment Buttons Gateway by Blesta.Club - Installation Guide

Welcome, and thank you for purchasing the Dual PayPal Payment Buttons Gateway! We're excited to have you as a customer and are committed to ensuring you have a seamless experience. This README will guide you through the installation of your new gateway. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Installation Guide

To install the Dual PayPal Payment Buttons Gateway, please follow these steps:

1. Obtain the Gateway:

   • Download the Dual PayPal Payment Buttons Gateway from the download section of the client area.

2. Upload to Blesta:

   • Upload the Dual PayPal Payment Buttons Gateway to your Blesta gateways directory:

     /var/www/html/blesta/components/gateways/nonmerchant/dual_paypal_payment_buttons/

3. Install the Gateway:

   • Log in to your Blesta admin account.
   • Navigate to Settings > Payment Gateways.
   • Find the Dual PayPal Payment Buttons Gateway under the "Available" tab and click the "Install" button.

Setting Up the Gateway

1. Configure the Gateway:

   • Navigate to Settings > Payment Gateways (/admin/settings/company/gateways/installed/).
   • Find the "Dual PayPal Payment Buttons" Gateway and click on "Manage".
   • Enter the Client ID and Client Secret of your first PayPal account.
   • Optionally enter an Amount Limit plus the second account's Client ID and Client Secret. Payments greater than the limit are taken with the second account; everything else uses the first. Leave all three blank to use the first account for every payment.

2. Register the PayPal Webhook (required):

   • Still on the Manage screen, copy the URL shown under the PayPal Webhook heading.
   • In the PayPal developer dashboard, open the REST app whose credentials you entered and add a webhook pointing at that URL.
   • Subscribe it to Checkout order approved (CHECKOUT.ORDER.APPROVED) and Payment capture completed (PAYMENT.CAPTURE.COMPLETED).
   • Repeat this for the second PayPal account. Both accounts must send the webhook, or payments routed to the account you skipped are never recorded.

3. Enable Payment Processing:

   • After configuring, ensure the gateway is enabled for use in your Blesta system order forms.

Trying it out first? Tick Demo Mode, enter any placeholder credentials, and the gateway serves canned PayPal responses so you can walk the full payment flow without a PayPal account. No webhook is needed in demo mode. Turn it off before taking real payments.

You're now done with the installation! Proceed to configure the gateway as needed by following the usage guide.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please get in touch with us. We are committed to providing robust updates and welcome customer feedback.

Dual PayPal Payment Buttons Gateway by Blesta.Club - Update Guide

To ensure you're always using the latest version of the Dual PayPal Payment Buttons Gateway, follow these steps to update the gateway within your Blesta installation.

Steps for Updating the Gateway

1. Download the Latest Version

• Visit the download section to obtain the latest version of the Dual PayPal Payment Buttons Gateway.

2. Upload the Updated Gateway

• Upload the updated files to your Blesta installation directory, replacing the existing files.
• The directory path is:

   /var/www/html/blesta/components/gateways/nonmerchant/dual_paypal_payment_buttons/

3. Update the Gateway in Blesta

• Log in to your Blesta admin account.
• Navigate to Settings > Payment Gateways.
• Locate the Dual PayPal Payment Buttons Gateway in the list and click the "Upgrade" button, if available.

4. Check Configuration

• After the update, review your credentials and payment settings to ensure they are correctly configured. Navigate to Settings > Payment Gateways and manage the Dual PayPal Payment Buttons Gateway to verify the settings.

Upgrading to v2.0.0

No action is required. v2.0.0 changes no settings and no stored data, so your existing credentials, Amount Limit and webhook registrations keep working exactly as before. The new features - staff-side refunds, optional webhook signature verification, credential checking on save, and the button appearance and funding settings - are all optional additions you can start using whenever you like.

Two things worth knowing:

• Refunding payments taken before v1.1.0. Those older payments were recorded with the payer's email address where the PayPal refund reference is now kept. v2.0.0 recognizes that and refunds them using the payment's own transaction id instead, so they are refundable from Blesta like any other payment. Payments taken with v1.1.0 or later are unaffected.
• Webhook signature verification is opt-in. Leave the Webhook ID fields blank and the gateway keeps verifying every payment by re-fetching the order from PayPal, exactly as v1.1.0 did. If you fill one in, copy it from that PayPal app's webhook - a Webhook ID from the wrong app never verifies. Filling in only one of the two accounts is supported and never blocks payments taken with the other.

⚠ Upgrading to v1.1.0 - action required

v1.1.0 changes how payments are recorded. You must register a PayPal webhook on BOTH PayPal accounts, or the gateway will stop recording payments after the upgrade.

Before v1.1.0 the gateway recorded the payment itself when the client's browser returned from PayPal. It now records from PayPal's own webhook instead, which means a payment is no longer lost when a client closes the tab before being redirected back.

To finish the upgrade:

1. Go to Settings > Payment Gateways and click Manage on Dual PayPal Payment Buttons.
2. Copy the URL shown under the PayPal Webhook heading.
3. In the PayPal developer dashboard, open the REST app whose credentials you use for the first account, and add a webhook pointing at that URL.
4. Subscribe it to Checkout order approved (CHECKOUT.ORDER.APPROVED) and Payment capture completed (PAYMENT.CAPTURE.COMPLETED).
5. Repeat steps 3-4 for the second PayPal account. The same URL is used for both. Payments routed to an account without the webhook are never recorded.
6. Repeat for your sandbox apps if you also test in sandbox.

Also note in v1.1.0:

• The unused PayPal Account and Second PayPal Account settings have been removed. Only the Client IDs and Client Secrets are needed. You do not need to do anything - any previously saved value is simply ignored.
• A blank Amount Limit now keeps every payment on the first account. Previously a blank limit routed every payment to the second account, which could send payments to unconfigured credentials. If you relied on that by accident, set the limit explicitly.
• CNY and RUB have been removed from the currency list (PayPal does not settle them) and TRY has been added. If you had selected CNY or RUB, pick a different currency for the affected order forms.
• Orders already in flight when you upgrade are still recorded correctly; no payment in progress is lost by upgrading.

Testing the Update

1. Test Mode:

   • Before switching back to live transactions, you may want to test the gateway in PayPal’s sandbox mode to ensure everything works as expected.

2. Transaction Testing:

   • Perform a test transaction using the updated gateway to ensure that payments are processed successfully.

Troubleshooting Update Issues

1. Missing or Incorrect Files:

   • If you experience issues after updating, ensure all files have been uploaded correctly to the appropriate directory.
   • Check file permissions to ensure the web server can access the updated files.

2. Payments stopped being recorded after updating:

   • This is the v1.1.0 webhook change above. Register the callback URL on both PayPal REST apps with both required events. Tools > Logs > Gateway shows whether the webhook is reaching Blesta.

3. Credential Issues:

   • If transactions are failing after the update, verify the Client IDs and Client Secrets in the gateway settings. Ensure that you're using live credentials for real transactions and sandbox credentials for testing purposes.

4. Version Compatibility:

   • Make sure the updated version of the gateway is compatible with your current version of Blesta. Refer to the changelog or update notes for any breaking changes or version requirements.

Contact Us

If you encounter any issues during the update process or have suggestions for improving the gateway, please reach out to us. We are dedicated to providing consistent updates and value your feedback.

Dual PayPal Payment Buttons Gateway by Blesta.Club - Usage Guide

Welcome, and thank you for purchasing the Dual PayPal Payment Buttons Gateway! We're excited to help you get the most out of your new gateway. This guide will walk you through how to use the gateway effectively. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Gateway Capabilities

The Dual PayPal Payment Buttons Gateway lets clients pay directly from the Blesta pay page using PayPal Smart Buttons, and spreads those payments across two PayPal accounts:

• On-page PayPal buttons. The buttons render on your own pay page, rather than sending the client off to a PayPal-hosted checkout page first.
• No PayPal account required from your clients. Card payments go through the same buttons.
• Automatic dual-account routing. Payments greater than the Amount Limit are taken with the second PayPal account; everything at or below it uses the first.
• Itemized invoices. Each invoice being paid appears as its own line in the PayPal order, with any overpayment shown as "Client Credits".
• Demo Mode for evaluating the gateway with no PayPal account at all.

Dual-account routing

Routing is decided per payment, on the rounded total the client is about to pay:

Leaving the Amount Limit blank - or leaving the second account's credentials blank - keeps every payment on the first account. The gateway will not route to a second account it has no credentials for.

Registering the PayPal Webhook (required)

Payments are recorded from PayPal's webhook, not from the client's browser. This is what stops a payment being lost when a client closes the tab before returning to your site.

The gateway registers this webhook with PayPal for you automatically, per account, the first time you save that account's settings with its Webhook ID field left blank. In most cases there is nothing further to do for either account. If automatic registration fails for an account (for example, that PayPal REST app has the Webhooks feature turned off), settings will not save and that account's Webhook ID field will show an error - register it manually:

1. Go to Settings > Payment Gateways and click Manage on Dual PayPal Payment Buttons.
2. Copy the URL shown under the PayPal Webhook heading.
3. In the PayPal developer dashboard, open the REST app whose credentials you use and add a webhook pointing at that URL.
4. Subscribe it to Checkout order approved (CHECKOUT.ORDER.APPROVED) and Payment capture completed (PAYMENT.CAPTURE.COMPLETED).
5. Save, then paste the webhook ID PayPal shows you into that account's Webhook ID field on the Manage screen and save again.
6. Repeat for the second PayPal account if it also failed to auto-register. Both accounts need the webhook; payments routed to an account without it are never recorded.

You do not need to tell the gateway which account a payment came from - it identifies the owning account by looking the order up against each of them.

Using the Gateway

Once installed and configured, the gateway is available to clients paying for their services.

Client View

• When clients pay an invoice, the PayPal buttons render directly on the payment page.
• The client approves the payment in PayPal's popup and is returned to your site.
• The payment appears in Blesta as pending and flips to approved as soon as PayPal's capture webhook arrives, usually within seconds.

Testing the Gateway

1. Demo Mode:
   • Tick Demo Mode with any placeholder credentials to walk the full flow against canned PayPal responses. No PayPal account, and no webhook, is required. Nothing is charged.
2. Sandbox:
   • Tick Sandbox and enter PayPal sandbox app credentials to test against PayPal itself. Register the webhook on your sandbox apps too.
3. Go live:
   • Untick both, and enter live credentials for both accounts.

Troubleshooting Common Issues

1. Payments are not being recorded:
   • The webhook is almost always the cause. The gateway registers one automatically per account on save, but an install upgraded from an older version, or an account where automatic registration failed silently in the past, may not have one. Confirm it is registered on both PayPal accounts with both required events. Tools > Logs > Gateway shows whether the webhook is reaching Blesta, alongside every order the gateway creates. A webhook that arrives but names an order neither account recognizes is written there as a failed entry, which is what a webhook registered on only one of the two accounts looks like.
2. Payments always use the first account:
   • Check that the Amount Limit is set and that the second account's Client ID and Client Secret are both filled in. A blank limit, or missing second credentials, keeps everything on the first account by design.
3. The buttons do not appear on the pay page:
   • The page shows a short error message when the buttons fail to start. It is deliberately generic, because your clients see it; the full reason PayPal gave is in Tools > Logs > Gateway. The usual causes are a mistyped Client ID or Client Secret, or an invoice in a currency the gateway is not enabled for.
4. Currency Mismatch:
   • Ensure that the currency settings in Blesta match the currencies accepted by your PayPal accounts to avoid processing errors.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please get in touch with us. We are committed to providing robust updates and welcome customer feedback.