Checkout Gateway

Context

As of Shopware version 6.6.3.0, the Checkout Gateway was introduced.

The Checkout Gateway aims to allow a streamlined implementation for making informed decisions during the checkout process, based on both the cart contents and the current sales channel context. In particular, the app system benefits from this solution, enabling seamless communication and decision-making on the app server during the checkout.

While this documentation focuses on the app integration of the Checkout Gateway, the design is intended to allow a custom replacement solution via the plugin system."

Prerequisites

You should be familiar with the concept of Apps, their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server.

App base guide

Your app server must be also accessible for the Shopware server. You can use a tunneling service like ngrok for development.

Manifest configuration

To indicate to Shopware that your app uses the checkout gateway, you must provide a checkout property inside a gateways parent property of your app's manifest.xml.

Below, you can see an example definition of a working checkout gateway configuration.

manifest.xml

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <checkout>https://my-app.server.com/checkout/gateway</checkout>
    </gateways>
</manifest>

After successful installation of your app, the checkout gateway will already be used during checkout.

Checkout gateway endpoint

During checkout, Shopware checks for any active checkout gateways and will call the checkout url. The app server will receive the current SalesChannelContext, Cart, and available payment and shipping methods as part of the payload.

WARNING

Connection timeouts

The Shopware shop will wait for a response for 5 seconds. Be sure, that your checkout gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection.

Your app server can then respond with a list of commands to manipulate the cart, payment methods, shipping methods, or add cart errors.

You can find a reference of all currently available commands here.

Let's assume for this example, that your payment method is not available for carts with a total price above 1000€.

Event

Plugins can listen to the Shopware\Core\Checkout\Gateway\Command\Event\CheckoutGatewayCommandsCollectedEvent. This event is dispatched after the Checkout Gateway has collected all commands from all app servers. It allows plugins to manipulate the commands before they are executed, based on the same payload the app servers retrieved.