🚀 Punchout Problem Solvers 🚀

Everything You Need to Know About Punchout

What is cXML Punchout?

Our punchout plugin allows for an integration between Infigo and a procurement system. Infigo will handle the e-commerce experience, including a combination of personalised and static products, and then hand over the contents of the basket to a procurement system where they can then go through their own approval workflows before confirming the order.

Our Punchout plugin is a paid plugin. If you read through this article and decide this is something that you would like to use on your platform then please reach out to Support or contact Sales.

How does it work?

It uses an industry standard XML markup called cXML.

Between the two systems (Procurement/third party and Infigo) there are a number of interactions and data exchanges that are detailed in the below (and attached) diagram.

General setup

Once you have enabled the plugin on your platform you then need to configure it on the relevant storefront.

Navigate to 'Connect Settings' in admin and then enable 'Connect: PunchOut' from the list of available plugins.
go to 'Connect Plugins' and click configure against your PunchOut plugin in order to start setting it up.
Enter in your Shared Secret (which you can obtain from the third party system).
Then set your Punchout Sender Identity, Sender Domain, Infigo side identity and Infigo identity domain.

As part of the setup process Infigo will share with the third party system a webhook URL that they will use for the Setup cXML request step. This you can find from the bottom of the plugin configuration page.

Infigo will also share with the third party system a webhook URL for the order status update process. They will need to store this and then use it when calling the Order Request. This you can also find from the bottom of the plugin configuration page.

Setup cXML Request

Third Party → Infigo

The first interaction is the setup request. This is initiated by the third party procurement system and it is essentially establishing the connection with Infigo and requesting a Single Sign On URL for a particular user and session.

Infigo will also store the BrowserFormPost URL against the user as this will be used later in the order submission process.

