PunchOut: Standard cXML payload for session request – TradeCentric

The PunchOutSetupRequest payload initiates a punchout session to your eCommerce platform. For standard integrations that receive cXML payloads, the TradeCentric platform transforms the buyer's PunchOutSetupRequest into our standard cXML format. Then, our platform delivers the payload to your endpoint.

For punchout sessions to start successfully, your eCommerce platform must accept our standard cXML format and respond with a start URL. This article describes the standard cXML request and response formats.

Jump to:

Request payload (from TradeCentric)

Request element details

cXML root
Header
Request

Response payload (to TradeCentric)

Response element details

cXML root
Response

Request payload (from TradeCentric)

The code block below shows an example PunchOutSetupRequest payload in our standard cXML format:

cXML

HTTP POST

PunchOutSetupRequest

<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="ABCD1234efg567@buyer.com" timestamp="2025-09-25T00:00:00Z">
    <Header>
        <From>
            <Credential domain="DUNS">
                <Identity>BuyerID</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="NetworkID">
                <Identity>SupplierID</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="NetworkID">
                <Identity>Buyer Corp.</Identity>
                <SharedSecret>password</SharedSecret>
            </Credential>
            <UserAgent>TradeCentric PunchOut</UserAgent>
        </Sender>
    </Header>
    <Request deploymentMode="production">
        <PunchOutSetupRequest operation="create">
            <!-- Unique session identifier -->
            <BuyerCookie>SESSION-123456</BuyerCookie>
            <!-- Standard extrinsic field, if applicable -->
            <Extrinsic name="unique">contact.name</Extrinsic>
            <!-- Custom extrinsic fields -->
            <Extrinsic name="pos">ABCD1234efg567</Extrinsic>
            <Extrinsic name="organisation_name">Buyer Corp.</Extrinsic>
            <Extrinsic name="organisation_id">123</Extrinsic>
            <!-- Where to send PunchOut response -->
            <BrowserFormPost>
                <URL>https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567</URL>
            </BrowserFormPost>
            <!-- Buyer contact info -->
            <Contact role="endUser">
                <Name xml:lang="en">Contact Name</Name>
                <Email>contact@buyer.com</Email>
            </Contact>
            <!-- Shipping address -->
            <ShipTo>
                <Address addressID="Main" isoCountryCode="US">
                    <Name xml:lang="en">Main Office</Name>
                    <PostalAddress name="Test Corp.">
                        <DeliverTo>Contact Name</DeliverTo>
                        <Street>3445 Seminole Trail #218</Street>
                        <City>Charlottesville</City>
                        <State>VA</State>
                        <PostalCode>22911</PostalCode>
                        <Country isoCountryCode="US">United States</Country>
                    </PostalAddress>
                </Address>
            </ShipTo>
            <!-- Selected item(s) to preload -->
            <SelectedItem>
                <ItemID>
                    <SupplierPartID>45L017</SupplierPartID>
                    <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>
                </ItemID>
            </SelectedItem>
        </PunchOutSetupRequest>
    </Request>
</cXML>

Request element details

A standard cXML PunchOutSetupRequest payload has a root element, a Header element, and a Request element. The subsections below explain each element and its fields.

cXML root

Applies identifying information to the entire payload

Example

<cXML payloadID="ABCD1234efg567@buyer.com" timestamp="2025-09-25T00:00:00Z">
  ...
</cXML>

Root field breakdown

payloadID

Session identifier

Type: String

Provides a unique identifier for the punchout session

Example: payloadID="ABCD1234efg567@buyer.com"
timestamp

Payload creation timestamp

Format: ISO 8601

Provides the date and time when the request was created

Example: timestamp="2025-09-25T00:00:00Z"

Header

Identifies the organizations involved in the punchout session

Example

<Header>
  <From>
    <Credential domain="DUNS">
      <Identity>BuyerID</Identity>
    </Credential>
  </From>
  <To>
    <Credential domain="NetworkID">
      <Identity>SupplierID</Identity>
    </Credential>
  </To>
  <Sender>
    <Credential domain="NetworkID">
      <Identity>Buyer Corp.</Identity>
      <SharedSecret>password</SharedSecret>
    </Credential>
    <UserAgent>TradeCentric PunchOut</UserAgent>
  </Sender>
</Header>

Header field breakdown

From
Buyer credential

Identifies the buyer organization
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="DUNS" = Data Universal Numbering System (DUNS) value
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>BuyerID</Identity>
To
Supplier credential

Identifies your organization
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="NetworkID" = Network identifier value from your eCommerce platform
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>SupplierID</Identity>
Sender
Sending system credential

Identifies the sending eProcurement system and provides its authentication information
- domain Identifier type
  
  Type: String
  
  Specifies the type of identifier provided in the credential
  
  Example: domain="NetworkID" = Network identifier value from the eProcurement system
- Identity Identifier
  
  Type: String
  
  Provides the identifier value for the credential
  
  Example: <Identity>Buyer Corp.</Identity>
- SharedSecret Shared secret
  
  Type: String
  
  Provides the buyer's shared secret, which is the password that your organization and TradeCentric agreed to use to authenticate the buyer
  
  Example: <SharedSecret>password</SharedSecret>
- UserAgent Additional system identifier
  
  Type: String
  
  Provides an informational identifier, such as a name, for the sending system
  
  Example: <UserAgent>TradeCentric PunchOut</UserAgent> = The TradeCentric platform sent the payload

Request

Provides the punchout session details, which are described in the subsections below

Session identification

Provides identifying information about the request and punchout session

Example

<Request deploymentMode="production">
  <PunchOutSetupRequest operation="create">
    <BuyerCookie>SESSION-123456</BuyerCookie>

Session identification field breakdown

deploymentMode

Deployment mode

Values: test, production

Specifies whether the request is for test or production

Example: deploymentMode="production"
PunchOutSetupRequest
Request details

Provides identifying information about the punchout session
- operation Requested action
  
  Values: create, edit, inspect
  
  Specifies whether to create a new session, or to edit or inspect an existing one
  
  Example: operation="create"
- BuyerCookie Buyer session identifier
  
  Type: String
  
  Provides the session identifier that the buyer generated, which we’ll also include in the return cart payload sent to the buyer
  
  Example: SESSION-123456

Extrinsic information

Provides other identifying information, which may vary depending on the integration's requirements, such as about the user and buyer organization

Example

<Extrinsic name="unique">contact.name</Extrinsic>
<Extrinsic name="pos">ABCD1234efg567</Extrinsic>
<Extrinsic name="organisation_name">Buyer Corp.</Extrinsic>
<Extrinsic name="organisation_id">123</Extrinsic>

Extrinsic field breakdown

name

Identifier type

Type: String

Specifies the type of identifier provided

Example: name="unique" = unique user identifier, name="pos" = session identifier
Extrinsic

Identifier

Type: String

Provides the identifier value

Example: <Extrinsic name="unique">contact.name</Extrinsic>

Return cart URL

Provides the URL that your eCommerce platform should send the return cart to

Example

<BrowserFormPost>
  <URL>https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567</URL>
</BrowserFormPost>

Routing field breakdown

URL

Return URL

Format: protocol://domain/path

Provides the full TradeCentric URL, including the unique session identifier, for the return cart

Example: https://connect.tradecentric.com/gateway/link/api/id/ABCD1234efg567

User contact information

Provides contact details for the user punching out

Example

<Contact role="endUser">
  <Name xml:lang="en">Contact Name</Name>
  <Email>contact@buyer.com</Email>
</Contact>

Contact field breakdown

role

Contact role

Type: String

Specifies the type of user in the buyer's preferred format

Example: role="endUser"
Name
Contact name

Type: String

Provides the name of the user

Example: <Name xml:lang="en">Contact Name</Name>
- xml:lang
  
  Format: IETF BCP 47
  
  Specifies the language used for the name
  
  Example: xml:lang="en"
Email

Contact email address

Type: String

Provides the email address for the user

Example: <Email>contact@buyer.com</Email>

Shipping information

Provides a shipping address for the punchout session

Example

<ShipTo>
  <Address addressID="Main" isoCountryCode="US">
    <Name xml:lang="en">Main Office</Name>
    <PostalAddress name="Test Corp.">
      <DeliverTo>Contact Name</DeliverTo>
      <Street>3445 Seminole Trail #218</Street>
      <City>Charlottesville</City>
      <State>VA</State>
      <PostalCode>22911</PostalCode>
      <Country isoCountryCode="US">United States</Country>
    </PostalAddress>
  </Address>
</ShipTo>

Shipping field breakdown

Address
Shipping address

Identifies the shipping address
- addressID Identifier
  
  Type: String
  
  Provides an identifier for the address
  
  Example: addressID="Main"
- isoCountryCode Country code
  
  Format: ISO 3166
  
  Specifies the country for the address
  
  Example: isoCountryCode="US"
- Name Address name
  
  Type: String
  
  Provides a name for the shipping address
  
  Example: <Name xml:lang="en">Shipping</Name>
  - xml:lang Language
    
    Format: IETF BCP 47
    
    Specifies the language used for the name
    
    Example: xml:lang="en"
- PostalAddress Postal address
  
  Provides the full shipping address
  - name Business name
    
    Type: String
    
    Provides the organization name
    
    Example: name="Test Corp."
  - DeliverTo Delivery contact
    
    Type: String
    
    Provides the name of the delivery contact
    
    Example: <DeliverTo>Contact Name</DeliverTo>
  - Street Street address
    
    Type: String
    
    Provides the street address
    
    Example: <Street>3445 Seminole Trail #218</Street>
  - City City
    
    Type: String
    
    Provides the city
    
    Example: <City>Charlottesville</City>
  - State Region code
    
    Type: String
    
    Provides the state, province, or region
    
    Example: <State>VA</State>
  - PostalCode Postal code
    
    Type: String
    
    Provides the postal code
    
    Example: <PostalCode>22911</PostalCode>
  - Country Country
    
    Type: String
    
    Provides the country name
    
    Example: <Country isoCountryCode="US">United States</Country>
    
    isoCountryCode Country code
    
    Format: ISO 3166
    
    Provides the country code
    
    Example: isoCountryCode="US"

