Stripe Universal

Offer your clients every payment method Stripe supports, from cards and wallets to iDEAL, Klarna and SEPA, on a checkout you control.

What it does

Clients want to pay however suits them, but wiring up every card network, wallet and local payment method yourself is a lot of work to maintain. The Stripe Universal Gateway plugs Stripe's own Checkout straight into Blesta so clients can pay with cards, Apple Pay, Google Pay, Klarna, iDEAL, SEPA, Alipay and dozens of other methods your Stripe account supports, without you building anything extra. Payments, delayed bank methods, refunds and disputes are all synced back into Blesta automatically, so your transaction records stay accurate without manual reconciliation.

Key features

• Every Stripe Payment Method: Clients pay with cards, Apple Pay, Google Pay, Klarna, iDEAL, Bancontact, SEPA, Alipay, WeChat Pay, Cash App Pay, Revolut Pay, BLIK, Swish, TWINT, US bank accounts and more, all through one gateway.
• Turn Individual Methods Off: A checkbox per payment method lets you hide any of them from checkout, so you can accept cards only, drop a method that costs you too much, or run a country-specific method on its own.
• Hosted or Embedded Checkout: Send clients to Stripe's own hosted page, or embed the Stripe checkout directly into your client area so they never leave your site.
• 133 Supported Currencies: Bill and take payment in any of 133 currencies, with zero-decimal currencies such as JPY handled correctly on both payments and refunds.
• Delayed Bank Payments Tracked: Payment methods that take days to clear are recorded as pending as soon as they start and flip to approved when the money lands, so slow bank payments never look like a missing payment.
• Refunds and Disputes Sync Back: A refund issued in the Stripe Dashboard, or a dispute raised against a payment, is picked up automatically and applied to the matching Blesta transaction, so your records stay in step without manual reconciliation.
• Stripe Customers Kept in Sync: Optionally create and update a Stripe customer on every payment with the client's name, company, address and tax or VAT ID, so your Stripe dashboard mirrors your Blesta client list.
• Full Payment Logging: Checkout creation, every notification received and every refund are recorded in Blesta's gateway log, so you can see exactly what happened on any payment without leaving your admin area.

Stripe Universal Gateway by Blesta.Club - Installation Guide

Welcome, and thank you for purchasing the Stripe Universal Gateway! We're delighted to have you as a customer and are committed to ensuring you have a seamless experience. This README aims to 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

For detailed instructions on how to install the Stripe Universal Gateway, please ensure you have the license manager installed for leased extensions and then follow these steps:

1. Obtain the Gateway:

   • Download the Stripe Universal Gateway from the download section of the client area.

2. Upload to Blesta:

   • Upload the Stripe Universal Gateway to your Blesta gateways directory:

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

3. Install the Gateway:

   • Log in to your Blesta admin account.
   • Navigate to Settings > Payment Gateways.
   • Find the Stripe Universal 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 "Stripe Universal" Gateway and click on "Manage".
   • Input your Stripe API keys (Publishable Key and Secret Key) and other necessary settings. Refer to the usage instructions if needed.

2. Register the Webhook (required):

   • The same Manage screen shows a read-only Webhook URL. Copy it.
   • In your Stripe Dashboard, go to https://dashboard.stripe.com/webhooks, add an endpoint with that URL, and subscribe it to at least the payment_intent.succeeded event.
   • Copy that endpoint's signing secret (whsec_...) back into the Webhook Signing Secret field on the Manage screen and save.
   • Payments are recorded only from this Webhook. Without it, clients can pay successfully and the invoice will stay unpaid.

3. Enable Payment Processing:

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

Want to try the gateway before adding real Stripe keys? Tick Mock API mode on the Manage screen. The gateway then runs entirely against bundled sample data, 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.

Stripe Universal Gateway by Blesta.Club - Update Guide

To ensure you are always using the latest version of the Stripe Universal Gateway, follow these steps to update the gateway within your Blesta installation.

Updating to v2.0.0

v2.0.0 is a feature release with no database changes; your existing settings and transactions are untouched. Two things are worth doing after you update:

