Integrate PunchOut Gateway

This document describes how to integrate the PunchOut Gateway module into a Spryker shop.

1. Install the module

Install the PunchOut Gateway module using Composer:

composer require spryker-eco/punchout-gateway:^0.4.0

2. Configure the module

To control logging through the AWS Parameter Store, add the following optional configuration:

config/Shared/config_default.php

use SprykerEco\Shared\PunchoutGateway\PunchoutGatewayConstants;

$config[PunchoutGatewayConstants::ENABLE_LOGGING] = getenv('PUNCHOUT_GATEWAY_ENABLE_LOGGING') ?: false;

Configuration constants

Logging

When logging is enabled, the module emits structured entries through \SprykerEco\Shared\PunchoutGateway\Logger\PunchoutLoggerInterface. The shipped implementation PunchoutLogger writes to the standard Spryker log channels and covers, among others, request reception and parsing, authentication attempts and outcomes, response generation, quote and session creation, and uncaught throwables. When logging is disabled, the resolver returns NullPunchoutLogger and all calls become no-ops.

3. Additional module configuration

src/Pyz/Zed/PunchoutGateway/PunchoutGatewayConfig.php provides the following configuration methods:

The same values can be changed at runtime through the Back Office under Configuration > Punchout Gateway.

4. Update Quote configuration

Update QuoteConfig to allow the PunchOut session field to be saved with the quote.

src/Pyz/Zed/Quote/QuoteConfig.php

use Generated\Shared\Transfer\QuoteTransfer;

public function getQuoteFieldsAllowedForSaving(): array
{
    return array_merge(parent::getQuoteFieldsAllowedForSaving(), [
        // ...
        QuoteTransfer::PUNCHOUT_SESSION,
    ]);
}

5. Set up the database schema

Install the database schema:

vendor/bin/console propel:install

This creates the following tables:

6. Generate transfer objects

Generate transfer objects for the module:

vendor/bin/console transfer:generate

7. Register plugins

Register the Quote expander plugin

Add the PunchOut session expander plugin:

src/Pyz/Zed/Quote/QuoteDependencyProvider.php

use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\Quote\PunchoutSessionQuoteExpanderPlugin;

protected function getQuoteExpanderPlugins(): array
{
    return [
        // ...
        new PunchoutSessionQuoteExpanderPlugin(),
    ];
}

Register the route provider plugin

Add the route provider plugin:

src/Pyz/Yves/Router/RouterDependencyProvider.php

use SprykerEco\Yves\PunchoutGateway\Plugin\Router\PunchoutGatewayRouteProviderPlugin;

protected function getRouteProvider(): array
{
    return [
        // ...
        new PunchoutGatewayRouteProviderPlugin(),
    ];
}

Register the security header expander plugin

Add the security header expander plugin:

src/Pyz/Yves/Application/ApplicationDependencyProvider.php

use SprykerEco\Yves\PunchoutGateway\Plugin\Application\PunchoutSecurityHeaderExpanderPlugin;

protected function getSecurityHeaderExpanderPlugins(): array
{
    return [
        // ...
        new PunchoutSecurityHeaderExpanderPlugin(),
    ];
}

Support iframe embedding

If your eProcurement system requires embedding into an iframe, you must also adjust this variable in the deploy file for your environments:

image:
  environment:
    SPRYKER_YVES_SESSION_COOKIE_SAMESITE: 'none'

8. Register the cart widget

Add the PunchOut cart widget:

src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php

use SprykerEco\Yves\PunchoutGateway\Widget\PunchoutCartWidget;

protected function getGlobalWidgets(): array
{
    return [
        // ...
        PunchoutCartWidget::class,
    ];
}

The widget is rendered wherever it is embedded by the cart template. If your project uses the stock spryker-shop/cart-page template, embed it inside SprykerShop/Yves/CartPage/Theme/default/templates/page-layout-cart/page-layout-cart.twig (or your override) so that the “Transfer Cart” button is shown on the cart page.

The following example shows PunchoutCartWidget usage:

{% widget 'PunchoutCartWidget' args [data.cart] only %}{% endwidget %}

9. Import glossary data

The module provides glossary translations used by the PunchOut flow.

Option 1: Import using the module’s configuration file

vendor/bin/console data:import --config=vendor/spryker-eco/punchout-gateway/data/import/punchout-gateway.yml

Option 2: Copy file content and import individually

Copy content from vendor/spryker-eco/punchout-gateway/data/import/*.csv to the corresponding files in data/import/common/common/. Then run:

vendor/bin/console data:import glossary

10. Translations for the Back Office

The module ships Zed translations for the Back Office UI in vendor/spryker-eco/punchout-gateway/data/translation/Zed/en_US.csv and de_DE.csv. They are picked up by the standard Zed translator on the next request—no separate import step is required. To override a label, add an entry with the same key to your project’s Zed translation file.

Verify the integration

After completing the steps above:

• Open Punchout Connections in the Back Office. The grid should render empty until you create your first connection.
• Run vendor/bin/console punchout-gateway:cxml:demo-connection:create to insert a demo cXML connection for store DE and confirm that DB table spy_punchout_connection and the grid both reflect it.
• Run vendor/bin/console punchout-gateway:oci:demo-connection:create to insert a demo OCI connection for store DE and confirm that DB table spy_punchout_connection and the grid both reflect it.

Additional links

• Manage PunchOut connections — Back Office workflow for connections and credentials.
• Project configuration for PunchOut Gateway — connection columns, processor and form-handler plugins, endpoints.
• PunchOut Protocols Coverage — cXML and OCI field-by-field mapping.