cXML PunchOut

PunchOutSetupRequest

The cXML PunchOutSetupRequest document is the first document exchanged in the PunchOut process. It is sent from the shoppers eProcurement system to the suppliers eCommerce site via an HTTP(S) POST request with the XML in the POST body.

Credentials

See the Credentials section of the cXML Overview for more information.

Operation

The PunchOutSetupRequest[@operation] attribute is set to "create" when a user is accessing a PunchOut site to create a shopping cart. Values of "inspect" and "edit" indicate the user has already created a cart and would like to view the cart or make changes to the cart. The contents of the shopping cart will be contained in the PunchOutSetupRequest/ItemOut elements.

BrowserFormPost/URL

The BrowserFormPost/URL element will contain the URL where the shopping cart should be sent back to. This will be done via an HTML <form> POST in the shopper’s web browser. For more information regarding carts see cXML PunchOutOrderMessage.

The BuyerCookie element contains a value that needs to be passed back with the shopping cart cXML (PunchOutOutOrderMessage). The eProcurement application uses this value to determine which user the cart is for. This value should be saved with the shopper’s session on the e-commerce site so it can be accessed later.

Important information for eProcurement application developers on appropriate usage of the BuyerCookie element is available here.

User Information

Information about the end user who is accessing the PunchOut site was not included as part of the original cXML PunchOut standard. As a result, eProcurement applications differ in how this information is passed in the PunchOutSetupRequest. PunchOut ecommerce application should not rely on these fields because some eProcurement applications do not pass any user information in the PunchOutSetupRequest. When this information is included, it is through a combination of Extrinsic and Contact elements.

Extrinsic Elements

The list below contains all of the common extrinsics that are derived from the user’s data. Which extrinsics are actually present will depend on the the eProcurement application being used. These elements will be children of the //cXML/Request/PunchOutSetupRequest element.

Name Description Example

UserEmail

Email address

jdoe@example.com

FirstName

First name

John

LastName

Last name

Doe

UserPrintableName

First and last name

John Doe

UserFullName

First and last name

John Doe

UniqueName

Username/login

jdoe

UniqueUsername

Username/login

jdoe

User

Username/login

jdoe

UserId

Unique ID

12345

UserPhoneNumber

Phone number

555-555-5555

PhoneNumber

Phone number

555-555-5555

Contact Element

The PunchOutSetupRequest/Contact element is present in the cXML PunchOutSetupRequest from some eProcurement applications. This element can contain the users full name and their email address. The format of the users full name often varies and may be "Last, First" or "First Last".

<Contact role="endUser">
  <Name xml:lang="en-US">Doe, John</Name>
  <Email>john.doe@example.com</Email>
</Contact>

Shipping Address

The users shipping address may be present in the PunchOutSetupRequest/ShipTo element. The shipping address included in the PunchOutSetupRequest may be different from the address used when the order is placed. The data in this element should only be used to enhance the users PunchOut experience. An appropriate usage would be auto-selecting the users default store based on their zip code in their shipping address.

<ShipTo>
  <Address addressID="12345">
    <Name xml:lang="en">My Address</Name>
    <PostalAddress>
      <Street>123 Street Address</Street>
      <City>Mountain View</City>
      <State>CA</State>
      <PostalCode>94040</PostalCode>
      <Country isoCountryCode="US">US</Country>
    </PostalAddress>
  </Address>
</ShipTo>

Example PunchOutSetupRequest

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539050765.0492@example.com" timestamp="2018-10-09T02:06:05+00:00">
  <Header>
    <From>
      <Credential domain="NetworkId">
        <Identity>buyer</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>acme</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>buyer</Identity>
        <SharedSecret>jd8je3$ndP</SharedSecret>
      </Credential>
      <UserAgent>Application Name v1.2.3</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>550bce3e592023b2e7b015307f965133</BuyerCookie>
      <Extrinsic name="UserEmail">jdoe@example.com</Extrinsic>
      <Extrinsic name="FirstName">John</Extrinsic>
      <Extrinsic name="LastName">Doe</Extrinsic>
      <Extrinsic name="PhoneNumber">555-555-5555</Extrinsic>
      <BrowserFormPost>
        <URL>https://example.com/cxml_cart</URL>
      </BrowserFormPost>
      <ShipTo>
        <Address addressID="TEST">
          <Name xml:lang="en">My Address</Name>
          <PostalAddress>
            <Street>123 Street Address</Street>
            <City>Mountain View</City>
            <State>CA</State>
            <PostalCode>94040</PostalCode>
            <Country isoCountryCode="US">US</Country>
          </PostalAddress>
        </Address>
      </ShipTo>
    </PunchOutSetupRequest>
  </Request>
</cXML>

cXML PunchOutSetupResponse

The suppliers eCommerce site responds to a PunchOutSetupRequest with a PunchOutSetupResponse document. The document contains a single URL that the shopper will be redirected to in their browser. This URL should automatically log the user in to the eCommerce site without requiring the shopper to enter any additional information. The shopper should automatically be shown the pricing/catalog for their organization based on the Credential’s in the PunchOutSetupRequest document.

StartPage/URL

The //cXML/Response/PunchOutSetupResponse/StartPage/URL element should contain a URL that the shopper can be redirected to in their web browser and automatically logged in to the supplier’s ecommerce site.

The following is a recommended method for accomplishing this:

  1. Validate the credentials in the cXML and return an error if they are invalid

  2. Generate a unique identifier for the session (ex. 32 random hex digits)

  3. Save the cXML (or information extracted from the cXML) in a temporary datastore (database, file, etc.) associated with the unique identifier.

  4. Include the unique id as a parameter in the StartPage/URL (ie https://www.example.com/punchout_entry?sid=SESSION_ID_GOES_HERE).

  5. When the user accesses the URL, validate the unique identifier and log the user into your application.

  6. Expire unused unique identifiers after 5 minutes.

Example Successful PunchOutSetupResponse

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539050765.83749@example.com" timestamp="2018-04-07T16:16:53-05:00">
  <Response>
    <Status code="200" text="OK"></Status>
      <PunchOutSetupResponse>
        <StartPage>
          <URL>https://www.example.com/punchout?sid=76857247543634381</URL>
        </StartPage>
      </PunchOutSetupResponse>
  </Response>
</cXML>

Error Responses

The following error responses are recommended:

Error Type Code Text Message

POST body is missing

400

Bad Request

No XML in POST body

XML cannot be parsed or is invalid

400

Bad Request

POST XML is not valid: ADDITIONAL_INFO

Credentials are not valid

401

Unauthorized

Sender identity or shared secret is invalid

Error in eCommerce application

500

Internal Server Error

An un-handled error occurred while processing this request

 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="1539635340.9061692@example.com" timestamp="2018-04-15T20:29:00+00:00">
  <Response>
    <Status code="401" text="Unauthorized">Message goes here</Status>
  </Response>
</cXML>

Next Steps

The shopper will be redirected to the URL returned in the StartPage/URL element. At this point the shopper can add items to their shopping cart and checkout. Instead of the typical eCommerce checkout process, the items in the shopping cart will be sent back to the eProcurement system as a PunchOutOrderMessage. The shopping cart will then be converted to a requisition which will be sent through an approval process. If the requisition is approved, an order will be sent to the supplier.

For more information regarding shopping carts see cXML PunchOutOrderMessage.

Share