The Punchout (Roundtrip) process is a standardized method for a user to leave their internal ERP system, shop within the Unimarket eMarketplace. And return a populated shopping cart to their ERP for approval and requisitioning.

The Three-Phase Punchout Process

The entire interaction happens through three primary cXML messages:

1. Punchout Setup Request (ERP → Unimarket)

The ERP initiates a session by sending an HTTPS POST request to Unimarket. This message establishes the user's identity and provides a "return address" for the cart.

Key Attributes:

• Community ID: Identifies the specific Unimarket customer community.

• System Credentials: The Identity and SharedSecret for authentication.

• Buyer Username: The specific user shopping in the session.

• BrowserFormPost: The URL where Unimarket must send the final shopping cart data.

Example Request:

2. Punchout Setup Response (Unimarket → ERP)

Once Unimarket authenticates the request, it creates a unique session and responds immediately.

• The StartPage URL: This is the most critical element of the response. The ERP must take this URL and open it in the user's web browser. This URL automatically logs the user into the Unimarket home page without requiring a second login.

Example Response:

3. Punchout Order Message (Unimarket → ERP)

After the user selects their items and clicks "Checkout" within Unimarket, the system redirects the user's browser back to the ERP.

• Mechanism: Unimarket performs a POST to the BrowserFormPost URL provided in Phase 1.

• Data Payload: The cart details are included in a parameter named cxml-urlencoded.

• Requirement: The ERP system must URL-decode this parameter to retrieve the valid cXML, which contains line-item details like SKU, quantity, price, and UNSPSC codes.

Example Punchout Order Message (URLencoded):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.021/cXML.dtd">
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:52.536+12:00" version="1.2.021" xml:lang="en">
 <Header>
   <From>
     <Credential domain="unimarket-id">
       <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
     </Credential>
   </From>
   <To>
     <Credential domain="unimarket-id">
       <Identity/>
     </Credential>
   </To>
   <Sender>
     <Credential domain="unimarket-id">
       <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
       <SharedSecret>SuperSecretPasswordHere</SharedSecret>
     </Credential>
     <UserAgent>UMKT</UserAgent>
   </Sender>
 </Header>
 <Message>
   <PunchOutOrderMessage>
     <BuyerCookie>NA</BuyerCookie>
     <PunchOutOrderMessageHeader operationAllowed="create">
       <Total>
         <Money currency="NZD">4.00</Money>
       </Total>
       <Shipping>
         <Money currency="NZD">20.00</Money>
         <Description xml:lang="en">$20.00 per order</Description>
       </Shipping>
     </PunchOutOrderMessageHeader>
     <ItemIn quantity="4">
       <ItemID>
         <SupplierPartID>1000010</SupplierPartID>
         <SupplierPartAuxiliaryID/>
         <IdReference domain="unimarketProductId" identifier="ca1be02d-60f2-47ce-9090-1add34657995"/>
       </ItemID>
       <ItemDetail>
         <UnitPrice>
           <Money currency="NZD">1.00</Money>
         </UnitPrice>
         <Description xml:lang="en">Product Code 10</Description>
         <UnitOfMeasure>EA</UnitOfMeasure>
         <Classification domain="UNSPSC">44000000</Classification>
       </ItemDetail>
       <SupplierID domain="DUNS"/>
     </ItemIn>
   </PunchOutOrderMessage>
 </Message>
</cXML>

Example Punchout Order Message (Decoded to XML):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.021/cXML.dtd">
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:52.536+12:00" version="1.2.021" xml:lang="en">
    <Header>
        <From>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-id">
                <Identity/>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
                <SharedSecret>SuperSecretPasswordHere</SharedSecret>
            </Credential>
            <UserAgent>UMKT</UserAgent>
        </Sender>
    </Header>
    <Message>
        <PunchOutOrderMessage>
            <BuyerCookie>NA</BuyerCookie>
            <PunchOutOrderMessageHeader operationAllowed="create">
                <Total>
                    <Money currency="NZD">4.00</Money>
                </Total>
                <Shipping>
                    <Money currency="NZD">20.00</Money>
                    <Description xml:lang="en">$20.00 per order</Description>
                </Shipping>
            </PunchOutOrderMessageHeader>
            <ItemIn quantity="4">
                <ItemID>
                    <SupplierPartID>1000010</SupplierPartID>
                    <SupplierPartAuxiliaryID/>
                    <IdReference domain="unimarketProductId" identifier="ca1be02d-60f2-47ce-9090-1add34657995"/>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="NZD">1.00</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Product Code 10</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                    <Classification domain="UNSPSC">44000000</Classification>
                </ItemDetail>
                <SupplierID domain="DUNS"/>
            </ItemIn>
        </PunchOutOrderMessage>
    </Message>
</cXML>

Technical Implementation Details

Setup Request Configuration

The request must be sent as an HTTPS POST to the community-specific web service URL (e.g., https://miketest.unimarket-demo.com/ws).

Example Setup Logic:

If the From identity is cb897379..., the Unimarket system recognizes the specific tenant and validates the SharedSecret. Against the credentials stored in the community's Integration settings.

The Return Handshake

The return process is "transparent" to the user. When they finish shopping, Unimarket bundles the PunchOutOrderMessage (containing the cart) and sends it via the user's browser back to the ERP. This allows the ERP to "grab" the items and populate a draft requisition automatically.

Troubleshooting Common Issues

• 401 Unauthorized: Usually caused by a mismatch in the SharedSecret or a missing unimarket-id in the header.

• StartPage Not Opening: Ensure the ERP is configured to handle the PunchOutSetupResponse synchronously and can redirect the browser session, to the provided URL.

• Empty Cart on Return: Check that the BuyerCookie in the Order Message matches the cookie sent, in the initial Setup Request.