# Connect a buyer Create a buyer credential for an OCI, cXML or IDS Connect buyer system, hand over the launch URL, and restrict where carts may be posted back to. URL: https://punchout.dev/docs/getting-started/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](https://punchout.dev/docs/getting-started/test-punchout/) never counts. [Plans and Sandbox](https://punchout.dev/docs/account/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/` | **OCI launch** | | cXML | `https://api.punchout.dev/v1/cxml/setup/` | **cXML PunchOutSetupRequest** | | IDS Connect | `https://api.punchout.dev/v1/ids/launch/` | **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](https://punchout.dev/docs/getting-started/install-the-tag/)). The [test punchout](https://punchout.dev/docs/getting-started/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](https://punchout.dev/docs/plugins/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](https://punchout.dev/docs/buyer-systems/). On the Sandbox plan, real launches are refused. Run a [test punchout](https://punchout.dev/docs/getting-started/test-punchout/) to check the shop, then choose a paid plan before the buyer's first productive punchout.