Project configuration for PunchOut Gateway

This document describes the project configuration to enable eProcurement systems support via PunchOut flow.

PunchOut connection configuration

Configure connections through the Back Office UI. For details, see Manage PunchOut connections.

To bootstrap a working configuration for local development, the module also provides two demo console commands. Each command creates a single, hardcoded connection for store DE. Do not use the demo data in production.

• OCI flow:

vendor/bin/console punchout-gateway:oci:demo-connection:create

• cXML flow:

vendor/bin/console punchout-gateway:cxml:demo-connection:create

The rest of this section describes the persisted shape of a connection. The same fields are exposed in the Back Office form.

To configure a connection manually, create a row in the spy_punchout_connection table:

OCI connection configuration

OCI-specific configuration

The triplet protocol_type, fk_store and request_url must be unique.

Column configuration contains JSON with the following optional keys. Override only when the value differs from the default.

Additionally, configure credentials for customers who will access the shop. To do this, create rows in the spy_punchout_credential table:

Customers used for an OCI connection are expected to be fully configured in the shop so that only permitted products and prices are accessible.

cXML connection configuration

cXML-specific configuration columns:

The sender_identity column value must be globally unique—each cXML system maps to exactly one connection. The sender identity is stored as a top-level column on spy_punchout_connection, not inside the JSON configuration blob.

Column configuration contains JSON with the following keys:

For a cXML connection, no additional PunchOut-related configuration is required. The logged-in customer is identified by the UserEmail extrinsic field. Customers used for a cXML connection are expected to be fully configured in the shop so that only permitted products and prices are accessible.

PunchOut flow processor plugin

Each PunchOut connection resolves its processor plugin at runtime using the fully qualified class name stored in spy_punchout_connection.processor_plugin_class. The plugin must implement one of the following interfaces:

• for OCI flow - \SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutProcessorPluginInterface
• for cXML flow - \SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutCxmlProcessorPluginInterface.

This module provides default functionality:

• \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultCxmlProcessorPlugin - for cXML flow,
• \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin - for OCI flow.

No dependency injection registration is required. The plugin is loaded at runtime.

Creation of a custom plugin

Place the plugin in your project’s Zed communication layer, for example:

src/Pyz/Zed/ProjectPunchoutGateway/Communication/Plugin/PunchoutGateway/CustomOciProcessorPlugin.php

The simplest approach is to extend the default OCI plugin and override only the methods you need:

namespace Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway;

use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin;

class CustomOciProcessorPlugin extends DefaultOciProcessorPlugin
{
    // Override only the methods you need to customize.
}

Set spy_punchout_connection.processor_plugin_class on the connection that uses this plugin to \Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway\CustomOciProcessorPlugin.

Global plugin methods

cXML-specific plugin methods

Form handler plugin

Projects extend or replace the storefront “Transfer Cart” form via plugins implementing \SprykerEco\Yves\PunchoutGateway\Plugin\Form\PunchoutFormHandlerPluginInterface. At render time, PunchoutFormDataBuilder::build() iterates the registered handlers in order and returns the result of the first whose isApplicable() returns true.

The module ships two defaults, both registered in \SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider::getPunchoutFormHandlerPlugins():

• \SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultCxmlPunchoutFormHandlerPlugin — for cXML sessions.
• \SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultOciPunchoutFormHandlerPlugin — for OCI sessions.

Plugin methods

Register a custom handler

Place the plugin in your project’s Yves layer, for example:

src/Pyz/Yves/ProjectPunchoutGateway/Plugin/Form/CustomCxmlPunchoutFormHandlerPlugin.php

Then register it before the defaults so it takes precedence for the same protocol:

src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php

namespace Pyz\Yves\PunchoutGateway;

use Pyz\Yves\ProjectPunchoutGateway\Plugin\Form\CustomCxmlPunchoutFormHandlerPlugin;
use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider;