1. Add the new Webhook events (recommended). To have Blesta reflect refunds you issue from the Stripe Dashboard, disputes/chargebacks, and slow bank payments while they settle, open your Stripe Webhook (https://dashboard.stripe.com/webhooks) and subscribe it to checkout.session.completed, payment_intent.processing, payment_intent.payment_failed, charge.refunded and charge.dispute.created, in addition to the required payment_intent.succeeded. Nothing breaks without them - you simply do not get the new sync.
2. Your Secret Key is now checked when you save. From v2.0.0 the gateway verifies the Secret Key with Stripe when you press Update Settings, and rejects a test/live key mix. If your keys are correct this is invisible; if you are just trying the gateway out without live keys, tick Mock API mode so the settings save.

New optional settings you can now configure: Checkout language, always-collect billing address, Tax ID / VAT ID collection at Checkout, a Statement Descriptor Suffix, Stripe receipt emails, and several newer payment methods in the disable list.

⚠️ Updating to v1.4.0 - read this first

From v1.4.0 a Stripe Webhook is mandatory. Set it up before you update.

Earlier versions recorded a payment twice: once from the Webhook, and once by the gateway notifying itself when the client returned from Stripe. That self-notification has been removed (it double-handled every payment and masked a missing Webhook), so the Webhook is now the only thing that records a payment. If your installation never had one configured, payments will silently stop being recorded after you update.

Before updating:

1. Go to Settings > Payment Gateways, open Stripe Universal, and copy the read-only Webhook URL shown there.
2. In Stripe, go to https://dashboard.stripe.com/webhooks and add an endpoint with that URL, subscribed to the payment_intent.succeeded event.
3. Copy the endpoint's signing secret (it starts with whsec_).
4. After updating, paste that secret into the new Webhook Signing Secret field on the gateway settings page and save. This is strongly recommended - it is what proves an incoming notification genuinely came from Stripe. Leaving it blank still works (the gateway falls back to re-checking each payment directly with Stripe) but is less safe.

Nothing else about the update needs special handling: there are no database changes, and your existing settings and transactions are untouched. Checkout sessions that were already open when you updated continue to reconcile correctly.

Steps for Updating the Gateway

1. Download the Latest Version

• Visit the download section of the client area to obtain the latest version of the Stripe Universal 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/stripe_universal/

3. Update the Gateway in Blesta

• Log in to your Blesta admin account.
• Navigate to Settings > Payment Gateways.
• Locate the Stripe Universal Gateway in the list and click the "Upgrade" or "Update" button, if available.

Testing the Update

1. Test Mode:

   • Before switching back to live transactions, you may want to test the gateway in Stripe's test 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. API Key Issues:

• If transactions are failing after the update, verify that the correct API keys are configured in the gateway settings. Ensure that you're using live API keys for real transactions and test keys for testing purposes.

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

Stripe Universal Gateway by Blesta.Club - Usage Guide

Welcome, and thank you for choosing the Stripe Universal Gateway! We're delighted to have you as a customer and are committed to ensuring you have a seamless experience. This guide aims to walk you through the general usage and configuration of your gateway. If you're new to Blesta or encounter any issues, please don't hesitate to reach out for support.

Gateway Capabilities

The Stripe Universal Gateway is designed to process payments within Blesta, offering a seamless integration with your billing system. With support for a variety of payment options through Stripe, it provides flexibility and convenience for both you and your clients.

Now with support for embedded or hosted pages for payments and webhooks!

Things to Note

1. A Webhook is required. Payments are recorded when Stripe calls your Webhook URL with the payment_intent.succeeded event, not when the client's browser returns to your site. Without a configured Webhook, clients can pay successfully and the invoice will stay unpaid. Set it up before you take your first payment (see "Configure Payment Settings" below).

2. Set the Webhook Signing Secret. Strongly recommended. Your callback URL is reachable by anyone; the signing secret is what lets the gateway prove a notification really came from Stripe and reject anything that didn't. Left blank, the gateway falls back to re-checking each payment directly with Stripe before recording it: safe, but one round-trip slower and one layer thinner.

3. Currency Support: Stripe supports multiple currencies; configure your currency settings in Blesta accordingly to avoid processing errors.

4. Make sure additional methods are enabled from https://dashboard.stripe.com/settings/payments before usage! Obviously they override the configuration in Blesta

5. sk or rk? Used interchangably - Don't panic if they're worded slightly different until sk is phased out by Stripe

6. Refund sync covers full refunds only. When you refund a payment in full from the Stripe Dashboard, the matching Blesta transaction is marked Refunded automatically. A partial Dashboard refund is deliberately left alone: the gateway flips the status of the original transaction rather than recording a separate refund entry, so reflecting a partial would report the whole payment as refunded. Adjust Blesta by hand after a partial Dashboard refund.

7. Mock API mode runs the whole gateway against bundled sample data instead of Stripe - useful for trying it out or demoing it without API keys. No real money moves and nothing reaches Stripe. Leave it off on a live installation.

Using the Gateway

Once the Stripe Universal Gateway is installed and configured, it will allow you to process payments for your Blesta billing system. Below are the general steps for managing the gateway:

Configure Payment Settings

1. Manage the Gateway:

   • Navigate to Settings > Payment Gateways in your Blesta admin panel (/admin/settings/company/gateways/installed/).
   • Select "Stripe Universal" Gateway and click on "Manage".
   • Enter your Stripe API keys (Publishable Key and Secret/Restricted Key) and configure the necessary payment options like accepted currencies and card types. Click "Update Settings" to save your changes.
   • Choose between Embedded or hosted gateway
   • Set up the Webhook (required). Copy the read-only Webhook URL shown on this page, go to https://dashboard.stripe.com/webhooks, add an endpoint with that URL subscribed to the payment_intent.succeeded event, then copy that endpoint's signing secret (whsec_...) back into the "Webhook Signing Secret" field here. Payments are only recorded via this Webhook. To also reflect delayed/bank payments, Dashboard refunds and disputes in Blesta, subscribe the same endpoint to checkout.session.completed, payment_intent.processing, payment_intent.payment_failed, charge.refunded and charge.dispute.created.
   • Checkout Options (optional). Show Stripe Checkout in each client's language, always collect the billing address, let clients enter a Tax ID / VAT ID at Checkout, set a Statement Descriptor Suffix (what shows on the client's card statement), and optionally have Stripe email its own receipt.
   • Disable Payment Gateways. If you went a bit wild in Stripe and enabled everything, You can narrow down your choices here!
   • Finally, Ensure the currencies are set correctly and save! Then enable the gateway on order forms!

   Note: when you save, the gateway verifies your Secret Key with Stripe and checks that your Publishable and Secret keys are from the same mode (both test or both live). If you are only trying the gateway out without live keys, tick Mock API mode so the settings save.