Selected item

Provides one or more items to start the punchout session with a premade cart

Example

<SelectedItem>
  <ItemID>
    <SupplierPartID>45L017</SupplierPartID>
    <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>
  </ItemID>
</SelectedItem>

Selected item field breakdown

ItemID
Item identifier

Groups the supplier item identifiers
- SupplierPartID Part identifier
  
  Type: String
  
  Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)
  
  Example: <SupplierPartID>45L017</SupplierPartID>
- SupplierPartAuxiliaryID Auxiliary part identifier
  
  Type: String
  
  Provides a unique, additional item identifier, such as to indicate a specific color or packaging option
  
  Example: <SupplierPartAuxiliaryID>CART12-ITEM123</SupplierPartAuxiliaryID>

Response payload (to TradeCentric)

Once your eCommerce platform processes the PunchOutSetupRequest, it should return a PunchOutSetupResponse cXML payload. This payload should provide either a URL to start the punchout session or an error message.

The code block below shows an example PunchOutSetupResponse payload in our standard cXML format:

cXML

HTTP response

PunchOutSetupResponse

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML xml:lang="en-US" payloadID="ID" timestamp="2016-04-03T08:45:48-05:00">
  <Response>
    <Status code="200" text="Ok"/>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>https://connect.punchout2go.com/gateway/punchout/start/id/ABCD1234efg567</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

Response element details

A standard cXML PunchOutSetupResponse payload has a root element and a Response element. The subsections below explain each element and its fields.

cXML root

Required Max use: 1

Applies identifying information to the entire response payload

Example

<cXML xml:lang="en-US" payloadID="ID" timestamp="2016-04-03T08:45:48-05:00">
  ...
</cXML>

Root field breakdown

payloadID

Payload identifier

Required Type: String

Provides a unique identifier for the response

Example: payloadID="ID"
timestamp

Response timestamp

Required Format: ISO 8601

Provides the date and time when the response was created

Example: timestamp="2016-04-03T08:45:48-05:00"
xml:lang

Language

Optional Format: IETF BCP 47

Specifies the language used for the response

Example: xml:lang="en-US"

Response

Required Max use: 1

Provides the success or error details, which are described in the subsections below

Success response

ConditionalMax use: 1

Indicates that the eCommerce platform processed the request successfully and provides the URL to start the punchout session

Example

<Response>
  <Status code="200" text="Ok"/>
  <PunchOutSetupResponse>
    <StartPage>
      <URL>https://connect.punchout2go.com/gateway/punchout/start/id/ABCD1234efg567</URL>
    </StartPage>
  </PunchOutSetupResponse>
</Response>

Success response field breakdown

Status
Response status

Required

Specifies the success status

Example: <Status code="200" text="Ok"/>
- code Status code
  
  Format: HTTP status code
  
  Provides the success status code
  
  Example: code="200"
- text Status text
  
  Type: String
  
  Provides a brief description of the status
  
  Example: text="Ok"
PunchOutSetupResponse
Response action

Required

Provides the start page
- StartPage Start page
  
  Required
  
  Groups the start page information
- URL Start URL
  
  Required Format: protocol://domain/path
  
  Provides the full TradeCentric URL, including the unique session identifier, needed to start the punchout session
  
  Example: <URL>https://connect.punchout2go.com/gateway/punchout/start/id/ABCD1234efg567</URL>

Error response

ConditionalMax use: 1

Indicates that the eCommerce platform failed to process the request and provides an error message

Example

<Response>
  <Status code="400" text="Bad request">Unable to authenticate the user</Status>
</Response>

Error response field breakdown

Status
Response status

Required

Specifies the error status and provides an error message

Example: <Status code="400" text="Bad request">Unable to authenticate the user</Status>
- code Status code
  
  Required Format: HTTP status code
  
  Provides the error status code
  
  Example: code="400"
- text Status text
  
  Required Type: String
  
  Provides a brief description of the error status
  
  Example: text="Bad request"

Request payload (from TradeCentric)

Request element details

cXML root

Session identifier

Payload creation timestamp

Header

Buyer credential

Supplier credential

Sending system credential

Request

Session identification

Deployment mode

Request details

Extrinsic information

Identifier type

Identifier

Return cart URL

Return URL

User contact information

Contact role

Contact name

Contact email address

Shipping information

Shipping address

Selected item

Item identifier

Response payload (to TradeCentric)

Response element details

cXML root

Payload identifier

Response timestamp

Language

Response

Success response

Response status

Response action

Error response

Response status

Related articles