PunchOut cXML Integration

This allows B2B buyers using Coupa, Ariba, or other cXML-compatible eProcurement systems to connect seamlessly to a DJUST store, browse products, and return their selection as a structured cart.

🔐 Step 1 – PunchOut Setup Request (Session Initialization)

sequenceDiagram
    participant EProc as 🛒 Buyer (eProcurement)
    participant PunchOut as 🧩 PunchOut Module (Djust)
    participant Backend as 🛠️ Djust Backend
    participant Frontend as 👤 Supplier Catalog (Storefront)

    EProc->>PunchOut: POST PunchOutSetupRequest (cXML)<br>with credentials, buyerCookie, BrowserFormPost
    PunchOut->>Backend: Verifies cXML credentials and tenant key
    Backend-->>PunchOut: OK / Token / Session
    PunchOut->>Frontend: Redirect to the DJUST storefront with session
    Frontend->>Backend: Retrieve customer user data via session
    Backend-->>Frontend: Customer context, prices, buying policies
    Frontend-->>Frontend: Display personalized PunchOut catalog

The session is initialized through a POST call to:

ADM-PUNCHOUT-101 - POST /punchout/cxml/setup/{tenantConfigurationKey}

The tenantConfigurationKey is a secure key assigned to each customer. It must be shared securely with the buyer’s eProcurement platform.

• ✅ On success, the user is redirected to the DJUST storefront with a valid session.
• ❌ On error, DJUST returns an auto-submitting HTML form containing an error code and message, following cXML fallback best practices.

🔐 Authentication

As DJUST does not yet support SSO for PunchOut sessions, authentication is performed using a combination of email and password, embedded in the PunchOutSetupRequest.

• 🧾 Expected Structure

Authentication is done through the cXML header, and the user’s email can be transmitted through several standard locations in the request.

• ✅ Password (Required)

The password must be sent in the following field:

<Sender>
  <Credential domain="...">
    <Identity>...</Identity>
    <SharedSecret>my-password</SharedSecret>
  </Credential>
  ...
</Sender>

• The SharedSecret acts as the user’s password.
• If this value is incorrect, DJUST will return an authentication error page.

• ✅ Email (Required)

DJUST expects the user’s email address to be provided in at least one of the following locations:

All three can be used in parallel. However, for best compatibility:

• Include the email in the Header or Contact object using the email attribute.
• Use the Extrinsic field as a fallback.

<cXML ...>
  <Header>
    <Sender>
      <Credential domain="DUNS">
        <Identity>BUYER-123</Identity>
        <SharedSecret>supersecret123</SharedSecret>
        <Email>[email protected]</Email>
      </Credential>
    </Sender>
  </Header>

  <Request>
    <PunchOutSetupRequest>
      <BuyerCookie>abc-123</BuyerCookie>
      <Contact email="[email protected]">
        <Name xml:lang="en">Jane Doe</Name>
      </Contact>
      <Extrinsic name="UserEmail">[email protected]</Extrinsic>
      ...
    </PunchOutSetupRequest>
  </Request>
</cXML>

Success response - PunchOutSetupResponse (with StartPage)

On a valid setup request and accepted credentials, return Status 200 with a StartPage/URL where the buyer session begins.

<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="[email protected]" timestamp="2024-10-08T12:00:00Z">
  <Response>
    <Status code="200" text="success"></Status>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>https://storefront.example.com/punchout/start?session=abc123</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

Error responses - standard Status codes

Return a cXML <Response> with the appropriate 4xx/5xx code and explanatory text.

<!-- 400 Bad Request: malformed or missing required fields -->
<Response>
  <Status code="400" text="Bad Request: Missing required fields"/>
</Response>

<!-- 401 Unauthorized: invalid credentials -->
<Response>
  <Status code="401" text="Unauthorized: Invalid credentials"/>
</Response>

<!-- 403 Forbidden: tenant not allowed to use PunchOut -->
<Response>
  <Status code="403" text="Forbidden: Access denied for this tenant"/>
</Response>

<!-- 404 Not Found: unknown tenantConfigurationKey -->
<Response>
  <Status code="404" text="Not Found: value {tenantConfigurationKey} does not exist"/>
</Response>

<!-- 500 Internal Server Error -->
<Response>
  <Status code="500" text="Internal Server Error: Unable to process the request"/>
</Response>

<!-- 503 Service Unavailable: temporary outage or maintenance -->
<Response>
  <Status code="503" text="Service Unavailable: Please try again later"/>
</Response>

🛒 Step 2 – Product Selection & PunchOutOrderMessage Return

After browsing the catalog, the buyer selects products and proceeds to checkout. DJUST generates a PunchOutOrderMessage response and redirects the user back to the eProcurement system.

sequenceDiagram
    participant EProc as 🛒 Buyer (eProcurement)
    participant PunchOut as 🧩 PunchOut Module (Djust)
    participant Backend as 🛠️ Djust Backend
    participant Frontend as 👤 Supplier Catalog (Storefront)

    Note right of Frontend: User adds products to cart

    Frontend->>Backend: Update commercial order
    Backend-->>Frontend: Return updated cart

    Frontend->>PunchOut: Generate PunchOutOrderMessage (cXML)
    PunchOut->>EProc: POST form with cXML payload to BrowserFormPost URL

    Note right of EProc: The cart is integrated into the requisition flow

To retrieve the cXML cart payload, the frontend must call:

ADM-PUNCHOUT-502 - GET /punchout/cxml/{tenantConfigurationKey}/commercial-orders/{commercialOrderId}

This returns a valid PunchOutOrderMessage cXML document, like:

<PunchOutOrderMessage>
  <BuyerCookie>abc-123</BuyerCookie>
  <PunchOutOrderMessageHeader operationAllowed="create"/>
  <ItemIn quantity="2">
    <ItemID>
      <SupplierPartID>SKU-456</SupplierPartID>
      <SupplierPartAuxiliaryID>INT-123</SupplierPartAuxiliaryID>
    </ItemID>
    <ItemDetail>
      <UnitPrice>
        <Money currency="EUR">12.50</Money>
      </UnitPrice>
      <Description xml:lang="en">Highlighter Set</Description>
      <UnitOfMeasure>BX</UnitOfMeasure>
      <Classification domain="UNSPSC">44121716</Classification>
      <Extrinsic name="ImageURL">https://djust.io/products/sku-456.jpg</Extrinsic>
    </ItemDetail>
  </ItemIn>
</PunchOutOrderMessage>

❗️

Important

The frontend must wrap this XML in an auto-submitting HTML form and POST it to the BrowserFormPost URL provided by the buyer in the original request.

🧩 Notes

• DJUST supports all standard cXML PunchOut fields, including:
  • BuyerCookie
  • BrowserFormPost
  • SupplierPartID
  • Money, UnitOfMeasure, Classification
  • Extrinsic (configurable per project)
  
  
• Custom fields can be transmitted via <Extrinsic> elements if coordinated with the buyer’s eProcurement system.
• For each PunchOut setup, a dedicated tenantConfigurationKey is used to ensure secure routing and context resolution.
• DJUST handles standard PunchOut errors (bad request, unauthorized, internal error, etc.) using auto-submitted HTML forms containing error metadata.