Article Contents
PunchOut Setup Request (from ESM Solutions)
Sample cXML Transaction (from ESM Solutions)
PunchOut Setup Response (from Supplier System)
Sample cXML Transaction (from Supplier System)
Shopping Cart Response (from ESM Solutions)
Overview
The purpose of this article is to outline the processing flow, field definitions, and general information necessary to implement shopping cart PunchOut integrations between ESM Purchase and cart-enabled Supplier web sites.
The 'Integration Notes and Limitations; section provides important information on how and why functionality may be limited.
The 'PunchOut Flow' section describes the lifecycle PunchOut session across the two systems. The 'Transaction Data Element Definitions' section provides a list of supported XML fields, and the 'Sample XML Transactions' section illustrates example formats in which they might be used.
PunchOut Catalog Requirements
- The supplier must use a supported version of a major internet browser (Chrome, Edge, Firefox or Safari).
- The punchout web site must support multiple, concurrent users.
- The punchout catalog should not contain links to external sites that would break the punchout session and remove the user from the shopping experience.
- Any necessary link must open in a new window.
- The punchout catalog must not require any additional user login, selection of account, or require the user to provide a ShipTo address or payment information within the punchout itself.
- Once a shopping cart is returned to ESM, the cart will move through an approval process before a purchase order is generated.
- Once approved, the purchase order delivery to the supplier will specify the ShipTo address and payment information.
- The ShipTo, BillTo, First and Last Name, Telephone Number, and User Email are passed in the PunchOut Setup Request as well.
- The punchout site will be displayed within a frame session, and therefore should not contain any code that could prevent proper function within frames. Scripts or code that designates the supplier site as the parent/top windows, or code that would otherwise force break frame session must be removed.
- Should the punch-out require cookies, the cookie must be unique and separate from those being used on the supplier’s eCommerce site. Separate cookies ensure that user activity between the two sites is not inadvertently affected by the other.
- The punchout site must be P3P compliant before promotion to production can be considered. Please see the P3P Compliance section for more detailed information.
- The initial post URL and the redirect URL contained within the tag set of the PunchOutSetupResponse message must be https (port 443).
PunchOut Flow
Diagram
Process Steps
- The user selects the PunchOut Supplier in ESM Purchase and clicks Submit.
- The ESM Solutions server does a synchronous web post to the Supplier's site, supplying XML containing required fields.
- The Supplier's site validates credentials, saves the shopping-cart-import URL, and responds synchronously to the web post, supplying the shopping cart entry URL.
- The ESM Purchase system redirects the client (via a new browser window) to the Supplier's URL.
- The user builds a shopping cart within the Supplier's site and selects the completion ("check out") option.
- The Supplier's system posts the cart XML (synchronously) to the ESM Solutions shopping-cart-import URL (from step 3 above).
- The ESM Solutions server processes the cart XML, creating or appending to an ESM Purchase requisition for the user.
- The ESM Solutions server responds synchronously to the web post with success or failure.
- The Supplier's site displays an appropriate message to the user.
- The user returns to the ESM Purchase site, where their requisition can be viewed, modified, deleted, or submitted for approval and purchase order creation.
Notes and Limitations
- ESM Solutions supports standard cXML.
- ESM Solutions has the capability to accept non-cXML compliant XML by developing internal style sheets.
- The Transaction Data Element Definitions section contains the definitions of each field in the transactions.
- Within ESM Purchase, users are allowed to aggregate requisitions (carts) across purchase orders. This means that a single requisition may be split up, and its line items may finally appear on several different purchase orders (along with line items from several different requisitions).
- The ESM Solutions integration technology allows the user to append shopping cart items to existing requisitions.
- Users may combine products from multiple Suppliers on a single requisition. For this reason, no Supplier or interface-specific data will be supported at the shopping cart header-level.
- Because of the aggregation mentioned above, the integration process cannot accommodate Tax or Freight values on a shopping cart.
- ESM Solutions does not accept a shopping cart with more than 99 unique line items.
- This interface does not support "Modification" PunchOut transactions. Users in ESM Purchase can modify requested quantities and delete requisition line items within ESM Purchase.
- Users in ESM Purchase have the capability to override prices on requisition items, but the Supplier may choose to ignore price values on purchase orders if they are incorrect.
- For the sake of generic version support and minimization of network "chatter," it is strongly recommended that XML-processing URLs do not perform any client redirects.
- Shopping carts must be posted to the ESM Solutions web server either by a server-to-server post of streamed XML data (XML Interchange standard), or by a customer-side form post with the XML data in the "cXML-URL encoded" form-level element (cXML standard).
- ESM Solutions requires KTTPS (128-bit encryption) support for all cross-system web posts.
PunchOut Setup Request (from ESM Solutions)
| Element Name | Data Definition | Description |
| cXML PayloadID | Text (255) | Unique identifier per request generated by ESM Solutions. |
|
/Header/From/Credential @domain="NetworkID" /Identity |
Text (15) | Supplier's identifier for the customer. This is unique per customer not user in the customer. Each request from the same customer will have the same identifier even when the user is different. |
|
/Header/To/Credential @domain="NetworkID" /Identity |
Text (15) | Supplier's Identifier |
|
/Header/Sender/Credential @domain="DUNS" /Identity |
Text (15) | ESM Solutions’ identifier |
| /Header/Sender/Credential/SharedSecret | Text (20) | ESM Solutions Supplier Shared Secret |
| /Header/Sender/UserAgent | Text (16) | ESM Solutions User Agent |
| /Request/PunchOutSetupRequest/BuyerCookie | Text (36) |
Unique cookie string required to be provided back to ESM on PunchOutOrderMessage PunchOutOrderMessage |
| /Request/PunchOutSetupRequest/BrowserFormPost/URL | Text (1000) | WWW Address for the ESM Cart Processor. This is the URL that the supplier’s cart must be posted to when the user checkout out of the supplier’s site. |
| /Request/PunchOutSetupRequest/Contact/Name | Text (51) | Requestor’s First Name, Last Name in ESM Solutions. |
| /Request/PunchOutSetupRequest/ Contact/Email | Text (60) | Requestor’s Email Address in ESM Solutions. |
| /Request/PunchOutSetupRequest/Contact/Phone | Text (50) | Requestor’s Phone Number in ESM Solutions. |
| /Request/PunchOutSetupRequest/SupplierSetup/URL | Text (1000) | ESM Solutions posts the PunchOut setup request to this URL. It is provided by the supplier during initial setup. |
| /Request/PunchOutSetupRequest/ShipTo/Address @addressID | Text (50) | Unique Code identifier for a customer location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/Name | Text (50) | Then name of the location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/DeliverTo | Text (72) | The full name of the contact at the location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/Street | Text (50) | The street address for the location. A location can have up to three street segments. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/City | Text (50) | The city name for the location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/State | Text (10) | The state abbreviation for the location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/PostalCode | Text (10) | The postal code for the location. |
| /Request/PunchOutSetupRequest/ShipTo/Address/PostalAddress/Country @ isoCountryCode | Text (50) | The country for the location. |
Sample cXML Transaction (from ESM Solutions)
PunchOut Setup Request
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.1.010/cXML.dtd">
<cXML xml:lang="en-US" timestamp="2015-12-10T11:22:30" payloadID="daf2845e-db5a-4582-b3d2-0ffcaca2e684">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>[Supplier Identifier for Customer]</Identity>
</Credential>
</From>
<To />
<Credential domain="NetworkId">
<Identity>[Supplier Identifier]</Identity>
</Credential>
<Sender>
<Credential domain="DUNS">
<Identity>132443859</Identity>
<SharedSecret>[ESM Solutions/Supplier Password]</SharedSecret>
</Credential>
<UserAgent>ESMPunchOut v1.0</UserAgent>
</Sender>
</Header>
<Request deploymentMode="production">
<PunchOutSetupRequest operation="create">
<BuyerCookie>d5a73049-75c1-41f5-a846-eaad5e466f5c</BuyerCookie>
<BrowserFormPost>
<URL>https://eprocurement.esmsolutions.com/Punchout/CreatePunchoutShoppingCart</URL>
</BrowserFormPost>
<Contact role="endUser">
<Name xml:lang="en-US">Greg Lucas</Name>
<Email>glucas@esmsolutions.com</Email>
<Phone>123456576</Phone>
</Contact>
<SupplierSetup>
<URL>https://emarketplace.airgas.com/invoke/wm.b2b.cxml/receiveCXML</URL>
</SupplierSetup>
<ShipTo>
<Address addressID="MSTC002">
<Name xml:lang="en-US">WTCS Location Test</Name>
<PostalAddress>
<DeliverTo />
<Street>Wisconsin test</Street>
<Street />
<City>Campus Location</City>
<State>Wisconsin</State>
<PostalCode>54481</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
</Address>
</ShipTo>
</PunchOutSetupRequest>
</Request>
</cXML>
PunchOut Setup Response (from Supplier System)
| Element Name | Data Definition | Description |
| /Response/Status @code | Text (10) | Code indicating success or failure A "200" is a success. |
| /Response/Status @text | Text (5000) | Error text for failures. |
| /Response/PunchOutSetupResponse/StartPage/URL | Text (1000) | The URL that the supplier wishes the user to be presented for their shopping and cart checkout. It usually includes a unique identifier in the query string to identify the current request. Many suppliers use a session ID for this purpose. |
Sample cXML Transaction (from Supplier System)
PunchOut Setup Response
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.006/cXML.dtd">
<cXML version="1.1" payloadID="2010-05-26T01:33:16-fishersci.com" xml:lang="en-US" timestamp="2010-05-26T01:33:16">
<Response>
<Status code="200" text="Success" />
<PunchOutSetupResponse>
<StartPage>
<URL>https://VendorWebSite.com/Punchout.aspx?sessionID=I5N5uQMbjf%2FKPZIYpiXxdLt31x 2B6J4VBH21HzjhUtQ%3D</URL>
</StartPage>
</PunchOutSetupResponse>
</Response>
</cXML>
PunchOut Order Message Request (from Supplier System)
| Element Name | Data Definition | Description |
| cXML @payloadID | Text (255) | Unique identifier per request generated by Supplier. Optional |
| /Header/From/Credential/Identity | Text (15) | Supplier's Customer Identifier. |
| /Header/To/Credential/Identity | Text (15) | ESM Solutions identifier. |
| /Header/Sender/Credential/Identity | Text (15) | Supplier's Identifier. |
| /Header/Sender/Credential/SharedSecret | Text (20) | ESM Solutions Supplier Shared Secret. |
| /Header/Sender/UserAgent | Text (50) | Supplier's User Agent. |
| Message/PunchOutOrderMessage/BuyerCockie | Text (36) | BuyerCookie provided in PunchOutSetupRequest message. |
| Message/PunchOutOrderMessage/PunchOutOrderMessageHeader/Total | Money | Total of all Items present in Cart. |
| Message/PunchOutOrderMessage/ItemIn @Quantity | Integer | Quantity of item requested. One per item in cart. Required. |
| Message/PunchOutOrderMessage/ItemIn/ItemID/SupplierPartID | Text (20) | Supplier Part Number. One per item in cart. Required |
| Message/PunchOutOrderMessage/Itemln/ItemID/SupplierPartAuxilaryID | Text (20) | Supplier's Additional Part Number Data (one per item in cart). This value is stored in the ESM Solutions system but not displayed to the end user. It will be included on any purchase order released through the ESM Solutions system to the supplier via XML. Optional. |
| Message/PunchOutOrderMessage/ItemIn/ItemDetail/Description | Text (500) | Product's long Description. One per item in cart. Required |
| Message/PunchOutOrderMessage/Itemin/ItemDetail/ManufacturerName | Text (50) | Manufacturer Name. One per item in cart. |
| Message/PunchOutOrderMessage/Itemln/ItemDetail/ManufacturerPartID | Text (30) | Manufacturer Part Number. One per item in cart. |
| Message/PunchOutOrderMessage/ItemIn/ItemDetail/UnitOfMeasure | Text (20) | Unit-of-Measure One per item in cart. |
| Message/PunchOutOrderMessage/ItemIn/ItemDetail/UnitPrice/Money | Money | Price per quantity (one per item in cart). Required |
| Message/PunchOutOrderMessage/Itemln/ItemDetail/URL | Text (5000) | The URL for the image of the item. This URL will be viewed by users in the ESM Solutions system. |
| Message/PunchOutOrderMessage/ItemIn/ItemDetail/Classification | Text (50) | Item classification code used for accounting and reporting One per Item in Cart. |
Sample cXML Transaction (from Supplier System)
PunchOut Order Message
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.1.007/cXML.dtd">
<cXML version="1.1" payloadID="7FE59AA9-582C-401D-B743-CFD69A53BDA6" timestamp="1118423577901" xml:lang="en-US">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>[Supplier Identifier for Customer]</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkId">
<Identity>[Supplier Identifier]</Identity>
</Credential>
</To>
<Credential domain="NetworkId">
<Identity>[Supplier Identifier]</Identity>
</Credential>
<Sender>
<Credential domain="DUNS">
<Identity>132443859</Identity>
<SharedSecret>[ESM Solutions/Supplier Password]</SharedSecret>
</Credential>
<UserAgent>SupplierUserAgent V1.2</UserAgent>
</Sender>
</Header>
<Message>
<PunchOutOrderMessage>
<BuyerCookie>d5a73049-75c1-41f5-a846-eaad5e466f5c</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="create">
<Total>
<Money currency="USD">109.44</Money>
</Total>
</PunchOutOrderMessageHeader>
<ItemIn Quantity ="1">
<ItemID>
<SupplierPartID>EI-8895</SupplierPartID>
<SupplierPartAuxiliaryID>EI-8895</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">109.44</Money>
</UnitPrice>
<Description xml:lang="en">TALKING GLOBE-8895</Description>
<UnitOfMeasure>each</UnitOfMeasure>
<Classification domain="UNSPSC">41440000</Classification>
<ManufacturerPartID>EI-8895</ManufacturerPartID>
<ManufacturerName xml:lang="en">EDUCATIONAL INSIGHTS</ManufacturerName>
<URL>https://VendorWebSite.com/image0303.jpg</URL>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>
Shopping Cart Response (from ESM Solutions)
ESM Solutions supports two shopping cart response methods: a standard cXML response from Server-to Server cart requests or and HTML response for Customer-to-Server cart requests.
The second method provides an option to Include Javascript to automatically close the shopping window on a successful cart import. The supplier must choose one of these methods before the beginning of development.
Standard cXML Response for Server-to-Server Requests
| Element Name | Data Definition | Description |
| /Response @code | Text (10) | Response code |
| /Response @text | Text (5000) | Response text message |
Standard cXML Shopping Cart Response
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="{4E9577C8-C2EE-4605-A0E8-3600C27BC4F3}" timestamp="2010-05-07T10:59:53- 05:00" version="1.1.001">
<Response>
<Status code="200" text="" xml:lang="en-US" />
</Response>
<Message>You order has been processed </Message>
</cXML>
HTML/Javascript Response for Customer-to-Server Requests
<html>
<head></head>
<body onload="javascript:close()" bgcolor="#ffffff" text="#000000" topmargin="0">
<table width="100%" height="100%">
<tr valign="center">
<td align="center">
<table>
<tr height="24">
<td align="center">
<font face="Arial" size="2">
Your shopping cart has been successfully imported into ESM Purchase Marketplace.
</font>
</td>
</tr>
<tr height="24">
<td align="center">
<font face="Arial" size="2">
You may now close this window.
</font>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>
Configuration Requirements
To begin development, the following credentials will need to be provided by the Supplier:
- Test Customer ID
- Share Secret
- PunchOut Setup Request URL (Test Site)
- Any additional (intrinsic) data required to be passed on to the Shopping Cart Request
- Selection of a Shopping Cart Response Method
Reference
cXML specification details can be accessed here: https://cxml.org/
Comments
Please sign in to leave a comment.