StackProcure

How B2B Punchout Works: cXML 1.2, OCI 5.0, and the Cart Round-Trip

By StackProcure Engineering ·

StackProcure is a B2B punchout server. It sits between a corporate buyer's procurement system — Coupa, SAP Ariba, SAP SRM, Prendio, TradeCentric, Oracle, Jaggaer — and your nopCommerce storefront, and it speaks the two protocols those systems use: cXML 1.2 and OCI 5.0.

What 'punchout' actually means

A punchout is a round-trip. The buyer never leaves their approval workflow for long: they punch out from their procurement system into your store, build a cart, and the cart is handed straight back into their system as a pending requisition. No re-keying, no PDF quotes, no email ping-pong.

The four legs

  1. Setup — the buyer's system POSTs a cXML PunchOutSetupRequest to /api/sp/punchout/setup. StackProcure authenticates it against a per-vendor shared secret held in Azure Key Vault, enforces an optional IP allow-list, opens a shopping session, and returns a one-time start URL.
  2. Shop — the buyer's browser is redirected to that URL and lands in your nopCommerce catalog in punchout mode. StackProcure mints a short-lived, HMAC-signed cart token bound to the session.
  3. Transfer — when the buyer clicks Transfer Cart, the store posts the cart to /api/sp/punchout/checkout. StackProcure verifies the cart token (rejecting anything forged, expired, or from a different session) and builds a cXML PunchOutOrderMessage.
  4. Return — that message is posted back to the buyer's system, which pre-fills a requisition. After approval, the buyer's system sends a cXML OrderRequest — the real purchase order — which StackProcure records idempotently as an order.

Why the HMAC cart token matters

A session token alone can leak. The cart token is a separate HMAC-SHA256 signature bound to the exact session, vendor, and buyer, with a 30-minute expiry. Without it, a stolen session id cannot be used to submit a forged cart — the checkout leg fails closed.

OCI 5.0

SAP-style systems use OCI instead of cXML. Same round-trip, different envelope: the setup is a form POST to /oci/setup and the cart returns as an auto-submitting HTML form to the buyer's HOOK_URL. One StackProcure instance serves both protocols from the same catalog.

Every state change — setup, checkout, order, errors, admin kills — is written to an append-only audit log with the actor, client IP, and before/after values. That is the point: a procurement integration your buyers' security teams can actually sign off on.