In this request, the third party system will send a request similar to this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.038/cXML.dtd">
<cXML payloadID="1528210417404-488391118527609149@216.109.111.6" timestamp="2018-06-05T07:24:25-07:00" xml:lang="en-US">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>AN01000002779-T</Identity>
</Credential>
</From>
<To>
<Credential domain="Infigo">
<Identity>{Infigo Identity Setting}</Identity>
<Domain>{Infigo Identity Domain</Domain>
</Credential>
</To>
<Sender>
<Credential domain="NetworkUserId">
<Identity>tester@punchout.com</Identity>
<SharedSecret>******</SharedSecret>
</Credential>
<UserAgent>CatalogTester</UserAgent>
</Sender>
</Header>
<Request>
<PunchOutSetupRequest operation="create">
<BuyerCookie>ksuwteYooMAZpmuzoV9IdrXT6BUMUEJM0.0976259363610921832</BuyerCookie>
<Extrinsic name="UserEmail">test@infigosoftware.com</Extrinsic>
<Extrinsic name="UniqueName">username</Extrinsic>
<Extrinsic name="DisplayName">Test Test</Extrinsic>
<Extrinsic name="DepartmentID">1234</Extrinsic>
<BrowserFormPost>
<URL>http://test.punchout.com/checkoutcatcher.aspx</URL>
</BrowserFormPost>
</PunchOutSetupRequest>
</Request>
</cXML>

So in the above request you can see that information about the user, credentials to connect and also the BrowserFormPost url are all included in the initial request.

Infigo then checks if the Punchout credentials are correct, if they are then we start by checking if the user exists. If we do not find a match for the user then will create a user for them - assign them to the department (if passed and the department exists) and store the BrowserFormPost URL against that user.

NOTE: Extrinsic names (UserEmail, UniqueName, DisplayName, DepartmentID) are configurable in the Plugin settings.

NOTE: The department mapping works by setting an External ID against the department (checkout this article on how to assign external IDs) and then that External ID value should be passed in the setup punchout request in the 'DepartmentID' extrinsic field.

Then Infigo generates a Single Sign On URL and in the response to the third party system includes this URL:

Infigo → Third Party

<cXML>
<Response>
<Status code="200" text="{Error/Success message}">{Error/Success message}</Status>
<PunchOutSetupResponse>
<StartPage>
<URL>{SSO Login URL}</URL>
</StartPage>
</PunchOutSetupResponse>
</Response>
</cXML>

The third party system then takes this URL and presents it to their user as a way to navigate and access Infigo directly from their system. Clicking that url will re-direct the user and automatically log them into their Infigo account seamlessly.

Ordering products

Once logged in, the user will interact with Infigo in the same way any other user would. Navigating through the product category and ordering personalised and non-personalised products.

Adding all their items to the basket the user can then checkout which, though configuration, would be a streamlined checkout without delivery and payment methods to select or complete.

Order Submission cXML

Infigo → Third Party

When an order is placed in Infigo it is marked as unpaid, which means it is put into a temporary on-hold state until it is paid and can then be processed.

At this point a request is sent from Infigo to the third party system, using <BrowserFormPost> URL from the setup request that includes all the order information, as shown below:

<?xml version="1.0" encoding="utf-16"?>
<cXML
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" timestamp="timestmap" payloadID="payloadId" version="version">
<Header>
<From>
<Credential domain="domain">
<Identity>identity</Identity>
<SharedSecret>sharedsecret</SharedSecret>
</Credential>
</From>
<To>
<Credential domain="domain">
<Identity>identity</Identity>
<SharedSecret>sharedsecret</SharedSecret>
</Credential>
</To>
<Sender>
<Credential domain="domain">
<Identity>identity</Identity>
<SharedSecret>sharedsecret</SharedSecret>
</Credential>
<UserAgent>useragent</UserAgent>
</Sender>
</Header>
<Message deploymentMode="deploymentMode">
<Status code="code" text="text">value</Status>
<PunchOutOrderMessage>
<BuyerCookie>butercookie</BuyerCookie>
<PunchOutOrderMessageHeader operationAllowed="operation allowed" quoteStatus="quotestatus">
<Total>
<Money currency="currency">value</Money>
</Total>
<Shipping>
<Money currency="currency">value</Money>
<Description>description</Description>
</Shipping>
<Tax>
<Money currency="currency">value</Money>
<Description>description</Description>
</Tax>
</PunchOutOrderMessageHeader>
<ItemIn quantity="3">
<ItemID>
<SupplierPartID>supplierPart</SupplierPartID>
<SupplierPartAuxiliaryID>auxiliar</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<Description>description</Description>
<UnitOfMeasure>unitofmeasure</UnitOfMeasure>
<UnitPrice>
<Money currency="currency">value</Money>
</UnitPrice>
<Extrinsic name="name">value</Extrinsic>
<Classification domain="domain">text</Classification>
</ItemDetail>
</ItemIn>
</PunchOutOrderMessage>
</Message>
</cXML>

When submitting this back to the third party system we will use the BrowserFormPost URL that we captured and stored as part of the Setup Request.

Third Party Approval

Once the contents of the order is submitted back into the third party system it can go through whatever approval workflows have been configured.

It is important to note that this integration only supports rejecting or approving at an Order Level. It is not currently possible to have a number of the items rejected for approval within the third party system and then have Infigo cancel off those items but continue with the rest of the order. The process would need to be cancel this order and place another.

Order Request cXML

Third Party → Infigo

Once the approval process has happened and the entire order is approved, the third party system will send its last request to Infigo that will effectively let us know that the order is paid, approved and good to be progressed.


<?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="93369535150910.10.57.136"
timestamp="2000-08-03T08:49:11+07:00">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>{Sender Identity Setting}</Identity>
</Credential>
</From>
<To>
<Credential domain="NetworkID">
<Identity>{Infigo Identity Setting}</Identity>
</Credential>
</To>
<Sender>
<Credential domain="NetworkUserId">
<Identity>tester@punchout.com</Identity>
<SharedSecret>******</SharedSecret>
</Credential>
<UserAgent>CatalogTester</UserAgent>
</Sender>
</Header>
<Request>
<OrderRequest>
<OrderRequestHeader orderID="{Infigo Order ID}">
<ShipTo>
<Address>
<PostalAddress>
<DeliverTo>John Q. Smith</DeliverTo>
<DeliverTo>Buyers Headquarters</DeliverTo>
<Street>123 Main Street</Street>
<City>Mountain View</City>
<State>CA</State>
<PostalCode>94089</PostalCode>
<Country>United States</Country>
</PostalAddress>
<Email>john_smith@acme.com</Email>
</Address>
</ShipTo>
<BillTo>
<Address isoCountryCode="US" addressID="12">
<Name xml:lang="en">Acme Accounts Payable</Name>
<PostalAddress name="default">
<Street>124 Union Street</Street>
<City>San Francisco</City>
<State>CA</State>
<PostalCode>94128</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>415</AreaOrCityCode>
<Number>6666666</Number>
</TelephoneNumber>
</Phone>
</Address>
</BillTo>
<Payment>
<PCard number="{PO Number}" expiration=""/>
</Payment>
</OrderRequestHeader>
</OrderRequest>
</Request>
</cXML>

On receipt of this request, Infigo will update a few elements on the order:

The shipping address - if this is different to what was used in the original placement of the order (if one was captured then) then Infigo will update it to whatever address is sent back to ensure it is correct.
The billing address - similar to the shipping address, we will update the billing address details against the order
The PO Number - we will capture and update the PO Number against the order with what is sent back
We will update the order to paid, which means it is no longer temporarily on-hold and can now be processed as normal.
If any other connect plugin is enabled and configured it will be called at this point.
Please note: there isn't anything in the existing logic which allows for the quantity of an order, the price of an order or the associated shipping dimensions and / or price to be updated after approval in the third party application.

NOTE: The ShipTo address details are mapped as so:

* DeliverTo (Array) - The second item in this list is mapped to the Address Line 2 in Infigo

* Street (Array) - The first item in this list is mapped to the Address Line 1 in Infigo

PunchOut Extrinsic Value Sent to Siteflow

The PunchOut plugin can capture a named value sent by your procurement system during a PunchOut session and store it as a checkout attribute on the resulting order. The Siteflow plugin can then compose that value into the order identifier it submits to HP Siteflow using a configurable placeholder format, so the value appears on the FedEx shipping label reference field. This lets a mailroom read a cost centre or "RC" code directly from the label and attribute internal billing accurately.

Problem

During a PunchOut session your procurement system can send additional identification values (for example a cost centre code) as named cXML extrinsic elements. Previously the platform could not capture arbitrary extrinsic values as checkout attributes, and the identifier sent to HP Siteflow could only be built from the existing order identifier plus fixed prefix and postfix text. As a result there was no way to carry a per-session code through to the FedEx shipping label.

Environment

Infigo storefront with the PunchOut plugin and the HP Siteflow plugin both active.

Configuration

Step 1: Open Connect Plugins

In the admin sidebar go to Configuration, then Connect Plugins. This page lists the integration (Connect) plugins installed on the storefront, including Punchout and Connect: Site Flow. Open each plugin from here to reach its settings.

Step 2: Map the PunchOut extrinsic value to a checkout attribute

Open the Punchout plugin settings and find the Extrinsic to checkout attribute mapping setting. For each value you want to capture, add a mapping: enter the name of the incoming cXML extrinsic element and select the target checkout attribute it should be written to. Multiple mappings are supported. When a setup request arrives, the value of each configured extrinsic is stored against its checkout attribute on the customer; if the extrinsic is absent, the mapped attribute is left untouched. Map free text extrinsics onto a text or hidden checkout attribute.

Step 3: Set the Source order id format on Connect: Site Flow

Open the Connect: Site Flow plugin settings and set the Source order id format (Infigo placeholders) field with your template. Use placeholders such as %OrderId% and %CheckoutAttribute_AttributeName% (using your checkout attribute's name), for example %CheckoutAttribute_RC Code%-%OrderId%-Infigo. The resolved template replaces the prefix, order id and postfix that would otherwise be sent. You are responsible for any separator characters and for the overall length. If the template resolves to an empty value, the order is still submitted using the existing identifier format.

Closing note

How HP Siteflow and FedEx render the shipping label reference field is outside Infigo's control; Infigo composes and submits the Source Order ID only. If you need help, raise a ticket with Infigo Customer Support.

Search Terms

punchout extrinsic checkout attribute siteflow source order id format placeholder cost centre code on FedEx shipping label punchout cXML value to siteflow checkout attribute on shipping label

Punchout: Why are charges added through checkout attributes missing from the order in my procurement system?

Summary

The Include checkout attributes as Items setting in the Connect: PunchOut plugin sends each checkout attribute on an order to your procurement system as its own line item. Each line carries the attribute's price, the value the customer chose or typed and, depending on your classification settings, a classification code.

Problem

Charges that customers add at checkout through checkout attributes, for example a gift wrap charge, do not appear as lines in the order your procurement system receives, so its item lines do not add up to the order total. This is because Include checkout attributes as Items is off by default.

Environment

Connect: PunchOut is enabled for the storefront. The setting is in Configuration > Plugins > Connect Plugins > Connect: PunchOut > Configure, in the XML generation group. It is off by default.

Configuration

Step 1: Open the Connect: PunchOut settings

In the admin area go to Configuration > Plugins > Connect Plugins, find Connect: PunchOut and click Configure. Scroll to the XML generation group.

Step 2: Turn on Include checkout attributes as Items

Tick Include checkout attributes as Items. When it is ticked, each checkout attribute on an order is sent as a separate line item in the order message to your procurement system. Every checkout attribute on the order is sent, not only the ones that have an External ID, and attributes with no price are sent as lines with a price of 0.

Step 3: Check how the lines are classified

Important: Enable UNSPSC Category in Order cXML, Default UNSPSC Category ID and Item detail classification are also used for the product lines of the order. Changing any of them changes how every product line is classified, so leave them as they are unless you mean to change the product lines too.

These settings are in the same group. They decide how each checkout attribute line is classified:

Enable UNSPSC Category in Order cXML ticked: each line gets a UNSPSC classification. The code is the checkout attribute's External ID (step 5). If the attribute has none, the code in Default UNSPSC Category ID is used. If that is empty too, the line is sent without a classification.
Enable UNSPSC Category in Order cXML not ticked: a line is classified only when Item detail classification is filled in and the attribute has an External ID. The line then carries that classification name with the External ID as its value. Otherwise it has no classification.

Use the option your procurement system expects.

Step 4: Save the plugin settings

Tell your buyer's procurement team before you save, because the new lines will appear on your Punchout orders. Scroll to the top of the page and click Save.

Step 5: Set a classification code on each checkout attribute

Skip this step if you do not need classifications, or if you ticked Enable UNSPSC Category in Order cXML and every attribute can use the Default UNSPSC Category ID. Otherwise:

Go to Catalogue > Attributes > Checkout Attributes.
On the row of the checkout attribute, click the green Connect Link button, which is to the left of Edit. The button only shows while a Connect plugin is enabled.
Enter the code as the External ID for Connect: PunchOut, and save. The Connect Link popup article explains the popup.
Repeat for each checkout attribute that needs its own code.

Step 6: Know what your procurement system receives

For each checkout attribute on a Punchout order, one line item is added after the product lines:

Quantity: 1.
Price: the attribute's price adjustment, excluding tax.
Description: the value the customer chose or typed, or the attribute's name if there is none. When more than one value is chosen, the names are joined with commas.
Part ID and auxiliary part ID: the order ID and the attribute name, for example 12345-Gift wrap.
Classification: as set in step 3.

Step 7: Check that it worked

Place a Punchout order with a checkout attribute selected and look at the order in your procurement system. You should see one extra line for each checkout attribute that has a value on the order, after the product lines. A checkout attribute with no value on the order does not create a line. If no lines come back at all, check that the test order was paid with a payment method your Callback payment method filter allows. If a line is missing, check that the setting was saved (step 4). If a line has no classification, check step 3 and that the attribute has an External ID or there is a default code.

Search Terms

punchout checkout attribute charge missing, checkout attribute charge not in procurement order, punchout order total does not match, extra charges missing punchout cart, punchout checkout attributes as line items, Include checkout attributes as Items, punchout checkout attribute charges as separate line items, punchout UNSPSC checkout attribute, Default UNSPSC Category ID, punchout checkout attribute External ID, Enable UNSPSC Category in Order cXML, punchout classification checkout attribute

Punchout: Why are fees and shipping not showing as separate lines in my procurement system?

Summary

Order, Job and Product fees can be set per product, and the Connect: PunchOut plugin can send those fees and the shipping cost to your procurement system as separate line items, each with its own UNSPSC code. The procurement system's payloadID can also be saved on the order.

Problem

Fees reach your procurement system only inside the order total, with no separate lines or classification. Shipping arrives as a separate shipping charge, not as a classified line. The order does not record the procurement system's own reference for it, and fees cannot be set differently for each product.

Environment

Connect: PunchOut is enabled for the storefront. The Punchout settings are in Configuration > Plugins > Connect Plugins > Connect: PunchOut > Configure. Per-product fees are switched on in Configuration > Settings > Order Settings. You need the UNSPSC codes your procurement system expects and a way to place a test Punchout order. Everything is off by default.

Configuration

Step 1: Turn on per-product fees (optional)

In the admin area go to Configuration > Settings > Order Settings. In the Processing and Handling fee group, tick Enable per-product fees and click Save. It is off by default. The store's own Order Processing fee, Job Handling fee and Product Handling fee in the same group (see Handling and processing fees) stay as they are, and the product fees are added on top of them. Per-product fees apply to every order on the store, not only Punchout orders. If you move a fee from the store to products, set the store's own fee to 0, or it is charged as well.

Step 2: Set the fees on a product or product group (optional)

Before you start: if you currently charge the same fees with checkout attribute pricing scripts, switch those scripts off. If they stay on, customers are charged twice.

Go to Catalogue > Products > Product Management (or Catalogue > Products > Product Groups). For a product, open it and then open its variant (the Product variants tab, then Edit). For a group, open the group.
On the Info tab, below Product cost, fill in the fees you need. The fee fields only show once Enable per-product fees is ticked and saved (step 1):
- Order fee type and Order fee: a fixed amount, a percentage of the order subtotal or a percentage of the order total.
- Job fee: a fixed amount.
- Product fee: a fixed amount.
Click Save. A product that belongs to a product group uses the group's fees. A fee you leave empty adds nothing.

Step 3: How per-product fees add up

On top of the store's own fees:

Order fee: charged once per order. Only the highest product Order fee in the basket counts, and it is added to the store's Order Processing fee.
Job fee: charged for every order line of that product, added to the store's Job Handling fee for each line.
Product fee: charged once for each product in the order, however many lines it is on, added to the store's Product Handling fee.

For example, the store has an Order Processing fee of 5, a Job Handling fee of 2 and a Product Handling fee of 1. Business cards have an Order fee of 10, a Job fee of 3 and a Product fee of 4 and are on 2 lines. Flyers have an Order fee of 15 and are on 1 line. The order's fees are:

Order fee: 5 store fee + 15 (the highest product Order fee, flyers) = 20
Job fee: (2 store fee × 3 lines) + (3 business card fee × 2 lines) = 12
Product fee: (1 store fee × 2 products) + 4 business card fee = 6

Fees you set on products apply to new orders. Orders already placed keep the fees stored on them.

Step 4: Open the Connect: PunchOut settings

Go to Configuration > Plugins > Connect Plugins, find Connect: PunchOut and click Configure. Scroll to the XML generation group.

Step 5: Send fees and shipping as items

Tick Include fees as items. Then enter a code in Order Fee UNSPSC Category ID, Job Fee UNSPSC Category ID and Product Fee UNSPSC Category ID. Your procurement system uses these codes to classify each charge. A fee with no code of its own uses the Default UNSPSC Category ID, and is sent without a classification if that is empty too.
Tick Include Shipping cost as item and enter a code in Shipping cost UNSPSC Category ID. The shipping cost is then sent as its own line instead of as a separate shipping charge, so it is not charged twice.
Scroll to the top of the page and click Save. Both options are off by default.

These settings send the order's Order, Job and Product fees, whether they come from the store's own fees or from per-product fees. A fee or shipping cost of 0 is not sent as a line.

Important: this changes the order message for every Punchout order. New lines appear in your buyer's system and shipping no longer arrives as a separate shipping charge, so agree the UNSPSC codes and the change with your buyer and test it before you switch it on for a live store.

Step 6: Save the payloadID on the order (optional)

When your procurement system sends the approved order, its payloadID can be saved on the order as its payment transaction code. This happens only when the order request XSLT maps it. The Standard XSLT does and the Legacy XSLT, which is the default, does not. XSLTs you have already saved are not updated for you.

In the plugin settings, go to the Order request mapping group.
In Predefined XSLTs, select Standard and click Apply. This replaces everything in XSLT for order request call with the Standard XSLT, which also reads the shipping method and tracking number from the order request, so try it on a test order first.
Scroll to the top of the page and click Save.

If you have changed your XSLT, do not apply a predefined one, because that replaces your changes. Instead, add a PaymentTransactionId element to it and set its value to the payloadID attribute of the cXML element, and keep the rest as it is.

If a Punchout order is paid through a payment gateway that keeps its own reference in the payment transaction code, the payloadID replaces that reference, so check this first.

The order notes record that the payment transaction code was set, and any earlier code is noted alongside it. The payloadID is available in Connect:Flow as PaymentTransactionId.

Step 7: Know what your procurement system receives

For each charge on a Punchout order, one line item is added after the product lines (and after any checkout attribute lines). In the part IDs, OrderId is the order ID, for example 10234-OrderProcessingFee:

Order fee: part ID OrderId-OrderProcessingFee
Job fee: part ID OrderId-OrderLineHandlingFee
Product fee: part ID OrderId-ProductHandlingFee
Shipping: part ID OrderId-OrderShippingPrice, described by the shipping method name

Each line has a quantity of 1, the amount excluding tax and its UNSPSC code. The order Total is the order total without tax. It includes shipping only when Include Shipping cost as item is ticked. It equals the sum of the lines only when the order has no discounts, gift cards, payment method fees or checkout attribute prices, so a procurement system that checks the lines against the Total may flag such orders. To send checkout attribute prices as lines as well, tick Include checkout attributes as Items in the same group. It sends every checkout attribute on the order as a line, including ones with no price.

Step 8: Check that it worked

Place a test Punchout order and check:

The fees show in the basket and on the order.
Your procurement system shows one extra line for each fee above 0 and one for shipping, after the product lines, with the part IDs and UNSPSC codes from step 7.
If you did step 6, the order notes show that the payment transaction code was set after your procurement system sends the order back.

If no fee or shipping lines appear, check that Include fees as items and Include Shipping cost as item are ticked and saved (step 5) and that the order has a fee above 0. If a fee is charged twice, the checkout attribute pricing scripts from step 2 are still on, or the same fee is still set at store level (step 1). If a product's fee is missing, or its fee fields are not on the product, check that Enable per-product fees is ticked and saved (step 1). If no payloadID is saved, check step 6.

Search Terms

punchout fees missing in procurement system, punchout shipping not showing as line item, punchout order total does not match line items, procurement system only shows one total, punchout fees as separate line items, Include fees as items, Include Shipping cost as item, Order Fee UNSPSC Category ID, Job Fee UNSPSC Category ID, Product Fee UNSPSC Category ID, Shipping cost UNSPSC Category ID, Enable per-product fees, different fee for each product, per-product order fee job fee product fee, punchout payloadID not saved on order, punchout order reference not saved, fees charged twice punchout