Download the PHP package programmatordev/kirby-stripe-checkout without Composer

Kirby Stripe Checkout

Stripe Checkout for Kirby CMS.

[!CAUTION] This plugin is still in its early stages. This means that it should not be considered stable, so use it at your own risk. Expect a lot of breaking changes until version 1.0.

Features

• 🔥 Stripe Checkout for both hosted and embedded modes;
• 💸 Handles sync and async payments (credit card, bank transfer, etc.);
• 📦 Orders panel page;
• ⚙️ Checkout Settings panel page;
• 🪝 Hooks for all payment status (completed, pending and failed), orders and checkout sessions;
• 🛒 Cart management;
• ...and more.

Documentation

• Requirements
• Installation
• Options
• Hooks
• Cart
• Translations
• Setup
• Development
• Production

Requirements

• PHP 8.2 or higher;
• Kirby CMS 4.0 or higher;
• Stripe account.

Installation

Install the plugin via Composer:

Options

Default options:

[!TIP] It is recommended that you use a library that enables environment variables to store your project credentials in a separate place from your code and to have separate development and production access keys.

List of all available options:

• stripePublicKey
• stripeSecretKey
• stripeWebhookSecret
• uiMode
• currency
• successPage
• cancelPage
• returnPage
• ordersPage
• settingsPage
• cartSnippet
• translations

stripePublicKey

type: string required

Stripe public key found on the Stripe Dashboard.

stripeSecretKey

type: string required

Stripe secret key found on the Stripe Dashboard.

stripeWebhookSecret

type: string required

Webhook secret found when a Webhook is created in the Stripe Dashboard.

Check the Setup section for more information.

currency

type: string default: EUR required

Three-letter ISO currency code. Must be a supported currency.

uiMode

type: string default: hosted required

The UI mode of the Checkout Session.

Available options:

• hosted the Checkout Session will be displayed on a Stripe-hosted page (where the user will be redirected);
• embedded the Checkout Session will be displayed as an embedded form on the website page.

successPage

type: string

This option is required if uiMode is set to hosted.

Page to where a user will be redirected when a Checkout Session is completed (form successfully submitted).

Must be a valid Kirby page id. The id is used, instead of a URL, to make sure that the user is redirected correctly in case of multi-language setups.

cancelPage

type: string

This option is required if uiMode is set to hosted.

Page to where a user will be redirected if decides to cancel the payment and return to the website.

Must be a valid Kirby page id. The id is used, instead of a URL, to make sure that the user is redirected correctly in case of multi-language setups.

returnPage

type: string

This option is required if uiMode is set to embedded.

Page to where a user will be redirected when a Checkout Session is completed (form successfully submitted).

Must be a valid Kirby page id. The id is used, instead of a URL, to make sure that the user is redirected correctly in case of multi-language setups.

ordersPage

type: string default: orders required

Kirby Panel page with the overview of all orders.

Must be a valid Kirby page id.

Check the Setup section for more information.

settingsPage

type: string default: checkout-settings required

Kirby Panel page with Checkout settings.

Must be a valid Kirby page id.

Check the Setup section for more information.

cartSnippet

type: ?string default: null

When set, it will look for the snippet with the same name and return the HTML content on every cart API response. Useful when adding, updating or removing cart contents, and you want to update the HTML on every request.

If snippet does not exist or is empty, it will return null.

translations

type: array default: []

Use this option to overwrite existing translations or to add a new one that is not bundled with the plugin. Check the translations folder for all available translations.

An example when overwriting an existing translation:

If a translation does not exist, you can provide yours:

Hooks

• stripe-checkout.session.create:before
• stripe-checkout.order.create:before
• stripe-checkout.payment:succeeded
• stripe-checkout.payment:pending
• stripe-checkout.payment:failed

stripe-checkout.session.create:before

Triggered before creating a Checkout Session. Useful to set additional Checkout Session parameters.

You can check all the available parameters in the Stripe API documentation page.

[!WARNING] Take into account that the sessionParams variable contains data required to initialize a Checkout Session. You may change these but at your own risk.