class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider
{
    protected function getPunchoutFormHandlerPlugins(): array
    {
        return [
            new CustomCxmlPunchoutFormHandlerPlugin(),
            ...parent::getPunchoutFormHandlerPlugins(),
        ];
    }
}

Punchout-specific security header expander plugin

At PunchOut session start, Yves applies protocol-specific Content-Security-Policy (CSP) directives to allow the Storefront to be embedded and to post back to the buyer’s procurement system.

Directive generation is delegated to plugins implementing \SprykerEco\Yves\PunchoutGateway\Dependency\Plugin\PunchoutSecurityHeaderExpanderPluginInterface. PunchoutSecurityHeaderSessionWriter walks the registered plugins and accumulates their directives for the active session once, persisting the value into the session.

When spy_punchout_connection.allow_iframe is true, the correct CSP headers are included in each response.

By default, we provide an OCI-specific plugin only:

• \SprykerEco\Yves\PunchoutGateway\Plugin\SecurityHeader\DefaultOciSecurityHeaderExpanderPlugin — adds frame-ancestors to the CSP for OCI sessions when the OCI login carries a ~TARGET form field.

Plugin method

Register a custom expander

In case your system requires additional Punchout-specific security headers, add your plugin to the Yves dependency provider.

src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php

namespace Pyz\Yves\PunchoutGateway;

use Pyz\Yves\ProjectPunchoutGateway\Plugin\SecurityHeader\CustomCxmlSecurityHeaderExpanderPlugin;
use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider;

class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider
{
    protected function getPunchoutSecurityHeaderExpanderPlugins(): array
    {
        return [
            ...parent::getPunchoutSecurityHeaderExpanderPlugins(),
            new CustomCxmlSecurityHeaderExpanderPlugin(),
        ];
    }
}

Session-in-quote expander plugin

PunchoutQuoteExpander (Zed) loads the PunchOut session that belongs to the current quote and runs it through every registered \SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutSessionInQuoteExpanderPluginInterface before stamping it on the QuoteTransfer. Use this extension point to enrich or override PunchOut session fields based on the quote (for example, to copy a project-specific field onto the session before it is persisted with the cart).

Plugin methods

Default implementations

This section describes the behavior of the two shipped default processor plugins and the storefront “Transfer Cart” widget for each lifecycle step. Use it to understand what you get out-of-the-box and to identify which plugin method to override when customising.

Shared behavior

Both DefaultOciProcessorPlugin and DefaultCxmlProcessorPlugin rely on QuoteCreator to stamp the following fields on every new quote:

• Store — resolved from spy_punchout_connection.fk_store.
• Currency — set to the default currency of the resolved store.

OCI

Customer identification

OciCustomerResolver looks up the customer by the idCustomer that is already on the connection transfer. That value is stamped during authentication: PunchoutOciAuthenticator matches the username and password from the OCI form fields against spy_punchout_credential and, on success, writes connection.idCustomer. The buyer identity therefore comes entirely from the credential record — nothing from the buyer’s login payload is used. Override resolveCustomer on the processor plugin to source the customer differently (for example, from a custom form field).

Quote identification

OciPunchoutQuoteFinder always returns a fresh empty QuoteTransfer with DEFAULT_QUOTE_NAME. There is no session-to-quote lookup on OCI login; every login starts a new cart. Store and currency are set by QuoteCreator as described in the shared behavior section above. Override resolveQuote to reuse a per-customer cart across sessions.

Quote fill with items

OCI login does not carry item data. DefaultOciProcessorPlugin::expandQuote is a pass-through and leaves the quote empty. Items are transferred back to the buyer’s procurement system via the storefront form POST (see “Transfer Cart button” below), not populated during login.

Transfer Cart button

