cXML PunchOut

Pressero supports the level 1 cXML PunchOut process for integration with procurement systems. If your customer uses a procurement system that supports cXML PunchOut level 1, and would like to integrate with the Pressero B2B storefront you provide to them, cXML PunchOut is the most common mechanism.

For full documentation on the cXML process, please visit http://www.cxml.org. Note that cXML is a very large specification governing a wide variety of procurement and financial transactions. Pressero has only implemented the PunchOut process as well as the PurchaseOrder process to the extent that an estimate placed can be approved or denied.

In order to configure cXML PunchOut on your site, you need to follow these steps:

Find out if your customer will have any TLS requirements (TLS is the modern name for what used to be called SSL). Often, procurement systems will only interact with sites that use https. You may need to add the In Store Credit Card Payments feature to have a certificate assigned to the site.
- If your procurement system uses TLS, then it must support modern TLS standards. In particular, it must support SNI and TLS 1.2. If the procurement system cannot talk to our server using this modern TLS protocol, we cannot support it.
Create a shared user to act as the default user. For cXML PunchOut, if Pressero cannot find the user specified by the procurement system, this user will be used. Create this shared account on the B2B site. The password MUST be the same as the user login.
Create any additional users in the site that the Procurement system might use. If you would like to have users created on the fly you will need to specifically ask for that. If the procurement system you are using contains everything that is needed to make this happen, then we can activate this feature. The system will not create users by default so in that case, it is important that the user exist in the site or the PunchOut could fail.
Each workflow that the products in the site utilize must have a workflow stage of "Estimate Request" for it to work properly. The initial PunchOut is not an order... the items are marked as Estimate Request. At a later point (sometimes nearly immediately) the procurement system will approve those estimates. They will then switch to an "Order Received" status.
Properly define your products. In order for cXML to function, the product may need to have the following information set: Part Number and Public Part Number. You should clarify with your customer which information is needed:
- SupplierPartAuxilliaryID is used by Pressero to keep track of the individual line items of your order. Your procurement system must not expect to use this for any other purpose.
- The Part Number will be used as the SupplierPartID tag. This must be able to uniquely identify the product among all the products of your Pressero site.
- The Public Part Number will be used as the Classification tag: Classification lists the UNSPSC (United Nations Standard Products and Services Code) commodity code for each selected item. These codes are used by back-end systems within buyer and supplier organizations for accounting and report generation. For the list of UNSPSC codes, see www.unspsc.org.
- Note that the Pressero MISID will not be passed as any part of the cXML PunchOut process.
Your customer will need some url information to configure their procurement system:
- https://{domain}/cxml/setup is the punchout setup url
- https://{domain}/cxml/purchaseorder is the final purchase url
- If you prefer not to use SSL (TLS) for the punchout, change the "https" to "http"
Set the site master password to be the Shared Secret. This will allow the incoming cxml user to authenticate under any site user account without knowing the account's specific password.
Orders placed using cXML PunchOut are not orders initially! At first a cXML PunchOut transaction is marked as an estimate request. The procurement system will later (immediately, or whenever your customer decides) be marked as an order. You will see these estimate requests in orders page of the Pressero admin.
Contact support with the following information and request cXML PunchOut provisioning:
- Site URL of the Pressero site you have created for your customer.
- Shared Secret to be used by the procurement system. (Your customer may provide you with this information or you may need to create it. Clarify this point with your customer.)
- Default site user account.
- You can allow the PunchOut to override any shipping and billing address information that is provided while the buyer is in the PunchOut session. Notify the support team if you would like these options enabled.
- By default Pressero will look to the Sender Identity to match to a Pressero user account. Some procurement systems specify the user in an alternative section of the punch out request, such as an extrinsic (custom) field. If the procurement system does this, please tell the support team where it can be found. It may be helpful to ask your customer for a sample Setup Request cxml so we can confirm the location of the user information.
- Let us know if you would like users to be created on the fly in Pressero.
Be patient! cXML PunchOut requires a great deal of time, effort, and coordination with your customer. Give yourself a few weeks to make the process work correctly.
Please note that cXML PunchOut is an add-on feature with a per site setup and monthly charge. Please contact us for pricing information.

