Skip to content
Stripe payment gateway plugin for Craft Commerce 2
Branch: master
Clone or download
Pull request Compare This branch is 2 commits ahead of develop.
Latest commit d3bbf14 May 30, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore @license MIT Feb 28, 2018 Clarify `buildGatewayRequest` documentation. (#58) May 29, 2019

Stripe for Craft Commerce icon

Stripe for Craft Commerce

This plugin provides a Stripe integration for Craft Commerce, with support for Payment Intents as well as traditional charges.


This plugin requires Craft 3.1.5 and Craft Commerce 2.1.4 or later.

This plugin uses Stripe API version '2019-03-14'.


You can install this plugin from the Plugin Store or with Composer.

From the Plugin Store

Go to the Plugin Store in your project’s Control Panel and search for “Stripe for Craft Commerce”. Then click on the “Install” button in its modal window.

With Composer

Open your terminal and run the following commands:

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require craftcms/commerce-stripe

# tell Craft to install the plugin
./craft install/plugin commerce-stripe

Changes in 2.0

The old “Stripe” gateway has been renamed to “Stripe Charge”, and is now deprecated. A new “Stripe Payment Intents” gateway has been added which uses Stripe’s new Payment Intents API, and utilizes 3D Secure 2, which is easier to implement than the old 3D Secure standard and delivers a better customer experience. Stripe will begin declining all EU charges using its old charge API on September 14, 2019, so switching to the new Payment Intents gateway is highly recommended. (See Stripe’s Strong Customer Authentication guide for more info.)


To add the Stripe payment gateway, go to Commerce → Settings → Gateways, create a new gateway, and set the gateway type to “Stripe Payment Intents”.

Note: A “Stripe Charge” gateway is also available, but it is deprecated. (See Changes in 2.0.)

Payment security enforcement

This plugin does not allow submitting credit card details directly. Instead, you must create a payment method before submitting the payment form. See here for an example on how it's done when calling the default getPaymentFormHtml() method on the gateway.


Configure Stripe

Set up a webhook endpoint in your Stripe dashboard API settings. The URL for this endpoint can be found in your Commerce Stripe gateway settings.

It is recommended to emit all possible events, but the required events are:

For 3D secure payments (if using Stripe Charge gateway)

  • source.cancelled
  • source.chargeable
  • source.failed

For subscriptions

The bare minimum of events required are:

  • invoice.payment_succeeded
  • customer.subscription.deleted

However, it is strongly recommended to enable the following events as well to ensure your Commerce subscriptions stay in sync with your Stripe dashboard:

  • plan.deleted
  • plan.updated
  • invoice.created
  • customer.subscription.updated

Configure the gateway

When the endpoint has been set up, you can view the signing secret in its settings. Enter this value in your Stripe gateway settings in the appropriate field.

Configuration settings

The chargeInvoicesImmediately setting

For subscriptions with automatic payments, Stripe creates an invoice 1-2 hours before attempting to charge it. By setting this to true in your commerce-stripe.php config file, you can force Stripe to charge this invoice immediately.

This setting affect all Stripe gateways on your Commerce installation.


Creating a subscription plan

  1. To create a subscription plan, it must first be created on Stripe.
  2. Go to Commerce → Settings → Subscription plans and create a new subscription plan.

Options when subscribing

The trialDays parameter

When subscribing, you can pass a trialDays parameter. The first full billing cycle will start once the number of trial days lapse. Default value is 0.

Options when cancelling a subscription.

The cancelImmediately parameter

If this parameter is set to true, the subscription is canceled immediately. Otherwise, it is marked to cancel at the end of the current billing cycle. Defaults to false.

Options when switching between different subscription plans

The prorate parameter

If this parameter is set to true, the subscription switch will be prorated. Defaults to false.

The billImmediately parameter

If this parameter is set to true, the subscription switch is billed immediately. Otherwise, the cost (or credit, if prorate is set to true and switching to a cheaper plan) is applied to the next invoice.

Please note, that the subscription switch will be billed immediately regardless of this parameter if the billing periods differ.


The plugin provides several events that allow you to modify the behaviour of your integration.

Payment request related events

The buildGatewayRequest event

Plugins get a chance to provide additional metadata to any request that is made to Stripe in the context of paying for an order. This includes capturing and refunding transactions.

There are some restrictions:

  • Changes to the Transaction model available as the transaction property will be ignored;
  • Changes to the order_id, order_number, transaction_id, client_ip, and transaction_reference metadata keys will be ignored;
  • Changes to the amount, currency and description request keys will be ignored;
use craft\commerce\models\Transaction;
use craft\commerce\stripe\events\BuildGatewayRequestEvent;
use craft\commerce\stripe\base\Gateway as StripeGateway;
use yii\base\Event;

Event::on(StripeGateway::class, StripeGateway::EVENT_BUILD_GATEWAY_REQUEST, function(BuildGatewayRequestEvent $e) {
  if ($e->transaction->type === 'refund') {
    $e->request['someKey] = 'some value';

The receiveWebhook event

Plugins get a chance to do something whenever a webhook is received. This event will be fired regardless the Gateway has done something with the webhook or not.

use craft\commerce\stripe\events\ReceiveWebhookEvent;
use craft\commerce\stripe\base\Gateway as StripeGateway;
use yii\base\Event;

Event::on(StripeGateway::class, StripeGateway::EVENT_RECEIVE_WEBHOOK, function(ReceiveWebhookEvent $e) {
  if ($e->webhookData['type'] == 'charge.dispute.created') {
    if ($e->webhookData['data']['object']['amount'] > 1000000) {
      // Be concerned that a USD 10,000 charge is being disputed.

Subscription events

The createInvoice event

Plugins get a chance to do something when an invoice is created on the Stripe gateway.

use craft\commerce\stripe\events\CreateInvoiceEvent;
use craft\commerce\stripe\base\SubscriptionGateway as StripeGateway;
use yii\base\Event;

Event::on(StripeGateway::class, StripeGateway::EVENT_CREATE_INVOICE, function(CreateInvoiceEvent $e) {
    if ($e->invoiceData['billing'] === 'send_invoice') {
        // Forward this invoice to the accounting dpt.

The beforeSubscribe event

Plugins get a chance to tweak subscription parameters when subscribing.

use craft\commerce\stripe\events\SubscriptionRequestEvent;
use craft\commerce\stripe\base\SubscriptionGateway as StripeGateway;
use yii\base\Event;

Event::on(StripeGateway::class, StripeGateway::EVENT_BEFORE_SUBSCRIBE, function(SubscriptionRequestEvent $e) {
    $e->parameters['someKey'] = 'some value';

Deprecated events

The following events are deprecated as they are associated with the deprecated Stripe Charge gateway.

The receive3dsPayment event

Plugins get a chance to do something whenever a successful 3D Secure payment is received.

use craft\commerce\Plugin as Commerce;
use craft\commerce\stripe\events\Receive3dsPaymentEvent;
use craft\commerce\stripe\gateways\Gateway as StripeGateway;
use yii\base\Event;

Event::on(StripeGateway::class, StripeGateway::EVENT_RECEIVE_3DS_PAYMENT, function(Receive3dsPaymentEvent $e) {
    $order = $e->transaction->getOrder();
    $orderStatus = Commerce::getInstance()->getOrderStatuses()->getOrderStatusByHandle('paid');
    if ($order && $paidStatus && $order->orderStatusId !== $paidStatus->id && $order->getIsPaid()) {
        $order->orderStatusId = $paidStatus->id;
You can’t perform that action at this time.