StripePlugin

This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.

Installation

1. Install the plugin ()

   composer require flux-se/sylius-stripe-plugin

2. Enable this plugin :

   <?php
   
   # config/bundles.php
   
   return [
       // ...
       FluxSE\SyliusStripePlugin\FluxSESyliusStripePlugin::class => ['all' => true],
       // ...
   ];

3. Import configuration

   # config/packages/flux_se_sylius_stripe.yaml
   
   imports:
   # ...
   - { resource: "@FluxSESyliusStripePlugin/config/config.yaml" }

4. Import shop routes (required for the Express Checkout cart button — Apple Pay, Google Pay, Link, etc.)

   # config/routes/flux_se_sylius_stripe.yaml
   
   flux_se_sylius_stripe_express_checkout_shop:
       resource: "@FluxSESyliusStripePlugin/config/routes/shop_express_checkout.yaml"

Configuration

• Go to the admin area.

• Log in.

• Click on the left menu item "CONFIGURATION > Payment methods".

• Create a new payment method type "Stripe (Checkout)" or "Stripe (Web Elements)":

  ![Create a new payment method][docs-assets-create-payment-method]

• The next chapter will explain how to fill the payment method creation form.

Payment Method configuration

A form will be displayed, fill-in the required fields :

1. The "code" field (ex: "my_shop_stripe_checkout").

💡 The code will be the gateway name, it will be necessary to build the right webhook URL later (see Webhook key section for more info).

2. Choose which channels this payment method will be affected to.

3. The gateway configuration (need info from here) :

![Gateway Configuration][docs-assets-gateway-configuration]

![Gateway Configuration][docs-assets-gateway-configuration-authorize]

📖 NOTE1: You can add as many webhook secret keys as you need here, however generic usage needs only one.

📖 NOTE2: the screenshot contains false test credentials.

4. Give to this payment method a display name (and a description) for each language you need.

Finally, click on the "Create" button to save your new payment method.

API keys

Install the Sylius Stripe App on your Stripe account. Its Settings Page exposes both keys this plugin needs:

• the publishable key (pk_test_… / pk_live_…) for the "Publishable key" field,
• a Restricted API Key (rk_test_… / rk_live_…) for the "Restricted API key" field.

Webhook key

Got to :

https://dashboard.stripe.com/test/webhooks

Then create a new endpoint with those events:

Gateway	stripe_checkout	stripe_web_elements
Webhook events	- checkout.session.completed - checkout.session.async_payment_failed - checkout.session.async_payment_succeeded - checkout.session.expired - setup_intent.canceled (⚠️ Only when using setup mode) - setup_intent.succeeded (⚠️ Only when using setup mode)	- payment_intent.canceled - payment_intent.succeeded - setup_intent.canceled (⚠️ Only when using setup mode) - setup_intent.succeeded (⚠️ Only when using setup mode)

💡 Express Checkout on the cart page (enable_express_checkout toggle on) always creates a PaymentIntent on Stripe regardless of the gateway type. If you enable it on a stripe_checkout PaymentMethod, add these events to that endpoint in addition to the checkout.session.* ones listed above:

• payment_intent.succeeded
• payment_intent.canceled
• payment_intent.processing

For stripe_web_elements the same payment_intent.* events are already required by the regular flow — no extra subscription is needed when the toggle is on.

See Express Checkout on the cart page for the full setup (domain registration, wallet activation, local testing). Which wallets actually appear on the button (Apple Pay, Google Pay, Link, PayPal, Amazon Pay) is decided by your Stripe Dashboard configuration and the customer's browser — the plugin does not hard-code that list.

The URL to fill is the route named sylius_payment_method_notify with the {code} param equal to the payment method code, here is an example :

https://localhost/payment-methods/my_shop_stripe_checkout

📖 As you can see in this example the URL is dedicated to localhost, you will need to provide to Stripe a public host name to get the webhooks working.

📖 Use this command to know the exact structure of sylius_payment_method_notify route

bin/console debug:router sylius_payment_method_notify

Test or dev environment

Webhooks are triggered by Stripe on their server to your server. If the server is into a private network, Stripe won't be allowed to reach your server.

Stripe provide an alternate way to catch those webhook events, you can use Stripe cli : https://stripe.com/docs/stripe-cli Follow the link and install Stripe cli, then use those command line to get your webhook key :

First login to your Stripe account (needed every 90 days) :

stripe login

Then start to listen for the Stripe events (minimal ones are used here), forwarding request to your local server :

1. Example with my_shop_stripe_checkout as payment method code:

   stripe listen \
      --events checkout.session.completed,checkout.session.async_payment_failed,checkout.session.async_payment_succeeded,checkout.session.expired \
      --forward-to https://localhost/payment-methods/my_shop_stripe_checkout

2. Example with my_shop_stripe_web_elements as payment method code:

   stripe listen \
      --events payment_intent.canceled,payment_intent.succeeded \
      --forward-to https://localhost/payment-methods/my_shop_stripe_web_elements

3. Example with my_shop_stripe_checkout as payment method code and Express Checkout enabled (merges the checkout.session.* events of the regular flow with the payment_intent.* events emitted by the cart-page wallet flow):

   stripe listen \
      --events checkout.session.completed,checkout.session.async_payment_failed,checkout.session.async_payment_succeeded,checkout.session.expired,payment_intent.succeeded,payment_intent.canceled,payment_intent.processing \
      --forward-to https://localhost/payment-methods/my_shop_stripe_checkout

💡 Replace --forward-to argument value with the right one you need.

When the command finishes, a webhook secret key is displayed, copy it to your Payment method configuration edit form in the Sylius admin.

⚠️ Using the command stripe trigger checkout.session.completed will always result in a 500 error, because the test object will not embed any usable metadata.

Advanced documentation

• API (Sylius using APIPlatform)
• Webhook events
• Express Checkout on the cart page

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Authors

This plugin was originally created by:

  

Kudos to Prometee and all contributors 🙏

License

This plugin is released under the MIT License.