Frequently Asked Questions

What URLs should be used? If your domain is abccorp.com then you should have abccorp.com/cxml/setup as the PunchOut Url and abccorp.com/cxml/purchaseorder as the PurchaseOrder Url.
Can Pressero detect the user who is using the PunchOut instead of relying on a shared user? Yes, we can use one of the extrinsic fields sent by the procurement system in the cXML PunchOut Setup request to identify an existing user in Pressero.
Can we have users created automatically during a PunchOut? Yes, if the procurement system you are using supports this option, but you need to specifically ask us to activate that for you. By default we do not do this and users will need to already exist in Pressero.
What happens if the user referenced in the PunchOut is deleted in Pressero? Pressero will consider this user to be "blocked" and attempt to login the user with the shared user account, if available.
I can't get the user to automatically login during the PunchOut process. What could be the problem behind it? We will try to use the shared secret as a password. Try setting your shared secret as the master password for your site or account and try again.
The order got placed but isn't marked as "Estimate Request". What's wrong with my setup? Verify if the product is assigned to a workflow that contains one stage mapped to the "Estimate Request" meaning and if all of the items are at the "Estimate Request" stage.
The order got placed but no emails got generated. What's wrong with my setup? The emails will only be fired after the PurchaseOrder process. PunchOuts will create estimates.
The PunchOut worked as expected, but after confirming the order on the procurement system it doesn't convert the items to "Order Placed". First try checking if your products are assigned to a workflow that contains an "Estimate Request" stage. If this is not the problem, make sure all the items are being confirmed. Pressero doesn't support partial orders for a Purchase Order process.
Which information from the PurchaseOrder request is retained? Pressero sets the PO Number of the order based on the PO Number on the request from the procurement system. The accounting information from the PurchaseOrder is also appended to the order notes.
Can I have the billing and/or shipping addresses updated when the order is confirmed on the Procurement System? Yes. By default this is turned off, but it can be requested via a support ticket.
Can I have a copy of the cxml raw data that went between the procurement system and Pressero? Yes, please open a ticket with our support team.
Will Pressero's implementation of cXML PunchOut work with <insert name of ERP here>?

Unfortunately, we are unable to answer this question. While we worked hard to make our implementation of cXML PunchOut compliant with the industry standard, we are unable to control how a particular ERP vendor has implemented it or if they have implemented it at all. By way of analogy, think of cXML Punchout as a standard, like PDF is a standard. Pressero/eDocBuilder are designed to work with PDF, and your output devices are designed to work with PDF. So the question isn’t whether Pressero/eDocBuilder works with your particular Canon/Xerox/HP/KM/Ricoh/etc device…the question is whether both conform to the PDF standard. It’s really the same with cXML Punchout. As long as both properly support the standard, it will work.

In addition, the ERP may only provide cXML as an add-on that your customer may or may not have purchased. Also, as ERP systems have multiple versions, a question like "Will this work with Oracle" is too broad to answer. The best approach is to share this knowledge base article with your customer and have their ERP admin team or vendor verify compliance. The most important question to answer is if the ERP system can support the level 1 cXML PunchOut process.

Can Aleyant support the configuration of cXML PunchOut with <insert name of ERP here>?

We are able to support Pressero and its implementation of cXML PunchOut. Given the high complexity and variety of ERP systems, we are unable to provide any direct assistance with the configuration of your customer's ERP system. Most ERP implementations have dedicated staff or vendors to manage the configuration process. Completing the cXML PunchOut integration will require you to work with your customer's ERP staff as well as with Aleyant's support staff.

Does Pressero CXML support PunchOut Catalog functionality?
CXML PO integration for your Pressero site allows for placing orders as Estimate Requests and then converting them to received orders. But the integration does not support PunchOut Catalog functionality, and attempting to call to the catalog address on your Pressero site will indicate that catalogs are not supported.

Process Overview