stripe-checkout.order.create:before

Triggered before creating an Order page in the Panel. Useful to set additional Order data in case you add additional fields in the blueprint or want to change existing ones.

[!WARNING] Take into account that the orderContent variable contains all data required to create an Order page. You may change these but at your own risk.

stripe-checkout.payment:succeeded

Triggered when a payment is completed successfully.

[!IMPORTANT] This hook is triggered for both sync and async payments. An example of a sync payment is when a customer pays using a credit card as the payment method. An example of an async payment is when a customer wants to pay through a bank transfer. In this case, the hook will only be triggered when the actual bank transfer is successfully performed. Check the stripe-checkout.payment:pending hook to handle pending payments.

stripe-checkout.payment:pending

Triggered when an order is pending payment.

This happens when a customer uses an async payment method, like a bank transfer, where the Checkout form is submitted successfully, but the payment is yet to be made.

stripe-checkout.payment:failed

Triggered when a payment has failed.

This happens when a customer uses an async payment method, like a bank transfer, where the Checkout form is submitted successfully, but the payment has failed (for example, the deadline for the payment has expired).

Cart

A cart management system already exists and is required to be able to create a Checkout Session. The reason for this is that the checkout line items are generated based on the current cart contents. This means that the cart must have at least one added item; otherwise it will throw an error.

PHP

A cart() function is available to manage the cart contents.

Default options:

Available methods:

• addItem
• updateItem
• removeItem
• items
• totalQuantity
• totalAmount
• currency
• currencySymbol
• cartSnippet
• destroy
• toArray

addItem

Adds an item to the cart.

The id and quantity values are required. An additional options value is available to set the options of a product (color, size, etc.).

Important to note that the id must be a valid Kirby page id and the page must include a valid price field. Otherwise, an exception will be thrown. Check the Setup section for more information.

Information related to the price, name and thumbnail are added to the item based on the given id (and related Kirby page).

If the item that is being added already exists in the cart, the sum of its quantities will be made into a single item.

If the same item is added but with different options, it will be considered different items in the cart. For example, a t-shirt with the color blue and the same t-shirt with the color red will be different items.

A key is returned that uniquely identifies the item in the cart.

updateItem

Updates the quantity of an item in the cart.

removeItem

Removes an item from the cart.

items

Collection with all items in the cart.

totalQuantity

Get the total quantity of items in the cart.

totalAmount

Get the total amount in the cart.

currency

Get currency.

currencySymbol

Get currency symbol.

cartSnippet

Get cart snippet if set in the cartSnippet option.

if render is set to true it will return the rendered HTML snippet

destroy

Destroy all contents and reset the cart to the initial state.

toArray

Converts all cart contents into an array.

JavaScript

A JavaScript library is currently being developed. Meanwhile, check the API endpoints section below for examples on how to use with JavaScript.

API endpoints

Endpoints are available to help manage the cart system in the frontend. You can make requests to these to add, update and remove items, get the cart contents or its snippet.

All successful responses will have the following structure:

In case of error:

GET /api/cart

Get cart contents.

POST /api/cart/items

Adds item to the cart.

PATCH /api/cart/items/:key

Updates item in the cart.

DELETE /api/cart/items/:key

Removes item from the cart.

GET /api/cart/snippet

Get cart snippet.

Response:

Translations

Currently, this plugin is only available in English and Portuguese (Portugal).

If you want to add a new translation, check the Options section.

If you want to contribute with a translation (to be bundled with the plugin), go to the translations directory and create a new YAML file named with the locale that you wish to translate. For example, if you want to add the German translation, create a de.yml file.

It will be very appreciated if you can contribute by making a pull request with the translation you wish to add.

Setup

Below are the steps required to set up a Stripe Checkout online shop, both in hosted and embedded mode.

[!TIP] It is recommended that you use a library that enables environment variables to store your project credentials in a separate place from your code and to have separate development and production access keys.

Considering that you already have a Stripe account:

Step 1.

Grab your public and secret keys from the Stripe Dashboard and add them to the stripeSecretKey options.

[!IMPORTANT] Make sure to grab the test keys when in development mode, and only use the production keys when the website is live.

Step 2.

Create a webhook to listen to Stripe Checkout events.

When creating a webhook in the Stripe Dashboard (should be in the Developers page), make sure to select the following Checkout events; otherwise it will not work correctly:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed

The endpoint URL must be set to the following: https://yourdomain.com/stripe/checkout/webhook. This is, your base URL followed by /stripe/checkout/webhook.

When the webhook is created, grab its secret key and add it to the stripeWebhookSecret option.

[!IMPORTANT] The webhook will not work properly when developing locally, since the request cannot reach a local endpoint that only exists on your computer. Check the Development section for more information on how to work with webhooks in development.

Step 3.

For the panel, you need to create a orders and a order blueprint. You can change the orders name with the ordersPage option.

[!NOTE] Remember to create a orders directory at /content with a orders.txt file. Otherwise, the page will not be found.

Step 4 (optional).

Similar to the previous step, create a checkout-settings blueprint. You can change the checkout-settings name with the settingsPage option.

Currently, the only existing settings are to manage shipping data, like allowed countries and shipping rates. If you don't need this information for your website (for example, if you are selling digital assets, where shipping information is not needed), you can skip this step.

Step 5.

You can create a product blueprint with any name.

Make sure that you have a price field (it is required). To add an image, add a thumbnail field (it is optional).

The plugin already comes with both blueprints fields, in case you want to use them:

hosted versus embedded mode

Depending on the mode you are using, jump to the respective step below:

• Step 6: hosted mode
• Step 6: embedded mode

For more information about the difference between both modes, check the uiMode option.

Step 6: hosted mode.

When in hosted mode, you need to add a link to the website with the URL generated by the following method stripeCheckout()->checkoutUrl().

This link usually exists in the cart component or when reviewing the order before proceeding to the checkout.

Something like:

Make sure to have at least one item added to the cart (check the Cart section) or it will throw an error.

It is also required to set the cancelPage options.

Step 6: embedded mode.

When in embedded mode, you need to use the Stripe.js library as well as the following method stripeCheckout()->checkoutEmbeddedUrl().

You have to create your own checkout page.

Something like:

Make sure to have at least one item added to the cart (check the Cart section) or it will throw an error.

It is also required to set the returnPage option.

Development

Webhook

Listen to events

Stripe webhooks will not work properly when developing locally, since the request cannot reach a local endpoint that only exists on your computer.

To solve this, Stripe has a CLI that you can install on your computer. Follow the instructions in their Stripe CLI documentation page before proceeding.

To forward the events to a local endpoint, use the following command (you can also check their documentation for more information):

This command will forward the events checkout.session.completed, checkout.session.async_payment_succeeded and checkout.session.async_payment_failed to the https://yourlocaldomain.com/stripe/checkout/webhook endpoint.

The endpoint must always be your local base URL followed by /stripe/checkout/webhook.

After running the command, it will show you the webhook secret. Add this secret to the stripeWebhookSecret option.

Now, if you submit the Stripe Checkout form (in hosted or embedded mode), it will be able to listen to the events.

Trigger events

If you want to trigger the events without the need to submit the form every time, you can use the following command (make sure to open another terminal window, do not close the window where you ran the listen command):

This command will trigger the checkout.session.async_payment_succeeded event (you can trigger any event). Make sure to always include the --add checkout_session:metadata.order_id=xxxxxx.

This is required because the plugin needs to share the Kirby order id across all events (to be in sync). You can set any order_id value, as long as it is alphanumeric.

Production

Make sure to change the stripeSecretKey and stripeWebhookSecret options for their respective live values.

[!TIP] It is recommended that you use a library that enables environment variables to store your project credentials in a separate place from your code and to have separate development and production access keys.

Contributing

Any form of contribution to improve this library (including requests) will be welcome and appreciated. Make sure to open a pull request or issue.

License

This project is licensed under the MIT license. Please see the LICENSE file distributed with this source code for further information regarding copyright and licensing.