The buyer rejects your PunchOutSetupResponse
Your endpoint receives the request and answers it. The buyer reports an invalid response, or that there was nowhere to send the shopper.
Three things, in this order. The response must carry <Status code="200" text="OK"/> inside the document rather than relying on the HTTP status; the StartPage URL must be absolute and resolvable from the shopper’s own browser; and the Content-Type must be text/xml, not text/html.
Causes, most likely first
Ordered by how often each one turns out to be the culprit, not by how interesting it is. Work down the list.
-
Errors are signalled with an HTTP status instead of a cXML Status
How to confirm: Your error handler returns an HTTP 4xx or 5xx with your framework’s default error page. The buyer reports an invalid or unparseable response rather than the message you intended to send.
Fix: Return HTTP 200 and put the real outcome in the cXML Status element. Set both attributes — text is required, not decorative. A credential failure is an HTTP 200 carrying Status code="401", which is the form every buyer accepts.
-
The StartPage URL has unescaped ampersands
How to confirm: Your session URL carries query parameters joined with a bare &. Inside XML that makes the document not well-formed, so the parse fails before the URL is ever read, and the error names XML rather than the URL.
Fix: Escape it to &. This is the most common well-formedness failure in setup responses, because the URL is nearly always assembled by string concatenation rather than by the serialiser that writes the rest of the document.
-
The StartPage URL is relative or internal
How to confirm: The value begins with a path, or names a host that only resolves inside your network. It works from your application server and nowhere else.
Fix: Emit an absolute https URL on a publicly resolvable host. The shopper opens this in their own browser, from their own network.
-
The Content-Type is text/html
How to confirm: Run curl -i against the endpoint and read the header. Many frameworks default to HTML and nothing in your code looks wrong.
Fix: Set text/xml; charset=utf-8 explicitly on the response.
-
The payload is in the wrong wrapper
How to confirm: PunchOutSetupResponse belongs inside <Response>. Putting it in <Message>, which is where the later PunchOutOrderMessage goes, produces a parse failure with an unhelpful message.
Fix: Move it into <Response>.
If it is not on your side
Send the buyer the raw response body you emitted, with the session token redacted, together with the Content-Type header you returned. Those two artefacts settle this faster than any description of the problem.
Check the document itself
Paste your cXML or OCI payload into our free tester. It runs entirely in your browser and reports the structural problems buyers reject on.
Open the testerRelated questions
Should an authentication failure be an HTTP 401 or a cXML Status 401?
A cXML Status 401 inside an HTTP 200. Some buyers tolerate the HTTP form, none object to the spec-correct one, so emitting that is how you stop having the conversation at all.
How long should the StartPage URL remain valid?
That is your decision, but assume the shopper does not click immediately — their system may present the link in a requisition they return to later. Decide deliberately whether the URL is single use, and return an explanatory page rather than a blank one when it is reused.
Rather not be the one debugging this?
We build and run the endpoint, and deal with the buyer’s technical team directly. Pricing is published in full.
See pricing Send us the error