1) cXML SETUP REQUEST: Procurement system starts an operation and calls the cXML Setup endpoint ({domain}/cxml/setup) so it can pre-authenticate the user and receive an auto-login URL. A shared user having its password as the same string of his login is required for fallback during authentication. We ALWAYS log what we receive and what we respond here:

<?xml version="1.0" encoding="utf-16"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd"[]>
<cXML xml:lang="en-US" payloadID="1415111498.512158@ip-10-113-134-13" timestamp="Tue, 04 Nov 2014 14:31:38 +0000">
  <Header>
    <From>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
        <SharedSecret>A_SHARED_SECRET</SharedSecret>
      </Credential>
      <UserAgent>Procurement System 1.0</UserAgent>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>dg123cfsi7f2qy384123huk12jhn3jb</BuyerCookie>
      <Extrinsic name="FirstName">John</Extrinsic>
      <Extrinsic name="LastName">Doe</Extrinsic>
      <Extrinsic name="UniqueName">jdoe</Extrinsic>
      <Extrinsic name="UserEmail">jdoe@samplecustomer.com</Extrinsic>
      <Extrinsic name="User">jdoe</Extrinsic>
      <BrowserFormPost>
        <URL>https://procurementhost.com/punchout/checkout?id=8</URL>
      </BrowserFormPost>
      <Contact role="endUser">
        <Name xml:lang="en-US">sample</Name>
        <Email>sample@domain.com</Email>
      </Contact>
      <SupplierSetup>
        <URL>https://samplecustomer.net/cxml/setup</URL>
      </SupplierSetup>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Important Notes:

Header.Sender.Credential.Identity will be matched to the Pressero user account.
Extrinsic entries are essentially custom fields. Pressero does not handle or retain these fields.
The Contact information is not currently saved.

2) Your Pressero site prepares the environment to start the cXML session and responds to the Setup Request (from Step 1)

<?xml version="1.0" encoding="utf-16"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="635506866995086566" timestamp="2014-11-04T08:31:39-06:00">
  <Response>
    <Status code="200" text="OK" />
    <PunchOutSetupResponse>
      <StartPage>
        <URL>https://samplecustomer.net/cxml/start?id=dd2aec64-0540-4790-8477-7210a15ca824</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

As you will see, the StartPage includes a URL to your Pressero site.

3) Procurement system redirects the user to the start url returned in #1 and we log the contents of the setup request that will be used in the session. User gets automatically logged in to the Pressero site.

4) User adds items to the cart. Upon checkout, instead of redirecting them to the order summary page informing that the order has been placed, we use the cXML Setup information that is stored in the session to identify that the order should be put in an “Estimate Request” stage. Pressero generates the cXML PunchOut Order Message that is sent back to the procurement system through a POST operation. User gets automatically redirected back to the procurement system. Your Pressero site will also send the contents of the order to the procurement system:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="2f236469-65f6-4c3c-a63a-2326baa6185a|48707" timestamp="2014-11-04T08:42:22-06:00">
  <Header>
    <From>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="DUNS">
        <Identity>SampleCustomer</Identity>
        <SharedSecret>A_SHARED_SECRET</SharedSecret>
      </Credential>
      <UserAgent>Pressero</UserAgent>
    </Sender>
  </Header>
  <Message deploymentMode="production">
    <PunchOutOrderMessage>
      <BuyerCookie>dg123cfsi7f2qy384123huk12jhn3jb</BuyerCookie>
      <PunchOutOrderMessageHeader operationAllowed="edit">
        <Total>
          <Money currency="USD">250.0000</Money>
        </Total>
      </PunchOutOrderMessageHeader>
      <ItemIn quantity="50">
        <ItemID>
          <SupplierPartID>productpartid</SupplierPartID>
          <SupplierPartAuxiliaryID>8f74304a-5611-4cdd-a524-53ce4feba89f|10000-1</SupplierPartAuxiliaryID>
        </ItemID>
        <ItemDetail>
          <UnitPrice>
            <Money currency="USD">5.0000</Money>
          </UnitPrice>
          <Description xml:lang="en">This is the Product Description</Description>
          <UnitOfMeasure>EA</UnitOfMeasure>
          <Classification domain="UNSPSC">78678</Classification>
        </ItemDetail>
      </ItemIn>
    </PunchOutOrderMessage>
  </Message>