2. Enable Payment Processing:

   • Ensure that the Stripe Universal Gateway is enabled for processing payments in your Blesta system.

Testing the Gateway

Before going live, it is recommended to run a test transaction using Stripe’s test mode to ensure everything is working as expected. This allows you to verify that the integration is correct without making real charges.

1. Enable Test Mode:

   • In Stripe, switch to test mode and generate test API keys.
   • Use these test keys in the Blesta gateway settings and perform a test transaction to verify functionality.

2. Switch to Live Mode:

   • Once testing is complete, replace the test API keys with live API keys in Blesta to start processing real payments.

Troubleshooting Common Issues

Transaction Failures

• Verify API Keys: Ensure the API keys entered in the Blesta gateway settings are correct.
• Check Stripe Mode: Ensure that your Stripe account is not in test mode when trying to process live transactions.

"Cannot declare class" error

• This happens if a vendor/ folder with the Stripe SDK has been added to this gateway's directory while another installed Stripe gateway (such as the stock Stripe Payments or Stripe Gateway) also bundles its own copy. Remove any extra vendor/ folder from Stripe Universal; it uses the Stripe SDK that ships with Blesta core and does not need or ship its own.

Currency Mismatch

• Currency Configuration: Make sure the currency set in Blesta matches the currency settings in your Stripe account to avoid processing errors.

Quick Support

If you need help with setting up or managing the gateway, here’s how to obtain your Stripe API keys:

1. Login to Stripe:

   • Visit the Stripe Dashboard and log in with your credentials.

2. API Keys:

   • Navigate to Developers > API Keys.
   • Copy the "Publishable Key" and "Secret Key" from the dashboard.

3. Configure in Blesta:

   • Paste these keys into the corresponding fields in your Blesta gateway settings and save your changes.

Contact Us

If you encounter any issues or have suggestions for improving the gateway, please don't hesitate to contact us. We are committed to providing robust updates and appreciate customer feedback.