README

Adding the Stripe Express Checkout Element to Commerce-Stripe.

Table of Contents

• Features
• Showcase
• Requirements
• Installation
• Setup
  • Products page
  • Cart page
  • Order complete
• Configuration
  • Global Settings
  • Local Settings
• Extending and Customizing
  • Event Hooks
  • Frontend JS
    • Events
    • Public Methods
    • Example

Features

• Adds the Stripe Express Checkout Element to your Craft Commerce site.
• Checkout products and carts with a single click.
• Supports Apple Pay, Google Pay, PayPal and much more.
• Supports shipping address and phone number requirements.
• Supports all the options from the Stripe Express Checkout Element.
• Intercept request through event hooks.
• Automatically adjusts costs based on configured shipping rules.
• Restrict deliveries to allowed countries in your Commerce settings.

Showcase

TODO: Add gif/webm of the express checkout; Maybe a YouTube Video showcasing the plugin would be neat

Requirements

• PHP >= 8.2
• Stripe Account
• Craft CMS ^5.0.0
• Craft Commerce ^5.0.0
• Craft Commerce Stripe ^5.0.0

Installation

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

From the Plugin Store

e Go to the Plugin Store in your project’s Control Panel and search for “Stripe Express Checkout”. Then press “Install”.

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 craft-unit/craft-stripe-express-checkout

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

Setup

1. Create a Stripe Account or use an existing one.
2. Install Craft Commerce and the Stripe Gateway Plugin.
3. Follow the setup instruction for the Stripe Gateway Plugin.
4. Go to the plugin settings in the sidebar and select the gateway you just created.
5. Render the buttons on your products and cart page.
6. Be sure to handle the order complete event. You can use the fetch API to ask for the order and return it to the success page. See the Order complete section for more information.

Products page

products/_product.twig

{{ craft.expressCheckout.buttons({
    itemsId: product.defaultVariant.id
}) | raw }}

{# or... #}

{{ craft.expressCheckout.buttons({
    items: [{
      id: product.defaultVariant.id,
      qty: 1,
    }],
}) | raw }}

Cart page

cart.twig

{{ craft.expressCheckout.buttons({ 
  cart: craft.commerce.carts.cart,
 }) | raw }}

Order complete

After the order is completed, the user will be redirected to the success_url you set in the options. At this point in time your order might not be completed in Craft Commerce hence why you won't see the completed order. You can use fetch to ask for the order and return it to the success page. Use the number query parameter to get the order number.

// Get the order number from the query parameter
const orderNumber = new URLSearchParams(window.location.search).get('number');
const order = await fetch(`/actions/commerce/stripe-express-checkout/get-order?number=${orderNumber}`);

Configuration

Configuration can be done globally in the plugin settings or locally by passing settings to the craft.expressCheckout.buttons function. Passing the settings to the function will override the global settings. You can find all the options in the Stripe documentation.

Global Settings

Local settings

{% set settings  = {
    name: product.slug ~ '-express-checkout',
    shippingAddressRequired: true,
    phoneNumberRequired: false,
    paymentMethodOrder: ['paypal', 'googlePay', 'link'],
    buttonTheme: {
      paypal: 'blue',
    },
    buttonHeight: 55,
    buttonType: {
      paypal: 'pay',
      googlePay: 'order',
    },
    wallets: {
      applePay: 'always',
      googlePay: 'always',
    }
    {# and more... #}
} %}

Extending and Customizing

Event Hooks

Variable::EVENT_MODIFY_BUTTON_OPTIONS

Fired right before the buttons are rendered. Modify $event->options to override the options passed to the client side StripeExpressCheckout.init() call. Setting paymentMethodConfiguration lets you control which payment methods the Express Checkout Element displays (e.g. a different set than the regular onsite checkout):

use craftunit\craftstripeexpresscheckout\events\ModifyButtonOptionsEvent;
use craftunit\craftstripeexpresscheckout\web\Variable;
use craft\helpers\App;
use yii\base\Event;

Event::on(
    Variable::class,
    Variable::EVENT_MODIFY_BUTTON_OPTIONS,
    function (ModifyButtonOptionsEvent $event) {
        if ($pmc = App::env('STRIPE_EXPRESS_PMC')) {
            $event->options['paymentMethodConfiguration'] = $pmc;
        }
    }
);

Frontend JS

Each button uses the StripeExpressCheckout class. This class is responsible for creating the Stripe Element and handling the payment intent. The instance gets added to the window.stripeExpressCheckouts object. You can give your express checkout buttons a custom name by passing the name option to the craft.expressCheckout.buttons function. You can then access the instance by calling window.stripeExpressCheckouts['your-custom-name'] or StripeExpressCheckout.getByName('your-custom-name').

Take a look at the StripeExpressCheckout class to see all the available events and methods.

Events

All Events get dispatched on the window object. You can listen to them by adding an event listener to the window object.

window.addEventListener('stripe-express-checkout:init', event => {
  const {name, instance} = event.detail;
  console.log(name, instance);
});

Public Methods

Example

Below is a example showing how to manipulate the quantity of a product in the cart using the setItemQty method.

<div class="quantity">
  <input type="number" name="qty" value="1" min="1">
</div>

{% set params = requiredParams | merge(optionalParams) %}
{{ craft.expressCheckout.buttons({
  name: 'foo',
  items: [{
    id: variant.id,
    qty: 1,
  }]
}) | raw }}

<script>
  // Wait for the express checkout to initialize
  window.addEventListener('stripe-express-checkout:init', event => {
    // Get the instance by name
    const {name, instance} = event.detail;
    if (name !== 'product-express-checkout') return;

    const quantityInput = document.querySelector('.quantity input');
    quantityInput.addEventListener('input', event => {
      const qty = parseInt(event.target.value, 10);
      // Set the quantity of the item
      instance.setItemQty(qty, {{ variant.id }});
    });
  });
</script>