PunchOut Protocols Coverage

PunchOut flow protocols cXML and OCI contain a big range of features, which also consist of different functional elements, XML and form fields.

Find out below which parts are supported out of the box and plan extension of the missing ones on the project accordingly.

cXML Flow fields mapping

This section lists the cXML elements that the PunchOut Gateway interprets on the inbound PunchOutSetupRequest and emits on the outbound PunchOutSetupResponse and PunchOutOrderMessage. Elements that are not listed are not parsed by the default flow.

Received elements (buyer to Spryker)

The buyer’s eProcurement system posts a PunchOutSetupRequest cXML document to the fixed cXML setup endpoint /punchout-cxml-setup. The connection is identified by the Header/Sender/Credential/Identity matched against sender_identity. The raw XML body is parsed by DefaultCxmlContentParser into PunchoutCxmlSetupRequestTransfer.

cXML Header

cXML Payload

Ship-to address

When PunchOutSetupRequest/ShipTo/Address is present, the following are mapped to PunchoutAddressTransfer:

Item list (only when operation="edit")

For each ItemOut, a PunchoutItemTransfer is built:

Returned elements (Spryker to buyer)

The PunchOut Gateway emits two outbound cXML documents.

PunchOutSetupResponse — synchronous reply to PunchOutSetupRequest

Returned with HTTP 200 OK and Content-Type: text/xml. Built by CxmlResponseBuilder.

On authentication, validation, or processing errors a cXML Status document is returned instead, with a non-200 status code:

PunchOutOrderMessage — cart return to the buyer

Built by CxmlPunchoutOrderMessageMapper and POSTed to BrowserFormPost.URL from the original setup request when the buyer transfers the cart back.

Header:

Message payload:

For field-level changes, use the per-connection mapping described in Per-connection field mapping. For deeper changes, replace the parser or message-mapper services, or set a custom cXML processor plugin FQCN on the connection’s processor_plugin_class column. Processor plugins are loaded at runtime by class name; no dependency-provider registration is required. For details, see Project configuration for PunchOut Gateway.

Per-connection field mapping

Beyond the defaults above, you can remap any emitted field or property per connection without custom code. Each connection stores a mappings map of key to source expression, edited in the Back Office connection configuration (the cXML and OCI configuration forms). At cart-return time, FieldValueResolver evaluates each expression against the current quote and item.

The key identifies the target field by its full location in the outbound document, written as a dot-separated path (for cXML) or as the form field name (for OCI). You do not need to memorize these keys: the complete catalog of mappable keys is defined in code by PunchoutGatewayConfig::getSupportedCxmlFields() for cXML and PunchoutGatewayConfig::getSupportedOciFields() for OCI, and the same lists populate the field drop-downs in the Back Office configuration forms.

Resolution follows two rules:

• Required fields (those with a default in the tables above) fall back to the default when the field is unmapped, or the expression resolves to null.
• Optional fields are omitted entirely when unmapped or unresolved.

A source expression is one of the following:

• A property path in the form pluginKey.field. The item plugin reads from the current ItemTransfer and the quote plugin reads from the QuoteTransfer. For example, item.sku or quote.currency.code.
• A quoted literal, single- or double-quoted, emitted verbatim. For example, "EA".
• A concatenation of the above, joined with &. For example, item.sku & "-" & item.groupKey.
• An empty literal "", which forces an empty value.

The tables on this page list the fields that the default flow emits; any other key from the supported catalog is emitted only when you map it.

To extend or override the field set in code, replace the parser or message-mapper services, or set a custom cXML processor plugin FQCN on the connection’s processor_plugin_class column. Processor plugins are loaded at runtime by class name; no dependency-provider registration is required. For details, see Project configuration for PunchOut Gateway.

Extrinsic deny list

CxmlPunchoutOrderMessageMapper::filterExtrinsics() removes any extrinsic whose key matches PunchoutGatewayConfig::EXTRINSIC_DENY_LIST before echoing the remaining values back inside each PunchOutOrderMessageHeader. The deny list guards against leaking personally identifiable information that the buyer’s procurement system sent for customer resolution. The default list is:

User, UniqueUsername, UniqueName, UserId, UserEmail, UserFullName, UserPrintableName, FirstName, LastName, PhoneNumber, UserPhoneNumber.

OCI Flow fields mapping

This section lists the OCI form fields that the PunchOut Gateway interprets on the inbound login and emits on the outbound cart return. Any inbound fields that are not listed are preserved in PunchoutOciLoginRequestTransfer.formData for a potential project level customisation.

Received fields (buyer to Spryker)

The buyer’s eProcurement system posts an HTML form to the connection’s request_url. The default OCI flow reads the following fields:

Returned fields (Spryker to buyer)

When the Spryker Shop transfers the cart back, HTML form with a button Transfer Cart is rendered, whose action is the HOOK_URL received at login. ~TARGET rendered as the target attribute of the form.

The form contains following fields:

The sources in the table above are defaults. You can override the source of any listed NEW_ITEM-* field, or emit optional ones, per connection through Field mapping, without writing code.