flux-se / sylius-payum-stripe-plugin
Payum Stripe gateways plugin for Sylius.
Installs: 241 208
Dependents: 0
Suggesters: 0
Security: 0
Stars: 55
Watchers: 6
Forks: 24
Open Issues: 6
Type:sylius-plugin
Requires
- flux-se/payum-stripe-bundle: ^2.0
- sylius/sylius: ^1.9
Requires (Dev)
- ext-json: *
- behat/behat: ^3.7
- dbrekelmans/bdi: ^1.2
- friends-of-behat/mink: ^1.9
- friends-of-behat/mink-browserkit-driver: ^1.4
- friends-of-behat/mink-debug-extension: ^2.0
- friends-of-behat/mink-extension: ^2.5
- friends-of-behat/page-object-extension: ^0.3
- friends-of-behat/suite-settings-extension: ^1.1
- friends-of-behat/symfony-extension: ^2.1
- friends-of-behat/variadic-extension: ^1.3
- phpspec/phpspec: ^7.2
- phpstan/extension-installer: ^1.0
- phpstan/phpstan-doctrine: ^1.0
- phpstan/phpstan-strict-rules: ^1.0
- phpstan/phpstan-webmozart-assert: ^1.0
- phpunit/phpunit: ^9.5
- polishsymfonycommunity/symfony-mocker-container: ^1.0
- robertfausk/behat-panther-extension: ^1.1
- sylius-labs/coding-standard: ^4.1
- sylius-labs/suite-tags-extension: ^0.2.0
- symfony/browser-kit: ^5.4|^6.4
- symfony/debug-bundle: ^5.4|^6.4
- symfony/dotenv: ^5.4|^6.4
- symfony/http-client: ^5.4|^6.4
- symfony/intl: ^5.4|^6.4
- symfony/runtime: ^5.4|^6.4
- symfony/web-profiler-bundle: ^5.4|^6.4
- symfony/webpack-encore-bundle: ^1|^2
README
Sylius Payum Stripe gateway plugin
This plugin is designed to add a new gateway to Payum to support Stripe Checkout Session. It supports one time payment and authorized payment by placing a hold on a card.
Refund is also possible but disabled by default to avoid mistakes, use this config to enable it :
# config/packages/flux_se_sylius_payum_stripe.yaml flux_se_sylius_payum_stripe: refund_disabled: false
See https://stripe.com/docs/payments/checkout for more information.
Installation
Install using Composer :
composer remove --dev stripe/stripe-php composer require flux-se/sylius-payum-stripe-plugin
💡 If the flex recipe has not been applied then follow the next step.
Enable this plugin :
<?php # config/bundles.php return [ // ... FluxSE\SyliusPayumStripePlugin\FluxSESyliusPayumStripePlugin::class => ['all' => true], FluxSE\PayumStripeBundle\FluxSEPayumStripeBundle::class => ['all' => true], // ... ];
Create the file config/packages/flux_se_sylius_payum_stripe.yaml
and add the following content
imports: - { resource: "@FluxSESyliusPayumStripePlugin/Resources/config/config.yaml" }
Configuration
Sylius configuration
Go to the admin area, log in, then click on the left menu item "CONFIGURATION > Payment methods". Create a new payment method type "Stripe Checkout Session (with SCA support)" :
Then a form will be displayed, fill-in the required fields :
1. the "code" field (ex: "stripe_checkout_session_with_sca").
💡 The code will be the
gateway name
, it will be needed 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) :
📖 NOTE1: You can add as many webhook secret keys as you need here, however generic usage need 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
Get your publishable_key
and your secret_key
on your Stripe dashboard :
https://dashboard.stripe.com/test/apikeys
Webhook key
Got to :
https://dashboard.stripe.com/test/webhooks
Then create a new endpoint with those events:
The URL to fill is the route named payum_notify_do_unsafe
with the gateway
param equal to the gateway name
(Payment method code), here is an example :
https://localhost/payment/notify/unsafe/stripe_checkout_session_with_sca
📖 As you can see in this example the URL is dedicated to
localhost
, you will need to provide to Stripe a public host name in order to get the webhooks working.
📖 Use this command to know the exact structure of
payum_notify_do_unsafe
routebin/console debug:router payum_notify_do_unsafe
📖 Use this command to know the exact name of your gateway, or just check the
code
of the payment method in the Sylius admin payment method index.bin/console debug:payum:gateway
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 :
- Example with
stripe_checkout_session_with_sca
as gateway name:stripe listen \ --events checkout.session.completed,checkout.session.async_payment_failed,checkout.session.async_payment_succeeded \ --forward-to https://localhost/payment/notify/unsafe/stripe_checkout_session_with_sca
- Example with
stripe_js_with_sca
as gateway name:stripe listen \ --events payment_intent.canceled,payment_intent.succeeded \ --forward-to https://localhost/payment/notify/unsafe/stripe_js_with_sca
💡 Replace the --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 in the Sylius admin.
⚠️ Using the command
stripe trigger checkout.session.completed
will always result in a500 error
, because the test object will not embed any usable metadata.
More?
See documentation here : https://github.com/FLUX-SE/PayumStripe/blob/master/README.md
API (Sylius Api Platform)
Stripe JS gateway
The endpoint : GET /api/v2/shop/orders/{tokenValue}/payments/{paymentId}/configuration
will make a Payum Capture
or an Authorize
and respond with the Stripe Payment Intent client secret, like this :
{ 'publishable_key': 'pk_test_1234567890', 'use_authorize': false, 'stripe_payment_intent_client_secret': 'a_secret' }
After calling this endpoint your will be able to use Stripe Elements to display a Stripe Payment form, the same as this template is doing it: https://github.com/FLUX-SE/PayumStripe/blob/master/src/Resources/views/Action/stripeJsPaymentIntent.html.twig. More information here : https://docs.stripe.com/payments/payment-element
Stripe Checkout Session gateway
The endpoint : GET /api/v2/shop/orders/{tokenValue}/payments/{paymentId}/configuration
will make a Payum Capture
or an Authorize
and respond with the Stripe Checkout Session url, like this :
{ 'publishable_key': 'pk_test_1234567890', 'use_authorize': false, 'stripe_checkout_session_url': 'https://checkout.stripe.com/c/pay/cs_test...' }
Since this endpoint is not able to get any data from you, a service can be decorated to specify the Stripe Checkout Session success_url
you need.
Decorate this service : flux_se.sylius_payum_stripe.api.payum.after_url.stripe_checkout_session
to generate your own dedicated url.
You will have access to the Sylius Payment
to decide what is the url/route and the parameters of it.