DefaultOciPunchoutFormHandlerPlugin (registered in \SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider) makes the button visible when the current quote has a PunchOut session whose punchoutData.ociLoginRequest is not null. When applicable, the action URL is taken from the HOOK_URL form field of the OCI login request (validated to start with https:// at session creation time). The hidden form fields are OCI-flat NEW_ITEM-… key/value pairs produced by OciFormFieldBuilder. The button is not rendered when no punchout session exists on the quote, when the session was created by a cXML login, or when no handler plugin is registered for the Yves factory.

cXML

Customer identification

CxmlCustomerResolver reads the Extrinsic[name="UserEmail"] field from the parsed PunchOutSetupRequest and resolves the customer via CustomerFacade::getCustomer by email. Connection authentication is a separate step that runs first: PunchoutCxmlAuthenticator verifies the senderSharedSecret from the cXML header against the connection record using password_verify. If the UserEmail extrinsic is absent or empty, resolveCustomer returns null and the session is rejected. Override resolveCustomer to read identity from a different extrinsic or from a custom header field.

Quote identification

CxmlPunchoutQuoteFinder uses BuyerCookie from the PunchOutSetupRequest to look up an existing PunchOut session via PunchoutGatewayRepository::findPunchoutSessionByBuyerCookie. When a session is found, the linked quote is reused — allowing the buyer to resume an in-progress cart. If the found quote belongs to a different store than the current connection’s idStore, the old quote is deleted and a new empty one is created. When BuyerCookie is missing or no session matches, a new DEFAULT_QUOTE_NAME quote is returned. Store and currency are then set by QuoteCreator. Override resolveQuote to change cookie-matching rules or to support cross-store quote reuse. Quote is always presented as an empty one for a customer after session start.

Transfer Cart button

DefaultCxmlPunchoutFormHandlerPlugin makes the button visible when the current quote has a PunchOut session whose punchoutData.cxmlSetupRequest is not null. The action URL is punchoutSession.browserFormPostUrl, captured from the original PunchOutSetupRequest.BrowserFormPost.URL at login time. A single hidden field (CXML_FORM_FIELD_NAME) carries the PunchOutOrderMessage built by PunchoutGatewayService::buildCxmlPunchoutOrderMessage. The button is not rendered when no punchout session exists, when the session was created by an OCI login, or when no handler plugin is registered.

Widget visibility summary

PunchoutCartWidget is always instantiated on pages where it is embedded. Actual form visibility is determined by PunchoutFormDataBuilder::build(), which calls plugins of interface PunchoutFormHandlerPluginInterface and returns the result of the first whose isApplicable() returns true. The Twig template renders the <form> and submit button only when formData is not null and formData.actionUrl is not empty. If you register a custom handler plugin, place it before the default plugins in the dependency provider so it takes precedence for the same protocol.

For OCI flow, the button is rendered for the empty cart as well to allow empty-order return to the eProcurement platform.

For cXML flow, no button is rendered for the empty cart. This behavior will be improved in the next version.

PunchOut endpoints

PunchoutGatewayRouteProviderPlugin (Yves) registers five routes consumed by the buyer’s eProcurement system and by the buyer’s browser:

The slug accepted in OCI routes matches [a-zA-Z0-9_-]+.

cXML session start lifecycle

The cXML flow is a two-step handshake:

1. The buyer’s procurement system POSTs a PunchOutSetupRequest to a cXML setup route. The shop authenticates the request, resolves the customer and quote, persists a spy_punchout_session row, and replies synchronously with a PunchOutSetupResponse whose StartPage/URL contains a one-shot session token: https://<shop-domain>/punchout-cxml-start?session=<token>.
2. The buyer’s browser follows that URL. CxmlController::startAction reads the token from the session query parameter, looks up the session, logs the customer in via LoginModel::loginCustomerFromSession, stores the protocol-specific Content Security Policy fragment via PunchoutSecurityHeaderSessionWriter, and redirects to the shop.

Two settings control this handshake:

Both are exposed in the Back Office settings panel under Configuration > Punchout Gateway.

spy_punchout_session table

The session table is created by propel:install (see Set up the database schema). It links one PunchOut login attempt to the resulting cart: