Connect a buyer

This page explains how to connect a buyer’s procurement system to your shop: the buyer credential, the launch URL and the return hosts.

Buyer credentials

A buyer credential is the login a buyer system uses to start a punchout of your shop. Create one per buyer system with Add buyer on the shop’s Buyers tab. Buyers in the sidebar lists the credentials of all your shops in one table, but you change them on the shop’s own tab.

The Add buyer dialog asks for:

Field	Meaning
Credential domain	Which kind of launch the credential is for. See the table below
Identity	The name the buyer system sends. For OCI and IDS Connect, the username
Label	For you only, for example the customer’s name
Secret	Generate one for me (recommended) or Enter my own, at least 16 characters
Shop customer reference	Optional. The shop account auto-login signs this buyer into

Protocol	Credential domain	Identity	What the buyer system’s administrator enters
OCI	OCI	A username you choose	The username as USERNAME and the secret as PASSWORD in the catalog call
cXML	NetworkID, DUNS, AribaNetworkUserId or Other …	The buyer’s identity in that domain	The domain, the identity and the secret as the shared secret
IDS Connect	IDS	A username you choose	The username and the secret in the craftsman software’s Benutzername and Passwort fields

Some craftsman software packages ask only for the Kundennummer (customer number) and no username. For those, store the customer number as the Identity of the IDS credential.

The OCI parameter names default to USERNAME and PASSWORD. If the buyer system must use other names, change OCI parameter for the username and OCI parameter for the password under General → Advanced settings.

Identity and domain cannot change after creation. For different values, create a new credential.

The secret is shown once

punchout.dev stores the secret only as a one-way hash. The plaintext appears once, in the panel “Secret shown once”, right after Create credential or Rotate secret. Copy it, tick I have saved the secret and click Done. Nobody can display it again, punchout.dev included.

Rotate secret replaces the secret. The old one stops working immediately, so the buyer system needs the new one before its next punchout. Disable keeps the credential but refuses its launches. Delete removes it.

Connections

One enabled buyer credential is one connection. Connections are counted across all shops of your organisation, and your plan sets how many may be enabled at the same time.

Action	Plan limit checked
Create a credential	Yes
Enable a disabled credential	Yes
Disable, rotate, edit or delete	No

If a change would exceed the limit, the portal refuses it and names how many connections your plan allows and how many are already active. Disable a credential you no longer need or, on a paid plan, ask an owner to book additional connections under Settings → Billing. The Sandbox allows one enabled credential so you can prepare a go-live, but it refuses that credential’s launches until the organisation is on a paid plan. The temporary entry of a test punchout never counts. Plans and Sandbox has the details.

Launch URLs

The Embed tab lists the address the buyer system calls under Launch URLs for the buying system:

Protocol	Launch URL	Label on the Embed tab
OCI	https://api.punchout.dev/v1/oci/launch/<shop ID>	OCI launch
cXML	https://api.punchout.dev/v1/cxml/setup/<shop ID>	cXML PunchOutSetupRequest
IDS Connect	https://api.punchout.dev/v1/ids/launch/<shop ID>	IDS Connect Roundtrip-URL

What each launch does:

• OCI. The buyer system opens the URL in the buyer’s browser with GET or POST. Prefer POST, which keeps the password out of the address bar. punchout.dev checks the username and password before your shop opens, then sends the browser to your landing page or, with auto-login, to the shop plugin’s login. Leave FUNCTION empty. Only the classic catalog call is supported, and any other function gets an error page.
• cXML. The buyer system calls the URL from its server with the domain, the identity and the shared secret. punchout.dev checks them and answers with a start page that the buyer system opens in the buyer’s browser.
• IDS Connect. The craftsman software stores the URL as its Roundtrip-URL, without a trailing slash, together with the username and password. punchout.dev checks the cart round trip like an OCI launch. The software cannot send a cart into the shop, open a single article or search for articles; it gets an error for each of these.

Note

OCI also works without a credential, with your shop’s own address as the catalog URL. This route works only with GET, checks no username and cannot sign the buyer in through auto-login. The OCI test punchout uses it. For real buyers, use the launch URL above.

Allowed return hosts

At the end of a punchout, the buyer’s browser hands the cart to a return address that the buyer system sends with the launch. General tab → Allowed return hosts limits where that address may point.

Setting	Effect
Empty	Any http or https host is accepted
procurement.customer.example	Exactly that host
*.customer.example	Any subdomain of customer.example, but not customer.example itself. List the domain separately if it is a return host too

Entries are bare host names, without scheme, port or path. punchout.dev checks the return address when the launch arrives and again at the transfer, so a cart never goes to a host that was removed in between. A launch whose return address is not on the list is refused, and the shop does not open.

Once you know your buyers, list their hosts. The portal also builds the form-action line of the Content Security Policy on the Embed tab from this list (Install the tag). The test punchout returns its cart to https://api.punchout.dev and is checked like any buyer system. Keep api.punchout.dev on the list while you use it, or the portal will not start the test.

Auto-login

With a shop plugin or your own login endpoint, the buyer lands in the shop already signed in to their own customer account and sees their own prices. The Shop customer reference of the credential names that account. Auto-login covers the setup and the security design.

What to send the buyer’s administrator

Protocol	Send
OCI	The OCI launch URL, the username, the secret, and the parameter names if you changed them
cXML	The cXML setup URL, the credential domain, the identity and the secret
IDS Connect	The Roundtrip-URL, the username (or the customer number you stored), and the secret

Send the secret through a different channel from the rest. Ask the administrator for the host name of their return address so you can add it to Allowed return hosts. Step-by-step guides for the buyer’s side are in Buyer systems.

On the Sandbox plan, real launches are refused. Run a test punchout to check the shop, then choose a paid plan before the buyer’s first productive punchout.