</cXML>

5) User approves the order in the procurement system. Note that this approval is separate from Pressero.

6) Procurement System sends a cXML PO request, which will transform the Estimate Request, into an order and fire any subsequent events, like emails and production file generation. Please note that the purchase order sent can only approve the estimate request. It can not edit the estimate request. Please note that this will fail if the order doesn’t contain all items from the original “Estimate Request” or if one of the items isn’t in the “Estimate Request” stage.

<cXML xml:lang="en-US" payloadID="1409767283.002071@ip-xxx-xxx-xxx-xxx" timestamp="2014-09-03T13:01:23-05:00">
  <Header>
    <From>
      <Credential domain="DUNS">
        <Identity>Customer</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>Printer</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="DUNS">
        <Identity>Customer</Identity>
        <SharedSecret>12345</SharedSecret>
      </Credential>
      <UserAgent>Procurement System Name</UserAgent>
    </Sender>
  </Header>
  <Request>
    <OrderRequest>
      <OrderRequestHeader orderID="2071" orderDate="2014-09-03T13:01:23-05:00" type="new">
        <Total>
          <Money currency="USD">13.5</Money>
        </Total>
        <ShipTo>
          <Address isoCountryCode="US" addressID="839">
            <Name xml:lang="en">Customer Name.</Name>
            <PostalAddress name="default">
              <DeliverTo>Sample Sample</DeliverTo>
              <Street>123 Main Street</Street>
              <Street>Suite 500</Street>
              <City>Anytown</City>
              <State>WI</State>
              <PostalCode>12345</PostalCode>
              <Country isoCountryCode="US">United States</Country>
            </PostalAddress>
            <Email name="default">email@domain.com</Email>
          </Address>
        </ShipTo>
        <BillTo>
          <Address isoCountryCode="US" addressID="7">
            <Name xml:lang="en">Customer Name</Name>
            <PostalAddress name="default">
              <DeliverTo>Sample Sample</DeliverTo>
              <Street>433 Main Street</Street>
              <City>Anytown</City>
              <State>WI</State>
              <PostalCode>12345</PostalCode>
              <Country isoCountryCode="US">United States</Country>
            </PostalAddress>
            <Email name="default">purchasing@associatedbank.com</Email>
          </Address>
        </BillTo>
        <Shipping>
          <Money currency="USD">0.0</Money>
          <Description xml:lang="en-US">
          </Description>
        </Shipping>
        <PaymentTerm payInNumberOfDays="30" />
        <Contact role="endUser">
          <Name xml:lang="en">Sample Sample</Name>
          <Email name="default">email@domain.com</Email>
        </Contact>
      </OrderRequestHeader>
      <ItemOut quantity="1" lineNumber="1">
        <ItemID>
          <SupplierPartID>value</SupplierPartID>
          <SupplierPartAuxiliaryID>ba7bbd45-76f8-4e3c-9584-e35b5ce8d687|12345-1</SupplierPartAuxiliaryID>
        </ItemID>
        <ItemDetail>
          <UnitPrice>
            <Money currency="USD">6.75</Money>
          </UnitPrice>
          <Description xml:lang="en">Business Card</Description>
          <UnitOfMeasure>EA</UnitOfMeasure>
          <Classification domain="UNSPSC">unknown</Classification>
         </ItemDetail>
        <Distribution>
          <Accounting name="Business Cards">
            <Segment type="Bank" id="001" description="Bank" />
            <Segment type="Account" id="11111" description="Account" />
            <Segment type="Cost Ctr" id="22222" description="Cost Ctr" />
          </Accounting>
          <Charge>
            <Money currency="USD">10.75</Money>
          </Charge>
        </Distribution>
      </ItemOut>
     </OrderRequest>
  </Request>
</cXML>

Article ID: 367, Created: 7/6/2013 at 12:08 AM, Modified: 12/30/2021 at 5:49 PM

Frequently Asked Questions

Process Overview

Was this article helpful?

Share this article