PayPal Payment Buttons

Add PayPal payment buttons to allow fast and easy payments to your PayPal account without requiring the client to have a PayPal Account

Install the Gateway

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

   For example:

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

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

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

4. 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

Do I need to configure anything else?

Yes. Payments are recorded by a PayPal webhook, so you must register the gateway's callback URL against your REST app before taking payments. The URL is shown on the gateway's Manage screen under "PayPal Webhook", and it needs the Checkout order approved and Payment capture completed events subscribed. The usage guide walks through it.

PayPal Payment Buttons Gateway by Blesta.Club - Installation Guide

Welcome, and thank you for purchasing the 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 PayPal Payment Buttons Gateway, please follow these steps:

1. Obtain the Gateway:

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

2. Upload to Blesta:

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

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

3. Install the Gateway:

   • Log in to your Blesta admin account.
   • Navigate to Settings > Payment Gateways.
   • Find the 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 "PayPal Payment Buttons" Gateway and click on "Manage".
   • Input the Client ID and Client Secret of your PayPal REST app, and tick Sandbox if you are configuring sandbox credentials.

2. Register the PayPal Webhook (required):

   • The same Manage screen shows a callback URL under the "PayPal Webhook" heading. Copy it.
   • In the PayPal developer dashboard (https://developer.paypal.com/developer/applications), open your REST app and add a webhook pointing at that URL, subscribed to the Checkout order approved and Payment capture completed events.
   • Payments are recorded from this webhook. Without it, clients can pay but nothing is recorded in Blesta.

3. Enable Payment Processing:

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

Want to try the gateway before setting up a PayPal app? Tick Demo Mode on the Manage screen. The gateway then serves canned PayPal responses, takes no real payments, and needs no webhook. Turn it off before going live.

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.

PayPal Payment Buttons Gateway by Blesta.Club - Update Guide

To ensure you're always using the latest version of the 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 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/paypal_payment_buttons/

3. Update the Gateway in Blesta

• Log in to your Blesta admin account.
• Navigate to Settings > Payment Gateways.
• Locate the 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 PayPal Payment Buttons Gateway to verify the settings.

⚠ Upgrading to v1.1.0 - action required

v1.1.0 changes how payments are recorded. You must register a PayPal webhook, 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 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. Repeat for your sandbox app if you also test in sandbox.

Also note in v1.1.0:

• The unused PayPal Account setting has been removed. Only the Client ID and Client Secret are needed. You do not need to do anything - any previously saved value is simply ignored.
• 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.

Upgrading to v2.0.0 - optional webhook events

v2.0.0 adds refunds from Blesta, refund and dispute syncing, credential checking on save, button appearance settings, and optional webhook signature verification. Existing installs keep working with no changes, but two optional steps unlock the new syncing:

• To have PayPal refunds and disputes reflected in Blesta automatically, open your webhook in the PayPal developer dashboard and subscribe it to two more events: Payment capture refunded (PAYMENT.CAPTURE.REFUNDED) and A dispute is created (CUSTOMER.DISPUTE.CREATED). A refund issued from the PayPal dashboard then marks the Blesta transaction refunded, and a new dispute marks it returned. Refunds issued from Blesta's own Refund button need no extra setup.
• For cryptographic webhook verification (optional), copy your webhook's ID from the PayPal dashboard into the new Webhook ID setting. When set, every incoming webhook is verified against PayPal before it is recorded. Left blank, the gateway continues to verify each payment by re-fetching it from PayPal.

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 your PayPal REST app 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 ID and Client Secret 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.

PayPal Payment Buttons Gateway by Blesta.Club - Usage Guide

Welcome, and thank you for purchasing the 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 PayPal Payment Buttons Gateway allows clients to pay for services directly through PayPal using PayPal's Smart Payment Buttons. Below are the key features of the gateway:

• PayPal Smart Buttons rendered on your own pay page. Clients complete the payment in a PayPal popup without leaving your site, and do not need a PayPal account to pay by card.
• Itemized checkout. Each invoice being paid appears as its own line ("Invoice #123") inside the PayPal checkout, so the client can see what they are paying for. Any amount paid above the invoice total is added as a "Client Credits" line.
• Webhook-driven recording, registered automatically. Payments are recorded from PayPal's own webhook rather than from the client's browser, so a closed tab or a lost connection on the way back from PayPal no longer loses the payment. The webhook itself is registered with PayPal automatically the first time you save your settings.
• Live and Sandbox environments, switched with a single checkbox.
• Demo Mode for evaluating the gateway end to end without PayPal credentials.
• Refunds from Blesta. The staff Refund button on a transaction issues a full or partial refund straight through PayPal.
• Refund and dispute syncing. A refund issued from the PayPal dashboard marks the Blesta transaction refunded, and a new dispute marks it returned (requires the two optional webhook events below).
• Credential checking on save. The Client ID and Client Secret are verified against PayPal when you save the settings, so a typo is caught immediately rather than at the first client payment.
• Button appearance settings. Choose the button's color, shape, label and layout, and which funding options (Venmo, Pay Later, Debit or Credit Card) are offered.
• Optional webhook signature verification. Set a Webhook ID to have every incoming webhook cryptographically verified against PayPal.
• Gateway logging. Order creation, incoming webhooks, captures and refunds are all recorded under Tools > Logs > Gateway.

Setting Up the Webhook (required)

Payments are recorded by a PayPal webhook, not by the client's browser returning to your site. If no webhook exists, clients can pay but nothing is recorded in Blesta.

As of this version, the gateway registers this webhook with PayPal for you automatically the first time you save your settings with a blank Webhook ID field, subscribed to all four event types below. In most cases there is nothing further to do - just enter your Client ID and Client Secret and save.

If automatic registration fails (for example, your PayPal REST app has the Webhooks feature turned off, or your credentials do not have permission to manage webhooks), settings will not save and the Webhook ID field will show an error. In that case, register the webhook manually:

1. Navigate to Settings > Payment Gateways (/admin/settings/company/gateways/installed/), find "PayPal Payment Buttons" and click Manage.
2. Copy the URL shown under the PayPal Webhook heading.
3. Go to https://developer.paypal.com/developer/applications and open the REST app whose credentials you configured.
4. Under Webhooks, add a webhook pointing at that URL.
5. Subscribe it to at least these two event types:
   • Checkout order approved (CHECKOUT.ORDER.APPROVED)
   • Payment capture completed (PAYMENT.CAPTURE.COMPLETED)
6. Save, then paste the webhook ID PayPal shows you into the Webhook ID field on the gateway's Manage screen and save again.

The first event captures the payment and records it as Pending; the second flips the same transaction to Approved. Both are needed.

Optional: to have refunds and disputes raised in PayPal reflected in Blesta automatically, subscribe the webhook to two more events too: Payment capture refunded (PAYMENT.CAPTURE.REFUNDED) and A dispute is created (CUSTOMER.DISPUTE.CREATED) - the auto-registered webhook already includes both. Whichever way the webhook was registered, having its ID in the Webhook ID setting has every delivery cryptographically verified against PayPal before it is trusted; leaving it blank still verifies each payment by re-fetching it from PayPal instead.

Using the Gateway

Once installed and configured, the PayPal Payment Buttons Gateway will be available for clients to use when paying for their services.

Client View

• When clients pay an invoice, the PayPal buttons are rendered directly on the payment page.
• Clicking one opens PayPal's own checkout, where the client can pay with a PayPal balance or a card without registering.
• After approving, the client is returned to your site and the payment is recorded by the webhook.

Configuring Payment Options

1. Configure the Gateway:

   • Navigate to Settings > Payment Gateways in the Blesta admin panel (/admin/settings/company/gateways/installed/).
   • Set your Client ID and Client Secret, and tick Sandbox if you are testing. The currencies this gateway can be used with are fixed by the extension (see the Currency Mismatch note below); pick from those when assigning it to an order form.

2. Enable PayPal Button for Invoices:

   • In your order form, ensure that the PayPal Payment Button is enabled for client payments.

Testing the Gateway

1. Demo Mode:
   • Tick Demo Mode to have the gateway serve canned PayPal responses instead of contacting PayPal at all. The payment page renders a demo button and no real money moves. Use this to evaluate the flow before you have credentials. Turn it off before going live.
2. Sandbox:
   • Use PayPal's sandbox environment with sandbox app credentials to test real API round trips. Remember to register the webhook against the sandbox app too.
3. Switch to Live Mode:
   • Once testing is complete, untick both Sandbox and Demo Mode, and make sure the webhook is registered on your live REST app.

Troubleshooting Common Issues

1. Clients can pay but nothing is recorded in Blesta:
   • This is almost always a missing webhook. The gateway registers one automatically on save, but an install upgraded from an older version, or one where automatic registration failed silently in the past, may not have one. Confirm the callback URL from the Manage screen is registered on the correct (live or sandbox) REST app, with both required events subscribed. Check Tools > Logs > Gateway to see whether the webhook is arriving at all.
2. Transaction Failures:
   • Verify the Client ID and Client Secret are correct for the environment you selected, and that Sandbox is ticked only when using sandbox credentials.
3. Currency Mismatch:
   • Ensure that the currency settings in Blesta match the currencies accepted by your PayPal account to avoid processing errors. Note that PayPal does not accept decimal amounts in HUF, JPY or TWD; the gateway rounds to whole units for those currencies.
4. A payment applied as credit instead of to the invoices:
   • PayPal limits the field carrying the invoice list to 256 characters. On a payment covering a very large number of invoices at once the list is dropped rather than failing the payment, and the amount is recorded as a client credit instead. Blesta's credit application then covers the invoices.

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.