Overview

Punchout (Roundtrip) functionality allows suppliers to maintain branded content on their own web site and provide buyers with the ability to automatically login by clicking a link within Unimarket. During the login process Unimarket passes the supplier site credentials which authenticate the buyer and allow the supplier to display buyer / account specific items and pricing.

After products are selected by the buyer, the Punchout service sends the required item details back into Unimarket for purchasing. At this point, the order is routed through the normal requisition and approval processes and eventually converted into a purchase order that is sent back to the supplier for order fulfillment.

Unimarket supports 2 types of Punchout (Roundtrip) catalog integration:

1. cXML (preferred)
2. OCI

cXML Punch-Out

For a more in-depth look at cXML PunchOut please see the cXML specification.

Implementation Steps

Login in to your store and select Create Catalog from the Catalogs menu.

Basic Information

Enter a catalog a name and description (optional). This is the information the customer will see in Unimarket before they click on the Punchout (Roundtrip) link. Select Roundtrip from the Catalog Type drop down menu and choose the Roundtrip Type (cXML or OCI).

Punchout (Roundtrip) Credentials

Configure the Punchout (Roundtrip) URL, Settings and Header Values. Header values are determined by you depending on how you would like to process the PunchOutSetupRequest from Unimarket.

• URL: Your Punchout (Roundtrip Request) URL.
• Allow Decimal Quantities: Only enable if your Punchout catalog contains decimal quantity products, (e.g. "1.5 yards of lumber").
• Product re-use allowed: Leave enabled unless you will also have Punchout Order integration, and that integration does not allow for the same roundtrip product to be re-ordered (i.e. if the customer wants to order the same product again, they need to revisit your Punchout site).
• Mime Type: Most Punchouts use text/xml.

Assign Catalog to Customers

Select which customer will have access to your new catalog. When the customer has assigned Buyer Groups to the new catalog, it will become available in their marketplace.

Upload Index Catalog

If you plan on using Punchout (Roundtrip) Search functionality, at this point you should upload your Index Catalog. Alternatively if you do not plan on using Punchout (Roundtrip) Search functionality, you can click Finish to create your Punchout (Roundtrip).

Test Roundtrip

Once you have configured the Punchout (Roundtrip) you can test using the Actions menu on the top right. If there are issues with the setup you can click View Details to view the error message. You can then amend the roundtrip setup by clicking Edit.

Technical Details (cXML)

1. Implement the PunchOut setup handling (see PunchOutSetupRequest and PunchOutSetupResponse below). This should be available at the url configured above (e.g. https://supplier.com/PunchoutSetup).

• You should authenticate the request based on the supplied Sender identity and Shared secret.
• The contents of the supplied <BuyerCookie>, <BrowserFormPost>, <To> and <From> elements need to be remembered (see Example PunchOutSetupRequest below).
• The contents of the returned PunchOutSetupResponse must contain the StartPage/URL element which will be the url the buyer's browser will be redirected to.

2. Implement the 'return shopping cart' functionality (see Example PunchOutOrderMessage below).

• The cXML header should contain the <To> and <From> elements with switched contents from the PunchOutSetupRequest (see examples below).
• The cXML header should contain the <Sender> element containing:
  • the <Credential> element with a domain of unimarket-user and
  • the <Identity> element containing the unimarket integration username.
• The <BuyerCookie> element from the PunchOutSetupRequest must be included.
• An <ItemIn> element for each item in your shopping cart must be created.
• Submit the constructed PunchOutOrderMessage to the url specified in the <BrowserFormPost> element in the original PunchOutSetupRequest.
  • The preferred submit parameter name is cxml-urlencoded.

3. Use the Test link to initiate a PunchOut to your store.

Example cXML messages

Example PunchOutSetupRequest (Unimarket --> Supplier)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="907bd336-5242-4e90-8214-4873449f5f17" timestamp="" xml:lang="en-US">
  <Header>
    <From>
      <Credential domain="[FROM_DOMAIN]">
        <Identity>[FROM_IDENTITY]</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="[TO_DOMAIN]">
        <Identity>[TO_IDENTITY]</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="[SENDER_DOMAIN]">
        <Identity>[SENDER_IDENTITY]</Identity>
        <SharedSecret>[SENDER_SECRTET]</SharedSecret>
      </Credential>
      <UserAgent>Unimarket</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>907bd336-5242-4e90-8214-4873449f5f17</BuyerCookie>
      <Extrinsic name="User">buyer-username</Extrinsic>
      <Extrinsic name="UserEmail">buyer@email.com</Extrinsic>
      <Extrinsic name="UniqueName">buyer-username</Extrinsic>
      <BrowserFormPost>
        <URL>http://community.unimarket-staging.com/ws/cXMLRoundtrip.htm?storeId=216</URL>
      </BrowserFormPost>
      <SupplierSetup>
        <URL>[https://supplier.com/RoundtripSetup]</URL>
      </SupplierSetup>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Example response to PunchOutSetupRequest (Supplier --> Unimarket)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="2009-11-02T13:27:53+10:00" timestamp="2009-11-02T13:27:53+10:00">
  <Response>
    <Status code="200" text="OK"/>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>[https://supplier.com/StartPage]</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

Example PunchOutOrderMessage (Supplier --> Unimarket)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="2009-11-02T13:29:53+10:00" timestamp="2009-11-02T13:29:53+10:00">
  <Header>
    <From>
      <Credential domain="[TO_DOMAIN]">
        <Identity>[TO_IDENTITY]</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="[FROM_DOMAIN]">
        <Identity>[FROM_IDENTITY]</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="unimarket-user">
        <Identity>[UNIMARKET_INTEGRATION_USER_ID]</Identity>
      </Credential>
      <UserAgent>Supplier</UserAgent>
    </Sender>
  </Header>
  <Message>
    <Status code="200" text="OK">The shopping session completed successfully.</Status>
    <PunchOutOrderMessage>
      <BuyerCookie>907bd336-5242-4e90-8214-4873449f5f17</BuyerCookie>
      <PunchOutOrderMessageHeader operationAllowed="edit">
        <Total>
          <Money currency="NZD">6.58</Money>
        </Total>
      </PunchOutOrderMessageHeader>
      <ItemIn quantity="1" lineNumber="1">
        <ItemID>
          <SupplierPartID>33005141</SupplierPartID>
        </ItemID>
        <ItemDetail>
          <UnitPrice>
            <Money currency="NZD">5.85</Money>
          </UnitPrice>
          <Description xml:lang="en">Reynard antibacterial hand spray pens pkt 3</Description>
          <UnitOfMeasure>EACH</UnitOfMeasure>
          <Classification domain="SPSC">00000000</Classification>          
        </ItemDetail>
      </ItemIn>
    </PunchOutOrderMessage>
  </Message>
</cXML>

OCI Punch-Out

For an OCI (Open Catalog Interface) Punchout follow the steps above, however select Roundtrip Type 'OCI'. Setup of the OCI punch-out requires a URL, Username and Password. Details on the OCI standard can be found here.