Punchout Technical Details (cXML)

  • Updated

This guide outlines the three essential steps for suppliers to implement the cXML Punchout integration with Unimarket, along with examples of the required cXML message structures.

 

Steps for cXML Punchout Integration

Implement Punchout Setup Handling

You must implement the handling of the PunchOutSetupRequest and generate a PunchOutSetupResponse. This should be available at the URL configured in Unimarket (e.g., https://supplier.com/PunchoutSetup).

RequirementActionNotes
AuthenticationAuthenticate the request based on the supplied Sender identity and Shared secret. 
Data StorageRemember the contents of the supplied <BuyerCookie>, <BrowserFormPost>, <To>, and <From> elements.This data is crucial for the PunchOutOrderMessage.
ResponseThe returned PunchOutSetupResponse must contain the <StartPage/URL> element.This is the URL the buyer's browser will be redirected to.

  • Note: The PunchOutSetupRequest message will not be submitted from the buyer's browser but from a server-side process. A browser session for the buyer cannot be created at this point; it must be created when the buyer first visits the StartPage/URL.

     

Example PunchOutSetupRequest (Unimarket-->Supplier):

XML

 
<?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

 
<?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>

 

Implement 'Return Shopping Cart' Functionality

This functionality involves creating and submitting the PunchOutOrderMessage once the buyer completes their shopping on your site.

ElementRequirement
cXML HeaderThe <To> and <From> elements must contain switched contents from the original PunchOutSetupRequest.
Sender ElementThe <Sender> element must contain: <ul><li>The <Credential> element with a domain of unimarket-user.</li><li>The <Identity> element containing the Unimarket integration username.</li></ul>
BuyerCookieThe <BuyerCookie> element from the original PunchOutSetupRequest must be included.
ItemInAn <ItemIn> element for each item in your shopping cart must be created.
SubmissionSubmit the constructed PunchOutOrderMessage to the URL specified in the <BrowserFormPost> element in the original PunchOutSetupRequest.

  • Preferred Parameter: The preferred submit parameter name is cxml-urlencoded.

  • Note: The PunchOutOrderMessage message must be submitted from the buyer's browser and not from a server-side process (this is required to preserve the buyer's cookies).

 

Example PunchOutOrderMessage (Supplier --> Unimarket):

XML

 
<?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>

 

Use the Test Link

  • Use the Test link provided in the Unimarket configuration. To initiate a punchout to your store and verify the integration works correctly.